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