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