• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.account.distributedAccount (分布式账号管理)](js-apis-distributed-account.md)。
16
17## 导入模块
18
19```ts
20import { distributedAccount } from '@kit.BasicServicesKit';
21```
22
23## DistributedAccountAbility
24
25提供查询和更新分布式账号登录状态方法(需要先获取分布式账号的单实例对象)。
26
27### getOsAccountDistributedInfoByLocalId<sup>10+</sup>
28
29getOsAccountDistributedInfoByLocalId(localId: number, callback: AsyncCallback&lt;DistributedInfo&gt;): void
30
31获取指定系统账号的分布式信息。使用callback异步回调。
32
33**系统接口：** 此接口为系统接口。
34
35**系统能力：** SystemCapability.Account.OsAccount
36
37**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS或(ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS与ohos.permission.GET_DISTRIBUTED_ACCOUNTS)
38
39**参数：**
40
41  | 参数名 | 类型 | 必填 | 说明 |
42  | -------- | -------- | -------- | -------- |
43  | localId | number | 是 | 系统账号ID。 |
44  | callback | AsyncCallback&lt;[DistributedInfo](js-apis-distributed-account.md#distributedinfo)&gt; | 是 | 回调参数。当获取分布式账号信息成功，err为undefined，data为获取到的分布式账号信息对象；否则为错误对象。 |
45
46**错误码：**
47
48| 错误码ID | 错误信息|
49| -------- | ------------------- |
50| 201 | Permission denied.|
51| 202 | Not system application.|
52| 12300001 | System service exception. |
53| 12300003 | Account not found. |
54
55**示例：**
56
57```ts
58import { BusinessError } from '@kit.BasicServicesKit';
59
60const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility();
61try {
62  accountAbility.getOsAccountDistributedInfoByLocalId(100,
63    (err: BusinessError, data: distributedAccount.DistributedInfo) => {
64      if (err) {
65        console.error(`getOsAccountDistributedInfoByLocalId exception: code is ${err.code}, message is ${err.message}`);
66      } else {
67        console.info('distributed information: ' + JSON.stringify(data));
68      }
69    });
70} catch (err) {
71  console.error(`getOsAccountDistributedInfoByLocalId exception: code is ${err.code}, message is ${err.message}`);
72}
73```
74
75### getOsAccountDistributedInfoByLocalId<sup>10+</sup>
76
77getOsAccountDistributedInfoByLocalId(localId: number): Promise&lt;DistributedInfo&gt;
78
79获取指定系统账号的分布式信息。使用Promise异步回调。
80
81**系统接口：** 此接口为系统接口。
82
83**系统能力：** SystemCapability.Account.OsAccount
84
85**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS或(ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS与ohos.permission.GET_DISTRIBUTED_ACCOUNTS)
86
87**参数：**
88
89  | 参数名 | 类型 | 必填 | 说明 |
90  | -------- | -------- | -------- | -------- |
91  | localId | number | 是 | 系统账号ID。 |
92
93**返回值：**
94
95  | 类型 | 说明 |
96  | -------- | -------- |
97  | Promise&lt;[DistributedInfo](js-apis-distributed-account.md#distributedinfo)&gt; | Promise对象，返回分布式账号信息对象。 |
98
99**错误码：**
100
101| 错误码ID | 错误信息|
102| -------- | ------------------- |
103| 201 | Permission denied.|
104| 202 | Not system application.|
105| 12300001 | System service exception. |
106| 12300003 | Account not found. |
107
108**示例：**
109
110```ts
111import { BusinessError } from '@kit.BasicServicesKit';
112
113const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility();
114try {
115  accountAbility.getOsAccountDistributedInfoByLocalId(100).then((
116    data: distributedAccount.DistributedInfo) => {
117    console.info('distributed information: ' + JSON.stringify(data));
118  }).catch((err: BusinessError) => {
119    console.error(`getOsAccountDistributedInfoByLocalId exception: code is ${err.code}, message is ${err.message}`);
120  });
121} catch (err) {
122  console.error(`getOsAccountDistributedInfoByLocalId exception: code is ${err.code}, message is ${err.message}`);
123}
124```
125
126### setOsAccountDistributedInfoByLocalId<sup>10+</sup>
127
128setOsAccountDistributedInfoByLocalId(localId: number, distributedInfo: DistributedInfo, callback: AsyncCallback&lt;void&gt;): void
129
130设置指定系统账号的分布式信息。使用callback异步回调。
131
132**系统接口：** 此接口为系统接口。
133
134**系统能力：** SystemCapability.Account.OsAccount
135
136**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS
137
138**参数：**
139
140  | 参数名 | 类型 | 必填 | 说明 |
141  | -------- | -------- | -------- | -------- |
142  | localId | number | 是 | 系统账号ID。 |
143  | distributedInfo | [DistributedInfo](js-apis-distributed-account.md#distributedinfo) | 是 | 分布式账号信息。 |
144  | callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。当设置指定系统账号的分布式信息成功时，err为undefined，否则为错误对象。 |
145
146**错误码：**
147
148| 错误码ID | 错误信息|
149| -------- | ------------------- |
150| 201 | Permission denied.|
151| 202 | Not system application.|
152| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
153| 12300001 | System service exception. |
154| 12300002 | Invalid distributedInfo. |
155| 12300003 | Account identified by localId or by distributedInfo not found. |
156| 12300008 | Restricted OS account. |
157
158**示例：**
159
160```ts
161import { BusinessError } from '@kit.BasicServicesKit';
162
163const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility();
164let accountInfo: distributedAccount.DistributedInfo =
165  {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
166try {
167  accountAbility.setOsAccountDistributedInfoByLocalId(100, accountInfo, (err: BusinessError) => {
168    if (err) {
169      console.error(`setOsAccountDistributedInfoByLocalId exception: code is ${err.code}, message is ${err.message}`);
170    } else {
171      console.info('setOsAccountDistributedInfoByLocalId successfully');
172    }
173  });
174} catch (err) {
175    console.error(`setOsAccountDistributedInfoByLocalId exception: code is ${err.code}, message is ${err.message}`);
176}
177```
178
179### setOsAccountDistributedInfoByLocalId<sup>10+</sup>
180
181setOsAccountDistributedInfoByLocalId(localId: number, distributedInfo: DistributedInfo): Promise&lt;void&gt;
182
183设置指定系统账号的分布式信息。使用Promise异步回调。
184
185**系统接口：** 此接口为系统接口。
186
187**系统能力：** SystemCapability.Account.OsAccount
188
189**需要权限：** ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS
190
191**参数：**
192
193  | 参数名 | 类型 | 必填 | 说明 |
194  | -------- | -------- | -------- | -------- |
195  | localId | number | 是 | 系统账号ID。 |
196  | distributedInfo | [DistributedInfo](js-apis-distributed-account.md#distributedinfo) | 是 | 分布式账号信息。 |
197
198**返回值：**
199
200  | 类型 | 说明 |
201  | -------- | -------- |
202  | Promise&lt;void&gt; | Promise对象，无返回结果的Promise对象。 |
203
204**错误码：**
205
206| 错误码ID | 错误信息|
207| -------- | ------------------- |
208| 201 | Permission denied.|
209| 202 | Not system application.|
210| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. |
211| 12300001 | System service exception. |
212| 12300002 | Invalid distributedInfo. |
213| 12300003 | Account identified by localId or by distributedInfo not found. |
214| 12300008 | Restricted OS account. |
215
216**示例：**
217
218```ts
219import { BusinessError } from '@kit.BasicServicesKit';
220
221const accountAbility: distributedAccount.DistributedAccountAbility = distributedAccount.getDistributedAccountAbility();
222let accountInfo: distributedAccount.DistributedInfo =
223  {id: '12345', name: 'ZhangSan', event: 'Ohos.account.event.LOGIN'};
224try {
225  accountAbility.setOsAccountDistributedInfoByLocalId(100, accountInfo).then(() => {
226      console.info('setOsAccountDistributedInfoByLocalId successfully');
227  }).catch((err: BusinessError) => {
228      console.error(`setOsAccountDistributedInfoByLocalId exception: code is ${err.code}, message is ${err.message}`);
229  });
230} catch (err) {
231    console.error(`setOsAccountDistributedInfoByLocalId exception: code is ${err.code}, message is ${err.message}`);
232}
233```
234