1# @ohos.account.distributedAccount (分布式帐号管理) 2 3本模块提供管理分布式帐号的一些基础功能，主要包括查询和更新帐号登录状态。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import account_distributedAccount from '@ohos.account.distributedAccount'; 13``` 14 15## account_distributedAccount.getDistributedAccountAbility 16 17getDistributedAccountAbility(): DistributedAccountAbility 18 19获取分布式帐号单实例对象。 20 21**系统能力：** SystemCapability.Account.OsAccount 22 23**返回值：** 24 25 | 类型 | 说明 | 26 | -------- | -------- | 27 | [DistributedAccountAbility](#distributedaccountability) | 返回一个实例，实例提供查询和更新分布式帐号登录状态方法。 | 28 29**示例：** 30 ```ts 31 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 32 ``` 33 34## DistributedAccountAbility 35 36提供查询和更新分布式帐号登录状态方法(需要先获取分布式帐号的单实例对象)。 37 38### getOsAccountDistributedInfo<sup>9+</sup> 39 40getOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): void 41 42获取分布式帐号信息，使用callback异步回调。 43 44**系统能力：** SystemCapability.Account.OsAccount 45 46**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 或 ohos.permission.GET_DISTRIBUTED_ACCOUNTS 或 ohos.permission.DISTRIBUTED_DATASYNC 47 48**参数：** 49 50 | 参数名 | 类型 | 必填 | 说明 | 51 | -------- | -------- | -------- | -------- | 52 | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | 是 | 回调参数。当获取分布式帐号信息成功，err为undefined，data为获取到的分布式帐号信息对象；否则为错误对象。 | 53 54**错误码：** 55 56| 错误码ID | 错误信息| 57| -------- | ------------------- | 58| 12300001 | System service exception. | 59 60**示例：** 61 ```ts 62 import { BusinessError } from '@ohos.base'; 63 64 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 65 try { 66 accountAbility.getOsAccountDistributedInfo( 67 (err: BusinessError, data: account_distributedAccount.DistributedInfo) => { 68 if (err) { 69 console.log('getOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 70 } else { 71 console.log('distributed information: ' + JSON.stringify(data)); 72 } 73 }); 74 } catch (err) { 75 console.log('getOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 76 } 77 ``` 78 79### getOsAccountDistributedInfo<sup>9+</sup> 80 81getOsAccountDistributedInfo(): Promise<DistributedInfo> 82 83获取分布式帐号信息。使用Promise异步回调。 84 85**系统能力：** SystemCapability.Account.OsAccount 86 87**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 或 ohos.permission.GET_DISTRIBUTED_ACCOUNTS 或 ohos.permission.DISTRIBUTED_DATASYNC 88 89**返回值：** 90 91 | 类型 | 说明 | 92 | -------- | -------- | 93 | Promise<[DistributedInfo](#distributedinfo)> | Promise对象，返回分布式帐号信息对象。 | 94 95**错误码：** 96 97| 错误码ID | 错误信息| 98| -------- | ------------------- | 99| 12300001 | System service exception. | 100 101**示例：** 102 ```ts 103 import { BusinessError } from '@ohos.base'; 104 105 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 106 try { 107 accountAbility.getOsAccountDistributedInfo().then((data: account_distributedAccount.DistributedInfo) => { 108 console.log('distributed information: ' + JSON.stringify(data)); 109 }).catch((err: BusinessError) => { 110 console.log('getOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 111 }); 112 } catch (err) { 113 console.log('getOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 114 } 115 ``` 116 117### queryOsAccountDistributedInfo<sup>(deprecated)</sup> 118 119queryOsAccountDistributedInfo(callback: AsyncCallback<DistributedInfo>): void 120 121获取分布式帐号信息。使用callback异步回调。 122> **说明：** 123> 124> 从 API version 7开始支持，从API version 9开始废弃。建议使用[getOsAccountDistributedInfo](#getosaccountdistributedinfo9)。 125 126**系统能力：** SystemCapability.Account.OsAccount 127 128**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.DISTRIBUTED_DATASYNC 129 130**参数：** 131 132 | 参数名 | 类型 | 必填 | 说明 | 133 | -------- | -------- | -------- | -------- | 134 | callback | AsyncCallback<[DistributedInfo](#distributedinfo)> | 是 | 回调函数。当获取分布式帐号信息成功，err为undefined，data为获取到的分布式帐号信息对象；否则为错误对象。 | 135 136**示例：** 137 ```ts 138 import { BusinessError } from '@ohos.base'; 139 140 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 141 accountAbility.queryOsAccountDistributedInfo( 142 (err: BusinessError, data: account_distributedAccount.DistributedInfo) => { 143 if (err) { 144 console.log('queryOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 145 } else { 146 console.log('distributed information: ' + JSON.stringify(data)); 147 } 148 }); 149 ``` 150 151### queryOsAccountDistributedInfo<sup>(deprecated)</sup> 152 153queryOsAccountDistributedInfo(): Promise<DistributedInfo> 154 155获取分布式帐号信息。使用Promise异步回调。 156 157> **说明：** 158> 159> 从 API version 7开始支持，从API version 9开始废弃。建议使用[getOsAccountDistributedInfo](#getosaccountdistributedinfo9-1)。 160 161**系统能力：** SystemCapability.Account.OsAccount 162 163**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.DISTRIBUTED_DATASYNC 164 165**返回值：** 166 167 | 类型 | 说明 | 168 | -------- | -------- | 169 | Promise<[DistributedInfo](#distributedinfo)> | Promise对象，返回分布式帐号信息对象。 | 170 171**示例：** 172 ```ts 173 import { BusinessError } from '@ohos.base'; 174 175 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 176 accountAbility.queryOsAccountDistributedInfo().then((data: account_distributedAccount.DistributedInfo) => { 177 console.log('distributed information: ' + JSON.stringify(data)); 178 }).catch((err: BusinessError) => { 179 console.log('queryOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 180 }); 181 ``` 182 183### setOsAccountDistributedInfo<sup>9+</sup> 184 185setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback<void>): void 186 187更新分布式帐号信息。使用callback异步回调。 188 189**系统能力：** SystemCapability.Account.OsAccount 190 191**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 192 193**参数：** 194 195 | 参数名 | 类型 | 必填 | 说明 | 196 | -------- | -------- | -------- | -------- | 197 | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 | 198 | callback | AsyncCallback<void> | 是 | 回调函数。当更新分布式帐号信息成功时，err为undefined，否则为错误对象。 | 199 200**错误码：** 201 202| 错误码ID | 错误信息| 203| -------- | ------------------- | 204| 12300001 | System service exception. | 205| 12300002 | Invalid accountInfo. | 206| 12300003 | Account not found. | 207 208**示例：** 209 ```ts 210 import { BusinessError } from '@ohos.base'; 211 212 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 213 let accountInfo: account_distributedAccount.DistributedInfo = 214 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 215 try { 216 accountAbility.setOsAccountDistributedInfo(accountInfo, (err: BusinessError) => { 217 if (err) { 218 console.log('setOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 219 } else { 220 console.log('setOsAccountDistributedInfo successfully'); 221 } 222 }); 223 } catch (err) { 224 console.log('setOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 225 } 226 ``` 227 228### setOsAccountDistributedInfo<sup>9+</sup> 229 230setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> 231 232更新分布式帐号信息。使用Promise异步回调。 233 234**系统能力：** SystemCapability.Account.OsAccount 235 236**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 237 238**参数：** 239 240 | 参数名 | 类型 | 必填 | 说明 | 241 | -------- | -------- | -------- | -------- | 242 | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐户信息。 | 243 244**返回值：** 245 246 | 类型 | 说明 | 247 | -------- | -------- | 248 | Promise<void> | Promise对象，无返回结果的Promise对象。 | 249 250**错误码：** 251 252| 错误码ID | 错误信息| 253| -------- | ------------------- | 254| 12300001 | System service exception. | 255| 12300002 | Invalid accountInfo. | 256| 12300003 | Account not found. | 257 258**示例：** 259 ```ts 260 import { BusinessError } from '@ohos.base'; 261 262 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 263 let accountInfo: account_distributedAccount.DistributedInfo = 264 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 265 try { 266 accountAbility.setOsAccountDistributedInfo(accountInfo).then(() => { 267 console.log('setOsAccountDistributedInfo successfully'); 268 }).catch((err: BusinessError) => { 269 console.log('setOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 270 }); 271 } catch (err) { 272 console.log('setOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 273 } 274 ``` 275 276### updateOsAccountDistributedInfo<sup>(deprecated)</sup> 277 278updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback<void>): void 279 280更新分布式帐号信息。使用callback异步回调。 281 282> **说明：** 283> 284> 从 API version 7开始支持，从API version 9开始废弃。建议使用[setOsAccountDistributedInfo](#setosaccountdistributedinfo9)。 285 286**系统能力：** SystemCapability.Account.OsAccount 287 288**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 289 290**参数：** 291 292 | 参数名 | 类型 | 必填 | 说明 | 293 | -------- | -------- | -------- | -------- | 294 | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 | 295 | callback | AsyncCallback<void> | 是 | 回调函数。当更新分布式帐号信息成功时，err为undefined，否则为错误对象。 | 296 297**示例：** 298 ```ts 299 import { BusinessError } from '@ohos.base'; 300 301 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 302 let accountInfo: account_distributedAccount.DistributedInfo = 303 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 304 accountAbility.updateOsAccountDistributedInfo(accountInfo, (err: BusinessError) => { 305 if (err) { 306 console.log('queryOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 307 } else { 308 console.log('queryOsAccountDistributedInfo successfully'); 309 } 310 }); 311 ``` 312 313### updateOsAccountDistributedInfo<sup>(deprecated)</sup> 314 315updateOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise<void> 316 317更新分布式帐号信息。使用Promise异步回调。 318> **说明：** 319> 320> 从 API version 7开始支持，从API version 9开始废弃。建议使用[setOsAccountDistributedInfo](#setosaccountdistributedinfo9-1)。 321**系统能力：** SystemCapability.Account.OsAccount 322 323**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 324 325**参数：** 326 327 | 参数名 | 类型 | 必填 | 说明 | 328 | -------- | -------- | -------- | -------- | 329 | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐户信息。 | 330 331**返回值：** 332 333 | 类型 | 说明 | 334 | -------- | -------- | 335 | Promise<void> | Promise对象，无返回结果的Promise对象。 | 336 337**示例：** 338 ```ts 339 import { BusinessError } from '@ohos.base'; 340 341 const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility(); 342 let accountInfo: account_distributedAccount.DistributedInfo = 343 {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'}; 344 accountAbility.updateOsAccountDistributedInfo(accountInfo).then(() => { 345 console.log('updateOsAccountDistributedInfo successfully'); 346 }).catch((err: BusinessError) => { 347 console.log('updateOsAccountDistributedInfo exception: ' + JSON.stringify(err)); 348 }); 349 ``` 350 351## DistributedInfo 352 353提供操作系统帐号的分布式信息。 354 355**系统能力：** SystemCapability.Account.OsAccount 356 357| 名称 | 类型 | 必填 | 说明 | 358| -------- | -------- | -------- | -------- | 359| name | string |是 | 分布式帐号名称，非空字符串。 | 360| id | string |是 | 分布式帐号UID，非空字符串。 | 361| event | string |是 | 分布式帐号登录状态，包括登录、登出、Token失效和注销，分别对应以下字符串：<br/>- Ohos.account.event.LOGIN<br/>- Ohos.account.event.LOGOUT<br/>- Ohos.account.event.TOKEN_INVALID<br/>- Ohos.account.event.LOGOFF | 362| nickname<sup>9+</sup> | string |否 | 分布式帐号的昵称，默认为空。 | 363| avatar<sup>9+</sup> | string |否 | 分布式帐号的头像，默认为空。 | 364| status<sup>10+</sup> | [DistributedAccountStatus](#distributedaccountstatus10) |否 | 分布式帐号的状态，枚举类型，默认为未登录状态。 | 365| scalableData<sup>8+</sup> | object |否 | 分布式帐号扩展信息，根据业务所需，以k-v形式传递定制化信息，默认为空。| 366 367## DistributedAccountStatus<sup>10+</sup> 368 369表示分布式帐号状态枚举。 370 371**系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount 372 373| 名称 | 值 | 说明 | 374| ---- | ------ | ----------- | 375| NOT_LOGGED_IN | 0 | 未登录状态。 | 376| LOGGED_IN | 1 | 已登录状态。 | 377