• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.bundle.appControl (appControl模块)
2
3本模块提供应用拦截能力。对应用设置处置状态后，应用会被禁止运行；用户点击桌面图标时，会根据应用的处置状态，跳转到对应的页面。本模块支持对应用的处置状态进行设置、获取、删除。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9本模块接口为系统接口。
10
11## 导入模块
12
13``` ts
14import appControl from '@ohos.bundle.appControl'
15```
16
17## appControl.setDisposedStatus
18
19setDisposedStatus(appId: string, disposedWant: Want): Promise\<void>
20
21以异步方法设置应用的处置状态。使用Promise异步回调。成功返回null，失败返回对应错误信息。
22
23**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
24
25**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
26
27**系统API：**  此接口为系统接口。
28
29**参数：**
30
31| 参数名       | 类型     | 必填   | 说明                                    |
32| ----------- | ------ | ---- | --------------------------------------- |
33| appId  | string | 是    | 需要设置处置状态的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。               |
34| disposedWant | Want  | 是 | 对应用的处置意图。 |
35
36**返回值：**
37
38| 类型                        | 说明                 |
39| ------------------------- | ------------------ |
40| Promise\<void> | Promise对象。无返回结果的Promise对象。 |
41
42**错误码：**
43
44以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
45
46| 错误码ID | 错误信息                                |
47| ------ | -------------------------------------- |
48| 17700005 |  The specified app ID is empty string.  |
49
50**示例：**
51
52```ts
53import { BusinessError } from '@ohos.base';
54import Want from '@ohos.app.ability.Want';
55import appControl from '@ohos.bundle.appControl';
56
57let appId = "com.example.myapplication_xxxxx";
58let want:Want = {bundleName: 'com.example.myapplication'};
59
60try {
61    appControl.setDisposedStatus(appId, want)
62        .then(() => {
63            console.info('setDisposedStatus success');
64        }).catch((error: BusinessError) => {
65            let message = (error as BusinessError).message;
66            console.error('setDisposedStatus failed ' + message);
67        });
68} catch (error) {
69    let message = (error as BusinessError).message;
70    console.error('setDisposedStatus failed ' + message);
71}
72```
73
74## appControl.setDisposedStatus
75
76setDisposedStatus(appId: string, disposedWant: Want, callback: AsyncCallback\<void>): void;
77
78以异步方法设置应用的处置状态。使用callback异步回调。成功返回null，失败返回对应错误信息。
79
80**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
81
82**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
83
84**系统API：**  此接口为系统接口。
85
86**参数：**
87
88| 参数名       | 类型                              | 必填   | 说明                                    |
89| ----------- | ------------------------------- | ---- | --------------------------------------- |
90| appId  | string | 是    | 需要设置处置的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。                      |
91| disposedWant | Want  | 是 | 对应用的处置意图。 |
92| callback    | AsyncCallback\<void> | 是    | 回调函数，当设置处置状态成功，err为null，否则为错误对象。 |
93
94**错误码：**
95
96以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
97
98| 错误码ID | 错误信息                                |
99| ------ | -------------------------------------- |
100| 17700005 |  The specified app ID is empty string.  |
101
102**示例：**
103
104```ts
105import appControl from '@ohos.bundle.appControl';
106import { BusinessError } from '@ohos.base';
107import Want from '@ohos.app.ability.Want';
108
109let appId = "com.example.myapplication_xxxxx";
110let want: Want = {bundleName: 'com.example.myapplication'};
111
112try {
113  appControl.setDisposedStatus(appId, want, (error: BusinessError, data) => {
114    if (error) {
115      let message = (error as BusinessError).message;
116      console.error('setDisposedStatus failed ' + message);
117      return;
118    }
119    console.info('setDisposedStatus success');
120  });
121} catch (error) {
122    let message = (error as BusinessError).message;
123    console.error('setDisposedStatus failed ' + message);
124}
125```
126
127## appControl.setDisposedStatusSync<sup>10+</sup>
128
129setDisposedStatusSync(appId: string, disposedWant: Want): void;
130
131以同步方法设置应用的处置状态。成功返回null，失败抛出对应异常。
132
133**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
134
135**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
136
137**系统API：**  此接口为系统接口。
138
139**参数：**
140
141| 参数名       | 类型                              | 必填   | 说明                                    |
142| ----------- | ------------------------------- | ---- | --------------------------------------- |
143| appId  | string | 是    | 需要设置处置的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。                      |
144| disposedWant | Want  | 是 | 对应用的处置意图。 |
145
146**错误码：**
147
148以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
149
150| 错误码ID | 错误信息                                |
151| ------ | -------------------------------------- |
152| 17700005 |  The specified app ID is empty string.  |
153
154**示例：**
155
156```ts
157import appControl from '@ohos.bundle.appControl';
158import { BusinessError } from '@ohos.base';
159import Want from '@ohos.app.ability.Want';
160
161let appId: string = "com.example.myapplication_xxxxx";
162let want: Want = {bundleName: 'com.example.myapplication'};
163
164try {
165  appControl.setDisposedStatusSync(appId, want);
166} catch (error) {
167  let message = (error as BusinessError).message;
168  console.error('setDisposedStatusSync failed ' + message);
169}
170```
171
172## appControl.getDisposedStatus
173
174getDisposedStatus(appId: string): Promise\<Want>;
175
176以异步方法获取指定应用已设置的处置状态。使用Promise异步回调，成功返回应用的处置状态，失败返回对应错误信息。
177
178**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
179
180**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
181
182**系统API：**  此接口为系统接口。
183
184**参数：**
185
186| 参数名       | 类型     | 必填   | 说明                                    |
187| ----------- | ------ | ---- | --------------------------------------- |
188| appId  | string | 是    | 要查询的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。  |
189
190**返回值：**
191
192| 类型                        | 说明                 |
193| ------------------------- | ------------------ |
194| Promise\<Want> | Promise对象，返回应用的处置状态。 |
195
196**错误码：**
197
198以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
199
200| 错误码ID | 错误信息                                |
201| ------ | -------------------------------------- |
202| 17700005 |  The specified app ID is empty string.  |
203
204**示例：**
205
206```ts
207import appControl from '@ohos.bundle.appControl';
208import { BusinessError } from '@ohos.base';
209
210let appId = "com.example.myapplication_xxxxx";
211
212try {
213  appControl.getDisposedStatus(appId)
214    .then((data) => {
215      console.info('getDisposedStatus success. DisposedStatus: ' + JSON.stringify(data));
216    }).catch((error: BusinessError) => {
217    let message = (error as BusinessError).message;
218    console.error('getDisposedStatus failed ' + message);
219  });
220} catch (error) {
221    let message = (error as BusinessError).message;
222    console.error('getDisposedStatus failed ' + message);
223}
224```
225
226## appControl.getDisposedStatus
227
228getDisposedStatus(appId: string, callback: AsyncCallback\<Want>): void;
229
230以异步方法获取指定应用的处置状态。使用callback异步回调，成功返回应用的处置状态，失败返回对应错误信息。
231
232**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
233
234**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
235
236**系统API：**  此接口为系统接口。
237
238**参数：**
239
240| 参数名       | 类型     | 必填   | 说明                                  |
241| ----------- | ------ | ---- | --------------------------------------- |
242| appId  | string | 是    | 要查询的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。  |
243| callback    | AsyncCallback\<Want> | 是    | 回调函数。当获取应用的处置状态成功时，err为null，data为获取到的处置状态；否则为错误对象。                    |
244
245**错误码：**
246
247以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
248
249| 错误码ID | 错误信息                                |
250| ------ | -------------------------------------- |
251| 17700005 |  The specified app ID is empty string.  |
252
253**示例：**
254
255```ts
256import appControl from '@ohos.bundle.appControl';
257import { BusinessError } from '@ohos.base';
258
259let appId = "com.example.myapplication_xxxxx";
260
261try {
262  appControl.getDisposedStatus(appId, (error, data) => {
263    if (error) {
264      let message = (error as BusinessError).message;
265      console.error('getDisposedStatus failed ' + message);
266      return;
267    }
268    console.info('getDisposedStatus success. DisposedStatus: ' + JSON.stringify(data));
269  });
270} catch (error) {
271    let message = (error as BusinessError).message;
272    console.error('getDisposedStatus failed ' + message);
273}
274```
275
276## appControl.getDisposedStatusSync<sup>10+</sup>
277
278getDisposedStatusSync(appId: string): Want;
279
280以同步方法获取指定应用已设置的处置状态。成功返回应用的处置状态，失败抛出对应异常。
281
282**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
283
284**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
285
286**系统API：**  此接口为系统接口。
287
288**参数：**
289
290| 参数名       | 类型     | 必填   | 说明                                    |
291| ----------- | ------ | ---- | --------------------------------------- |
292| appId  | string | 是    | 要查询的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。  |
293
294**返回值：**
295
296| 类型                        | 说明                 |
297| ------------------------- | ------------------ |
298| Want | 返回应用的处置状态。 |
299
300**错误码：**
301
302以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
303
304| 错误码ID | 错误信息                                |
305| ------ | -------------------------------------- |
306| 17700005 |  The specified app ID is empty string.  |
307
308**示例：**
309
310```ts
311import appControl from '@ohos.bundle.appControl';
312import { BusinessError } from '@ohos.base';
313import Want from '@ohos.app.ability.Want';
314
315let appId: string = "com.example.myapplication_xxxxx";
316let want: Want;
317
318try {
319    want = appControl.getDisposedStatusSync(appId);
320} catch (error) {
321    let message = (error as BusinessError).message;
322    console.error('getDisposedStatusSync failed ' + message);
323}
324```
325
326## appControl.deleteDisposedStatus
327
328deleteDisposedStatus(appId: string): Promise\<void>
329
330以异步方法删除应用的处置状态。使用promise异步回调，成功返回null，失败返回对应错误信息。
331
332**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
333
334**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
335
336**系统API：**  此接口为系统接口。
337
338**参数：**
339
340| 参数名       | 类型     | 必填   | 说明                                    |
341| ----------- | ------ | ---- | --------------------------------------- |
342| appId  | string | 是    | 要删除处置状态的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。  |
343
344**返回值：**
345
346| 类型                        | 说明                 |
347| ------------------------- | ------------------ |
348| Promise\<void> | Promise对象，无返回结果的Promise对象 |
349
350**错误码：**
351
352以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
353
354| 错误码ID | 错误信息                                |
355| ------ | -------------------------------------- |
356| 17700005 |  The specified app ID is empty string.  |
357
358**示例：**
359
360```ts
361import appControl from '@ohos.bundle.appControl';
362import { BusinessError } from '@ohos.base';
363
364let appId = "com.example.myapplication_xxxxx";
365
366try {
367  appControl.deleteDisposedStatus(appId)
368    .then(() => {
369      console.info('deleteDisposedStatus success');
370    }).catch((error: BusinessError) => {
371      let message = (error as BusinessError).message;
372      console.error('deleteDisposedStatus failed ' + message);
373  });
374} catch (error) {
375  let message = (error as BusinessError).message;
376  console.error('deleteDisposedStatus failed ' + message);
377}
378```
379
380## appControl.deleteDisposedStatus
381
382deleteDisposedStatus(appId: string, callback: AsyncCallback\<void>) : void
383
384以异步方法删除应用的处置状态。使用callback异步回调，成功返回null，失败返回对应错误信息。
385
386**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
387
388**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
389
390**系统API：**  此接口为系统接口。
391
392**参数：**
393
394| 参数名       | 类型     | 必填   | 说明                                    |
395| ----------- | ------ | ---- | --------------------------------------- |
396| appId  | string | 是    | 要查询的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。  |
397| callback    | AsyncCallback\<void> | 是    | 回调函数，当设置处置状态成功时，err返回null。否则回调函数返回具体错误对象。                   |
398
399**错误码：**
400
401以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
402
403| 错误码ID | 错误信息                                |
404| ------ | -------------------------------------- |
405| 17700005 |  The specified app ID is empty string.  |
406
407**示例：**
408
409```ts
410import appControl from '@ohos.bundle.appControl';
411import { BusinessError } from '@ohos.base';
412
413let appId = "com.example.myapplication_xxxxx";
414try {
415  appControl.deleteDisposedStatus(appId, (error: BusinessError, data) => {
416    if (error) {
417      console.error('deleteDisposedStatus failed ' + error.message);
418      return;
419    }
420    console.info('deleteDisposedStatus success');
421  });
422} catch (error) {
423    let message = (error as BusinessError).message;
424    console.error('deleteDisposedStatus failed ' + message);
425}
426```
427
428## appControl.deleteDisposedStatusSync<sup>10+</sup>
429
430deleteDisposedStatusSync(appId: string) : void
431
432以同步方法删除应用的处置状态。成功返回null，失败抛出对应异常。
433
434**需要权限：** ohos.permission.MANAGE_DISPOSED_APP_STATUS
435
436**系统能力：** SystemCapability.BundleManager.BundleFramework.AppControl
437
438**系统API：**  此接口为系统接口。
439
440**参数：**
441
442| 参数名       | 类型     | 必填   | 说明                                    |
443| ----------- | ------ | ---- | --------------------------------------- |
444| appId  | string | 是    | 要查询的应用的appId。<br> appId是应用的唯一标识，由应用Bundle名称和签名信息决定，获取方法参见[获取应用的appId](#获取应用的appid)。  |
445
446**错误码：**
447
448以下错误码的详细介绍请参见[ohos.bundle错误码](../errorcodes/errorcode-bundle.md)。
449
450| 错误码ID | 错误信息                                |
451| ------ | -------------------------------------- |
452| 17700005 |  The specified app ID is empty string.  |
453
454**示例：**
455
456```ts
457import appControl from '@ohos.bundle.appControl';
458import { BusinessError } from '@ohos.base';
459
460let appId: string = "com.example.myapplication_xxxxx";
461
462try {
463    appControl.deleteDisposedStatusSync(appId);
464} catch (error) {
465    let message = (error as BusinessError).message;
466    console.error('deleteDisposedStatusSync failed ' + message);
467}
468```
469
470## 获取应用的appId
471
472appId是应用的唯一标识，由应用Bundle名称和签名信息决定，可以通过[getBundleInfo](js-apis-bundleManager.md#bundlemanagergetbundleinfo)接口获取。
473
474**示例：**
475
476```ts
477import bundleManager from '@ohos.bundle.bundleManager';
478import { BusinessError } from '@ohos.base';
479
480let bundleName = 'com.example.myapplication';
481let appId: string;
482try {
483  bundleManager.getBundleInfo(bundleName, bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_SIGNATURE_INFO)
484    .then((data) => {
485      appId = data.signatureInfo.appId;
486      console.info("appId is " + appId);
487    }).catch((error: BusinessError) => {
488      let message = (error as BusinessError).message;
489      console.error("getBundleInfo failed " + message);
490  });
491} catch (error) {
492    let message = (error as BusinessError).message;
493    console.error("getBundleInfo failed " + message);
494}
495```