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