• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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&lt;DistributedInfo&gt;): 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&lt;[DistributedInfo](#distributedinfo)&gt; | 是 | 回调参数。当获取分布式帐号信息成功，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&lt;DistributedInfo&gt;
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&lt;[DistributedInfo](#distributedinfo)&gt; | 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### getOsAccountDistributedInfoByLocalId<sup>10+</sup>
118
119getOsAccountDistributedInfoByLocalId(localId: number, callback: AsyncCallback&lt;DistributedInfo&gt;): void
120
121获取指定系统帐号的分布式信息。使用callback异步回调。
122
123**系统接口：** 此接口为系统接口。
124
125**系统能力：** SystemCapability.Account.OsAccount
126
127**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
128
129**参数：**
130
131  | 参数名 | 类型 | 必填 | 说明 |
132  | -------- | -------- | -------- | -------- |
133  | localId | number | 是 | 系统帐号ID。 |
134  | callback | AsyncCallback&lt;[DistributedInfo](#distributedinfo)&gt; | 是 | 回调参数。当获取分布式帐号信息成功，err为undefined，data为获取到的分布式帐号信息对象；否则为错误对象。 |
135
136**错误码：**
137
138| 错误码ID | 错误信息|
139| -------- | ------------------- |
140| 12300001 | System service exception. |
141| 12300003 | Account not found. |
142
143**示例：**
144  ```ts
145  import { BusinessError } from '@ohos.base';
146
147  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
148  try {
149    accountAbility.getOsAccountDistributedInfoByLocalId(100,
150      (err: BusinessError, data: account_distributedAccount.DistributedInfo) => {
151        if (err) {
152          console.log('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
153        } else {
154          console.log('distributed information: ' + JSON.stringify(data));
155        }
156      });
157  } catch (err) {
158    console.log('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
159  }
160  ```
161
162### getOsAccountDistributedInfoByLocalId<sup>10+</sup>
163
164getOsAccountDistributedInfoByLocalId(localId: number): Promise&lt;DistributedInfo&gt;
165
166获取指定系统帐号的分布式信息。使用Promise异步回调。
167
168**系统接口：** 此接口为系统接口。
169
170**系统能力：** SystemCapability.Account.OsAccount
171
172**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS 或 ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
173
174**返回值：**
175
176  | 类型 | 说明 |
177  | -------- | -------- |
178  | Promise&lt;[DistributedInfo](#distributedinfo)&gt; | Promise对象，返回分布式帐号信息对象。 |
179
180**错误码：**
181
182| 错误码ID | 错误信息|
183| -------- | ------------------- |
184| 12300001 | System service exception. |
185| 12300003 | Account not found. |
186
187**示例：**
188  ```ts
189  import { BusinessError } from '@ohos.base';
190
191  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
192  try {
193    accountAbility.getOsAccountDistributedInfoByLocalId(100).then((
194      data: account_distributedAccount.DistributedInfo) => {
195      console.log('distributed information: ' + JSON.stringify(data));
196    }).catch((err: BusinessError) => {
197      console.log('getOsAccountDistributedInfoByLocalId exception: '  + JSON.stringify(err));
198    });
199  } catch (err) {
200    console.log('getOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
201  }
202  ```
203
204### queryOsAccountDistributedInfo<sup>(deprecated)</sup>
205
206queryOsAccountDistributedInfo(callback: AsyncCallback&lt;DistributedInfo&gt;): void
207
208获取分布式帐号信息。使用callback异步回调。
209> **说明：**
210>
211> 从 API version 7开始支持，从API version 9开始废弃。建议使用[getOsAccountDistributedInfo](#getosaccountdistributedinfo9)。
212
213**系统能力：** SystemCapability.Account.OsAccount
214
215**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.DISTRIBUTED_DATASYNC
216
217**参数：**
218
219  | 参数名 | 类型 | 必填 | 说明 |
220  | -------- | -------- | -------- | -------- |
221  | callback | AsyncCallback&lt;[DistributedInfo](#distributedinfo)&gt; | 是 | 回调函数。当获取分布式帐号信息成功，err为undefined，data为获取到的分布式帐号信息对象；否则为错误对象。 |
222
223**示例：**
224  ```ts
225  import { BusinessError } from '@ohos.base';
226
227  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
228  accountAbility.queryOsAccountDistributedInfo(
229    (err: BusinessError, data: account_distributedAccount.DistributedInfo) => {
230      if (err) {
231        console.log('queryOsAccountDistributedInfo exception: ' + JSON.stringify(err));
232      } else {
233        console.log('distributed information: ' + JSON.stringify(data));
234      }
235    });
236  ```
237
238### queryOsAccountDistributedInfo<sup>(deprecated)</sup>
239
240queryOsAccountDistributedInfo(): Promise&lt;DistributedInfo&gt;
241
242获取分布式帐号信息。使用Promise异步回调。
243
244> **说明：**
245>
246> 从 API version 7开始支持，从API version 9开始废弃。建议使用[getOsAccountDistributedInfo](#getosaccountdistributedinfo9-1)。
247
248**系统能力：** SystemCapability.Account.OsAccount
249
250**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS 或 ohos.permission.DISTRIBUTED_DATASYNC
251
252**返回值：**
253
254  | 类型 | 说明 |
255  | -------- | -------- |
256  | Promise&lt;[DistributedInfo](#distributedinfo)&gt; | Promise对象，返回分布式帐号信息对象。 |
257
258**示例：**
259  ```ts
260  import { BusinessError } from '@ohos.base';
261
262  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
263  accountAbility.queryOsAccountDistributedInfo().then((data: account_distributedAccount.DistributedInfo) => {
264      console.log('distributed information: ' + JSON.stringify(data));
265  }).catch((err: BusinessError) => {
266      console.log('queryOsAccountDistributedInfo exception: '  + JSON.stringify(err));
267  });
268  ```
269
270### setOsAccountDistributedInfo<sup>9+</sup>
271
272setOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback&lt;void&gt;): void
273
274更新分布式帐号信息。使用callback异步回调。
275
276**系统能力：** SystemCapability.Account.OsAccount
277
278**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS
279
280**参数：**
281
282  | 参数名 | 类型 | 必填 | 说明 |
283  | -------- | -------- | -------- | -------- |
284  | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 |
285  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当更新分布式帐号信息成功时，err为undefined，否则为错误对象。 |
286
287**错误码：**
288
289| 错误码ID | 错误信息|
290| -------- | ------------------- |
291| 12300001 | System service exception. |
292| 12300002 | Invalid accountInfo. |
293| 12300003 | Account not found. |
294
295**示例：**
296  ```ts
297  import { BusinessError } from '@ohos.base';
298
299  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
300  let accountInfo: account_distributedAccount.DistributedInfo =
301    {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
302  try {
303    accountAbility.setOsAccountDistributedInfo(accountInfo, (err: BusinessError) => {
304      if (err) {
305        console.log('setOsAccountDistributedInfo exception: ' + JSON.stringify(err));
306      } else {
307        console.log('setOsAccountDistributedInfo successfully');
308      }
309    });
310  } catch (err) {
311      console.log('setOsAccountDistributedInfo exception: ' + JSON.stringify(err));
312  }
313  ```
314
315### setOsAccountDistributedInfo<sup>9+</sup>
316
317setOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise&lt;void&gt;
318
319更新分布式帐号信息。使用Promise异步回调。
320
321**系统能力：** SystemCapability.Account.OsAccount
322
323**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS
324
325**参数：**
326
327  | 参数名 | 类型 | 必填 | 说明 |
328  | -------- | -------- | -------- | -------- |
329  | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐户信息。 |
330
331**返回值：**
332
333  | 类型 | 说明 |
334  | -------- | -------- |
335  | Promise&lt;void&gt; | Promise对象，无返回结果的Promise对象。 |
336
337**错误码：**
338
339| 错误码ID | 错误信息|
340| -------- | ------------------- |
341| 12300001 | System service exception. |
342| 12300002 | Invalid accountInfo. |
343| 12300003 | Account not found. |
344
345**示例：**
346  ```ts
347  import { BusinessError } from '@ohos.base';
348
349  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
350  let accountInfo: account_distributedAccount.DistributedInfo =
351    {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
352  try {
353    accountAbility.setOsAccountDistributedInfo(accountInfo).then(() => {
354        console.log('setOsAccountDistributedInfo successfully');
355    }).catch((err: BusinessError) => {
356        console.log('setOsAccountDistributedInfo exception: '  + JSON.stringify(err));
357    });
358  } catch (err) {
359      console.log('setOsAccountDistributedInfo exception: ' + JSON.stringify(err));
360  }
361  ```
362### setOsAccountDistributedInfoByLocalId<sup>10+</sup>
363
364setOsAccountDistributedInfoByLocalId(localId: number, distributedInfo: DistributedInfo, callback: AsyncCallback&lt;void&gt;): void
365
366设置指定系统帐号的分布式信息。使用callback异步回调。
367
368**系统接口：** 此接口为系统接口。
369
370**系统能力：** SystemCapability.Account.OsAccount
371
372**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS
373
374**参数：**
375
376  | 参数名 | 类型 | 必填 | 说明 |
377  | -------- | -------- | -------- | -------- |
378  | localId | number | 是 | 系统帐号ID。 |
379  | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 |
380  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当设置指定系统帐号的分布式信息成功时，err为undefined，否则为错误对象。 |
381
382**错误码：**
383
384| 错误码ID | 错误信息|
385| -------- | ------------------- |
386| 12300001 | System service exception. |
387| 12300002 | Invalid distributedInfo. |
388| 12300003 | Account identified by localId or by distributedInfo not found. |
389| 12300008 | Restricted OS account. |
390
391**示例：**
392  ```ts
393  import { BusinessError } from '@ohos.base';
394
395  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
396  let accountInfo: account_distributedAccount.DistributedInfo =
397    {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
398  try {
399    accountAbility.setOsAccountDistributedInfoByLocalId(100, accountInfo, (err: BusinessError) => {
400      if (err) {
401        console.log('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
402      } else {
403        console.log('setOsAccountDistributedInfoByLocalId successfully');
404      }
405    });
406  } catch (err) {
407      console.log('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
408  }
409  ```
410
411### setOsAccountDistributedInfoByLocalId<sup>10+</sup>
412
413setOsAccountDistributedInfoByLocalId(localId: number, distributedInfo: DistributedInfo): Promise&lt;void&gt;
414
415设置指定系统帐号的分布式信息。使用Promise异步回调。
416
417**系统接口：** 此接口为系统接口。
418
419**系统能力：** SystemCapability.Account.OsAccount
420
421**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS
422
423**参数：**
424
425  | 参数名 | 类型 | 必填 | 说明 |
426  | -------- | -------- | -------- | -------- |
427  | localId | number | 是 | 系统帐号ID。 |
428  | distributedInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐户信息。 |
429
430**返回值：**
431
432  | 类型 | 说明 |
433  | -------- | -------- |
434  | Promise&lt;void&gt; | Promise对象，无返回结果的Promise对象。 |
435
436**错误码：**
437
438| 错误码ID | 错误信息|
439| -------- | ------------------- |
440| 12300001 | System service exception. |
441| 12300002 | Invalid distributedInfo. |
442| 12300003 | Account identified by localId or by distributedInfo not found. |
443| 12300008 | Restricted OS account. |
444
445**示例：**
446  ```ts
447  import { BusinessError } from '@ohos.base';
448
449  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
450  let accountInfo: account_distributedAccount.DistributedInfo =
451    {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
452  try {
453    accountAbility.setOsAccountDistributedInfoByLocalId(100, accountInfo).then(() => {
454        console.log('setOsAccountDistributedInfoByLocalId successfully');
455    }).catch((err: BusinessError) => {
456        console.log('setOsAccountDistributedInfoByLocalId exception: '  + JSON.stringify(err));
457    });
458  } catch (err) {
459      console.log('setOsAccountDistributedInfoByLocalId exception: ' + JSON.stringify(err));
460  }
461  ```
462
463### updateOsAccountDistributedInfo<sup>(deprecated)</sup>
464
465updateOsAccountDistributedInfo(accountInfo: DistributedInfo, callback: AsyncCallback&lt;void&gt;): void
466
467更新分布式帐号信息。使用callback异步回调。
468
469> **说明：**
470>
471> 从 API version 7开始支持，从API version 9开始废弃。建议使用[setOsAccountDistributedInfo](#setosaccountdistributedinfo9)。
472
473**系统能力：** SystemCapability.Account.OsAccount
474
475**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS
476
477**参数：**
478
479  | 参数名 | 类型 | 必填 | 说明 |
480  | -------- | -------- | -------- | -------- |
481  | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐号信息。 |
482  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当更新分布式帐号信息成功时，err为undefined，否则为错误对象。 |
483
484**示例：**
485  ```ts
486  import { BusinessError } from '@ohos.base';
487
488  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
489  let accountInfo: account_distributedAccount.DistributedInfo =
490    {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
491  accountAbility.updateOsAccountDistributedInfo(accountInfo, (err: BusinessError) => {
492    if (err) {
493      console.log('queryOsAccountDistributedInfo exception: ' + JSON.stringify(err));
494    } else {
495      console.log('queryOsAccountDistributedInfo successfully');
496    }
497  });
498  ```
499
500### updateOsAccountDistributedInfo<sup>(deprecated)</sup>
501
502updateOsAccountDistributedInfo(accountInfo: DistributedInfo): Promise&lt;void&gt;
503
504更新分布式帐号信息。使用Promise异步回调。
505> **说明：**
506>
507> 从 API version 7开始支持，从API version 9开始废弃。建议使用[setOsAccountDistributedInfo](#setosaccountdistributedinfo9-1)。
508**系统能力：** SystemCapability.Account.OsAccount
509
510**需要权限：** ohos.permission.MANAGE_LOCAL_ACCOUNTS
511
512**参数：**
513
514  | 参数名 | 类型 | 必填 | 说明 |
515  | -------- | -------- | -------- | -------- |
516  | accountInfo | [DistributedInfo](#distributedinfo) | 是 | 分布式帐户信息。 |
517
518**返回值：**
519
520  | 类型 | 说明 |
521  | -------- | -------- |
522  | Promise&lt;void&gt; | Promise对象，无返回结果的Promise对象。 |
523
524**示例：**
525  ```ts
526  import { BusinessError } from '@ohos.base';
527
528  const accountAbility: account_distributedAccount.DistributedAccountAbility = account_distributedAccount.getDistributedAccountAbility();
529  let accountInfo: account_distributedAccount.DistributedInfo =
530    {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
531  accountAbility.updateOsAccountDistributedInfo(accountInfo).then(() => {
532      console.log('updateOsAccountDistributedInfo successfully');
533   }).catch((err: BusinessError) => {
534      console.log('updateOsAccountDistributedInfo exception: '  + JSON.stringify(err));
535  });
536  ```
537## DistributedInfo
538
539提供操作系统帐号的分布式信息。
540
541**系统能力：** SystemCapability.Account.OsAccount
542
543| 名称 | 类型 | 必填 | 说明 |
544| -------- | -------- | -------- | -------- |
545| name | string |是 | 分布式帐号名称，非空字符串。 |
546| id | string |是 | 分布式帐号UID，非空字符串。 |
547| event | string |是 | 分布式帐号登录状态，包括登录、登出、Token失效和注销，分别对应以下字符串：<br/>-&nbsp;Ohos.account.event.LOGIN<br/>-&nbsp;Ohos.account.event.LOGOUT<br/>-&nbsp;Ohos.account.event.TOKEN_INVALID<br/>-&nbsp;Ohos.account.event.LOGOFF |
548| nickname<sup>9+</sup> | string |否 | 分布式帐号的昵称，默认为空。 |
549| avatar<sup>9+</sup> | string |否 | 分布式帐号的头像，默认为空。 |
550| status<sup>10+</sup> | [DistributedAccountStatus](#distributedaccountstatus10) |否 | 分布式帐号的状态，枚举类型，默认为未登录状态。 |
551| scalableData<sup>8+</sup> | object |否 | 分布式帐号扩展信息，根据业务所需，以k-v形式传递定制化信息，默认为空。|
552
553## DistributedAccountStatus<sup>10+</sup>
554
555表示分布式帐号状态枚举。
556
557**系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.OsAccount
558
559| 名称  | 值 | 说明        |
560| ---- | ------ | ----------- |
561| NOT_LOGGED_IN   | 0  | 未登录状态。 |
562| LOGGED_IN  | 1  | 已登录状态。 |
563