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