• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.notificationSubscribe (NotificationSubscribe模块)
2
3本模块提供通知订阅、取消订阅、通知移除等，一般情况下，只有系统应用具有这些操作权限。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```js
12import notificationSubscribe from '@ohos.notificationSubscribe';
13```
14
15
16
17## NotificationSubscribe.subscribe
18
19subscribe(subscriber: NotificationSubscriber, info: NotificationSubscribeInfo, callback: AsyncCallback\<void\>): void
20
21订阅通知并指定订阅信息（callback形式）。
22
23**系统能力**：SystemCapability.Notification.Notification
24
25**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
26
27**系统API**: 此接口为系统接口，三方应用不支持调用。
28
29**参数：**
30
31| 参数名       | 类型                      | 必填 | 说明             |
32| ---------- | ------------------------- | ---- | ---------------- |
33| subscriber | [NotificationSubscriber](js-apis-notification.md#notificationsubscriber)    | 是   | 通知订阅对象。     |
34| info       | [NotificationSubscribeInfo](js-apis-notification.md#notificationsubscribeinfo) | 是   | 通知订阅信息。 |
35| callback   | AsyncCallback\<void\>     | 是   | 订阅动作回调函数。 |
36
37**错误码：**
38
39错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
40
41| 错误码ID | 错误信息                            |
42| -------- | ----------------------------------- |
43| 1600001  | Internal error.                     |
44| 1600002  | Marshalling or unmarshalling error. |
45| 1600003  | Failed to connect service.          |
46
47**示例：**
48
49```js
50//subscribe回调
51function subscribeCallback(err) {
52    if (err) {
53        console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
54    } else {
55        console.info("subscribe success");
56    }
57}
58function onConsumeCallback(data) {
59	console.info("Consume callback: " + JSON.stringify(data));
60}
61let subscriber = {
62    onConsume: onConsumeCallback
63};
64let info = {
65    bundleNames: ["bundleName1","bundleName2"]
66};
67notificationSubscribe.subscribe(subscriber, info, subscribeCallback);
68```
69
70## NotificationSubscribe.subscribe
71
72subscribe(subscriber: NotificationSubscriber, callback: AsyncCallback\<void\>): void
73
74订阅当前用户下所有应用的通知（callback形式）。
75
76**系统能力**：SystemCapability.Notification.Notification
77
78**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
79
80**系统API**: 此接口为系统接口，三方应用不支持调用。
81
82**参数：**
83
84| 参数名       | 类型                   | 必填 | 说明             |
85| ---------- | ---------------------- | ---- | ---------------- |
86| subscriber | [NotificationSubscriber](js-apis-notification.md#notificationsubscriber) | 是   | 通知订阅对象。     |
87| callback   | AsyncCallback\<void\>  | 是   | 订阅动作回调函数。 |
88
89**错误码：**
90
91错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
92
93| 错误码ID | 错误信息                            |
94| -------- | ----------------------------------- |
95| 1600001  | Internal error.                     |
96| 1600002  | Marshalling or unmarshalling error. |
97| 1600003  | Failed to connect service.          |
98
99**示例：**
100
101```js
102function subscribeCallback(err) {
103    if (err) {
104        console.error(`subscribe failed, code is ${err.code}, message is ${err.message}`);
105    } else {
106        console.info("subscribe success");
107    }
108}
109function onConsumeCallback(data) {
110	console.info("Consume callback: " + JSON.stringify(data));
111}
112let subscriber = {
113    onConsume: onConsumeCallback
114};
115notificationSubscribe.subscribe(subscriber, subscribeCallback);
116```
117
118
119
120## NotificationSubscribe.subscribe
121
122subscribe(subscriber: NotificationSubscriber, info?: NotificationSubscribeInfo): Promise\<void\>
123
124订阅通知并指定订阅信息（Promise形式）。
125
126**系统能力**：SystemCapability.Notification.Notification
127
128**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
129
130**系统API**: 此接口为系统接口，三方应用不支持调用。
131
132**参数：**
133
134| 参数名       | 类型                      | 必填 | 说明         |
135| ---------- | ------------------------- | ---- | ------------ |
136| subscriber | [NotificationSubscriber](js-apis-notification.md#notificationsubscriber)    | 是   | 通知订阅对象。 |
137| info       | [NotificationSubscribeInfo](js-apis-notification.md#notificationsubscribeinfo) | 否   | 通知订阅信息。   |
138
139**错误码：**
140
141错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
142
143| 错误码ID | 错误信息                            |
144| -------- | ----------------------------------- |
145| 1600001  | Internal error.                     |
146| 1600002  | Marshalling or unmarshalling error. |
147| 1600003  | Failed to connect service.          |
148
149**示例：**
150
151```js
152function onConsumeCallback(data) {
153    console.info("Consume callback: " + JSON.stringify(data));
154}
155let subscriber = {
156    onConsume: onConsumeCallback
157};
158notificationSubscribe.subscribe(subscriber).then(() => {
159	console.info("subscribe success");
160});
161```
162
163
164
165## NotificationSubscribe.unsubscribe
166
167unsubscribe(subscriber: NotificationSubscriber, callback: AsyncCallback\<void\>): void
168
169取消订阅（callbcak形式）。
170
171**系统能力**：SystemCapability.Notification.Notification
172
173**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
174
175**系统API**: 此接口为系统接口，三方应用不支持调用。
176
177**参数：**
178
179| 参数名       | 类型                   | 必填 | 说明                 |
180| ---------- | ---------------------- | ---- | -------------------- |
181| subscriber | [NotificationSubscriber](js-apis-notification.md#notificationsubscriber) | 是   | 通知订阅对象。         |
182| callback   | AsyncCallback\<void\>  | 是   | 取消订阅动作回调函数。 |
183
184**错误码：**
185
186错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
187
188| 错误码ID | 错误信息                            |
189| -------- | ----------------------------------- |
190| 1600001  | Internal error.                     |
191| 1600002  | Marshalling or unmarshalling error. |
192| 1600003  | Failed to connect service.          |
193
194**示例：**
195
196```js
197function unsubscribeCallback(err) {
198    if (err) {
199        console.error(`unsubscribe failed, code is ${err.code}, message is ${err.message}`);
200    } else {
201        console.info("unsubscribe success");
202    }
203}
204function onDisconnectCallback() {
205	console.info("subscribe disconnect");
206}
207let subscriber = {
208    onDisconnect: onDisconnectCallback
209};
210notificationSubscribe.unsubscribe(subscriber, unsubscribeCallback);
211```
212
213## NotificationSubscribe.unsubscribe
214
215unsubscribe(subscriber: NotificationSubscriber): Promise\<void\>
216
217取消订阅（Promise形式）。
218
219**系统能力**：SystemCapability.Notification.Notification
220
221**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
222
223**系统API**: 此接口为系统接口，三方应用不支持调用。
224
225**参数：**
226
227| 参数名       | 类型                   | 必填 | 说明         |
228| ---------- | ---------------------- | ---- | ------------ |
229| subscriber | [NotificationSubscriber](js-apis-notification.md#notificationsubscriber) | 是   | 通知订阅对象。 |
230
231**错误码：**
232
233错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
234
235| 错误码ID | 错误信息                            |
236| -------- | ----------------------------------- |
237| 1600001  | Internal error.                     |
238| 1600002  | Marshalling or unmarshalling error. |
239| 1600003  | Failed to connect service.          |
240
241**示例：**
242
243```js
244function onDisconnectCallback() {
245	console.info("subscribe disconnect");
246}
247let subscriber = {
248    onDisconnect: onDisconnectCallback
249};
250notificationSubscribe.unsubscribe(subscriber).then(() => {
251	console.info("unsubscribe success");
252});
253```
254
255## NotificationSubscribe.remove
256
257remove(bundle: BundleOption, notificationKey: NotificationKey, reason: RemoveReason, callback: AsyncCallback\<void\>): void
258
259删除指定通知（Callback形式）。
260
261**系统能力**：SystemCapability.Notification.Notification
262
263**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
264
265**系统API**: 此接口为系统接口，三方应用不支持调用。
266
267**参数：**
268
269| 参数名            | 类型                                | 必填 | 说明                 |
270| --------------- |   ----------------------------------| ---- | -------------------- |
271| bundle          | [BundleOption](js-apis-inner-notification-notificationCommonDef.md#bundleoption)       | 是   | 指定应用的包信息。           |
272| notificationKey | [NotificationKey](js-apis-notification.md#notificationkey) | 是   | 通知键值。             |
273| reason          | [RemoveReason](#removereason)      | 是   | 通知删除原因。         |
274| callback        | AsyncCallback\<void\>               | 是   | 删除指定通知回调函数。 |
275
276**错误码：**
277
278错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
279
280| 错误码ID | 错误信息                                 |
281| -------- | ---------------------------------------- |
282| 1600001  | Internal error.                          |
283| 1600002  | Marshalling or unmarshalling error.      |
284| 1600003  | Failed to connect service.               |
285| 1600007  | The notification is not exist.           |
286| 17700001 | The specified bundle name was not found. |
287
288**示例：**
289
290```js
291function removeCallback(err) {
292    if (err) {
293        console.error(`remove failed, code is ${err.code}, message is ${err.message}`);
294    } else {
295        console.info("remove success");
296    }
297}
298let bundle = {
299    bundle: "bundleName1",
300};
301let notificationKey = {
302    id: 0,
303    label: "label",
304};
305let reason = notificationSubscribe.RemoveReason.CLICK_REASON_REMOVE;
306notificationSubscribe.remove(bundle, notificationKey, reason, removeCallback);
307```
308
309
310
311## NotificationSubscribe.remove
312
313remove(bundle: BundleOption, notificationKey: NotificationKey, reason: RemoveReason): Promise\<void\>
314
315删除指定通知（Promise形式）。
316
317**系统能力**：SystemCapability.Notification.Notification
318
319**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
320
321**系统API**: 此接口为系统接口，三方应用不支持调用。
322
323**参数：**
324
325| 参数名            | 类型            | 必填 | 说明       |
326| --------------- | --------------- | ---- | ---------- |
327| bundle          | [BundleOption](js-apis-inner-notification-notificationCommonDef.md#bundleoption)    | 是   | 指定应用的包信息。 |
328| notificationKey | [NotificationKey](js-apis-notification.md#notificationkey) | 是   | 通知键值。   |
329| reason          | [RemoveReason](#removereason) | 是   | 通知删除原因。         |
330
331**错误码：**
332
333错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
334
335| 错误码ID | 错误信息                                 |
336| -------- | ---------------------------------------- |
337| 1600001  | Internal error.                          |
338| 1600002  | Marshalling or unmarshalling error.      |
339| 1600003  | Failed to connect service.               |
340| 1600007  | The notification is not exist.           |
341| 17700001 | The specified bundle name was not found. |
342
343**示例：**
344
345```js
346let bundle = {
347    bundle: "bundleName1",
348};
349let notificationKey = {
350    id: 0,
351    label: "label",
352};
353let reason = notificationSubscribe.RemoveReason.CLICK_REASON_REMOVE;
354notificationSubscribe.remove(bundle, notificationKey, reason).then(() => {
355	console.info("remove success");
356});
357```
358
359## NotificationSubscribe.remove
360
361remove(hashCode: string, reason: RemoveReason, callback: AsyncCallback\<void\>): void
362
363删除指定通知（Callback形式）。
364
365**系统能力**：SystemCapability.Notification.Notification
366
367**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
368
369**系统API**: 此接口为系统接口，三方应用不支持调用。
370
371**参数：**
372
373| 参数名     | 类型                  | 必填 | 说明                 |
374| -------- | --------------------- | ---- | -------------------- |
375| hashCode | string                | 是   | 通知唯一ID。可以通过[onConsume](js-apis-notification.md#onconsume)回调的入参[SubscribeCallbackData](js-apis-notification.md#subscribecallbackdata)获取其内部[NotificationRequest](js-apis-inner-notification-notificationRequest.md#notificationrequest)对象中的hashCode。 |
376| reason   | [RemoveReason](#removereason) | 是   | 通知删除原因。         |
377| callback | AsyncCallback\<void\> | 是   | 删除指定通知回调函数。 |
378
379**错误码：**
380
381错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
382
383| 错误码ID | 错误信息                            |
384| -------- | ----------------------------------- |
385| 1600001  | Internal error.                     |
386| 1600002  | Marshalling or unmarshalling error. |
387| 1600003  | Failed to connect service.          |
388| 1600007  | The notification is not exist.      |
389
390**示例：**
391
392```js
393let hashCode = 'hashCode';
394
395function removeCallback(err) {
396    if (err) {
397        console.error(`remove failed, code is ${err.code}, message is ${err.message}`);
398    } else {
399        console.info("remove success");
400    }
401}
402let reason = notificationSubscribe.RemoveReason.CANCEL_REASON_REMOVE;
403notificationSubscribe.remove(hashCode, reason, removeCallback);
404```
405
406## NotificationSubscribe.remove
407
408remove(hashCode: string, reason: RemoveReason): Promise\<void\>
409
410删除指定通知（Promise形式）。
411
412**系统能力**：SystemCapability.Notification.Notification
413
414**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
415
416**系统API**: 此接口为系统接口，三方应用不支持调用。
417
418**参数：**
419
420| 参数名     | 类型       | 必填 | 说明       |
421| -------- | ---------- | ---- | ---------- |
422| hashCode | string | 是   | 通知唯一ID。 |
423| reason   | [RemoveReason](#removereason) | 是   | 通知删除原因。         |
424
425**错误码：**
426
427错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
428
429| 错误码ID | 错误信息                            |
430| -------- | ----------------------------------- |
431| 1600001  | Internal error.                     |
432| 1600002  | Marshalling or unmarshalling error. |
433| 1600003  | Failed to connect service.          |
434| 1600007  | The notification is not exist.      |
435
436**示例：**
437
438```js
439let hashCode = 'hashCode';
440let reason = notificationSubscribe.RemoveReason.CLICK_REASON_REMOVE;
441notificationSubscribe.remove(hashCode, reason).then(() => {
442	console.info("remove success");
443});
444```
445
446## NotificationSubscribe.removeAll
447
448removeAll(bundle: BundleOption, callback: AsyncCallback\<void\>): void
449
450删除指定应用的所有通知（Callback形式）。
451
452**系统能力**：SystemCapability.Notification.Notification
453
454**系统API**：此接口为系统接口，三方应用不支持调用。
455
456**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
457
458**参数：**
459
460| 参数名     | 类型                  | 必填 | 说明                         |
461| -------- | --------------------- | ---- | ---------------------------- |
462| bundle   | [BundleOption](js-apis-inner-notification-notificationCommonDef.md#bundleoption)         | 是   | 指定应用的包信息。                   |
463| callback | AsyncCallback\<void\> | 是   | 删除指定应用的所有通知回调函数。 |
464
465**错误码：**
466
467错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
468
469| 错误码ID | 错误信息                                 |
470| -------- | ---------------------------------------- |
471| 1600001  | Internal error.                          |
472| 1600002  | Marshalling or unmarshalling error.      |
473| 1600003  | Failed to connect service.               |
474| 17700001 | The specified bundle name was not found. |
475
476**示例：**
477
478```js
479function removeAllCallback(err) {
480    if (err) {
481        console.error(`removeAll failed, code is ${err.code}, message is ${err.message}`);
482    } else {
483        console.info("removeAll success");
484    }
485}
486let bundle = {
487    bundle: "bundleName1",
488};
489notificationSubscribe.removeAll(bundle, removeAllCallback);
490```
491
492## NotificationSubscribe.removeAll
493
494removeAll(callback: AsyncCallback\<void\>): void
495
496删除所有通知（Callback形式）。
497
498**系统能力**：SystemCapability.Notification.Notification
499
500**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
501
502**系统API**: 此接口为系统接口，三方应用不支持调用。
503
504**参数：**
505
506| 参数名     | 类型                  | 必填 | 说明                 |
507| -------- | --------------------- | ---- | -------------------- |
508| callback | AsyncCallback\<void\> | 是   | 删除所有通知回调函数。 |
509
510**错误码：**
511
512错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
513
514| 错误码ID | 错误信息                            |
515| -------- | ----------------------------------- |
516| 1600001  | Internal error.                     |
517| 1600002  | Marshalling or unmarshalling error. |
518| 1600003  | Failed to connect service.          |
519
520**示例：**
521
522```js
523function removeAllCallback(err) {
524    if (err) {
525        console.error(`removeAll failed, code is ${err.code}, message is ${err.message}`);
526    } else {
527        console.info("removeAll success");
528    }
529}
530
531notificationSubscribe.removeAll(removeAllCallback);
532```
533
534## NotificationSubscribe.removeAll
535
536removeAll(bundle?: BundleOption): Promise\<void\>
537
538删除指定应用的所有通知（Promise形式）。
539
540**系统能力**：SystemCapability.Notification.Notification
541
542**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
543
544**系统API**: 此接口为系统接口，三方应用不支持调用。
545
546**参数：**
547
548| 参数名   | 类型         | 必填 | 说明       |
549| ------ | ------------ | ---- | ---------- |
550| bundle | [BundleOption](js-apis-inner-notification-notificationCommonDef.md#bundleoption) | 否   | 指定应用的包信息。 |
551
552**错误码：**
553
554错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
555
556| 错误码ID | 错误信息                                 |
557| -------- | ---------------------------------------- |
558| 1600001  | Internal error.                          |
559| 1600002  | Marshalling or unmarshalling error.      |
560| 1600003  | Failed to connect service.               |
561| 17700001 | The specified bundle name was not found. |
562
563**示例：**
564
565```js
566// 不指定应用时，删除所有通知
567notificationSubscribe.removeAll().then(() => {
568	console.info("removeAll success");
569});
570```
571
572## NotificationSubscribe.removeAll
573
574removeAll(userId: number, callback: AsyncCallback\<void>): void
575
576删除指定用户下的所有通知（callback形式）。
577
578**系统能力**：SystemCapability.Notification.Notification
579
580**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
581
582**系统API**: 此接口为系统接口，三方应用不支持调用。
583
584**参数：**
585
586| 参数名   | 类型         | 必填 | 说明       |
587| ------ | ------------ | ---- | ---------- |
588| userId | number | 是   | 用户ID。 |
589| callback | AsyncCallback\<void\> | 是   | 删除指定用户所有通知回调函数。 |
590
591**错误码：**
592
593错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
594
595| 错误码ID | 错误信息                            |
596| -------- | ----------------------------------- |
597| 1600001  | Internal error.                     |
598| 1600002  | Marshalling or unmarshalling error. |
599| 1600003  | Failed to connect service.          |
600| 1600008  | The user is not exist.              |
601
602**示例：**
603
604```js
605function removeAllCallback(err) {
606    if (err) {
607        console.error(`removeAll failed, code is ${err.code}, message is ${err.message}`);
608    } else {
609        console.info("removeAll success");
610    }
611}
612
613let userId = 1;
614
615notificationSubscribe.removeAll(userId, removeAllCallback);
616```
617
618## Notification.removeAll
619
620removeAll(userId: number): Promise\<void>
621
622删除指定用户下的所有通知（Promise形式）。
623
624**系统能力**：SystemCapability.Notification.Notification
625
626**需要权限**: ohos.permission.NOTIFICATION_CONTROLLER
627
628**系统API**: 此接口为系统接口，三方应用不支持调用。
629
630**参数：**
631
632| 参数名   | 类型         | 必填 | 说明       |
633| ------ | ------------ | ---- | ---------- |
634| userId | number | 是   | 用户ID。 |
635
636**错误码：**
637
638错误码详细介绍请参考[errcode-notification](../errorcodes/errorcode-notification.md)。
639
640| 错误码ID | 错误信息                            |
641| -------- | ----------------------------------- |
642| 1600001  | Internal error.                     |
643| 1600002  | Marshalling or unmarshalling error. |
644| 1600003  | Failed to connect service.          |
645| 1600008  | The user is not exist.              |
646
647**示例：**
648
649```js
650function removeAllCallback(err) {
651    if (err) {
652        console.error(`removeAll failed, code is ${err.code}, message is ${err.message}`);
653    } else {
654        console.info("removeAll success");
655    }
656}
657
658let userId = 1;
659
660notificationSubscribe.removeAll(userId, removeAllCallback);
661```
662
663## RemoveReason
664
665**系统能力**：SystemCapability.Notification.Notification
666
667**系统API**: 此接口为系统接口，三方应用不支持调用。
668
669| 名称                 | 值  | 说明                  |
670| -------------------- | --- | -------------------- |
671| CLICK_REASON_REMOVE  | 1   | 点击通知后删除通知。    |
672| CANCEL_REASON_REMOVE | 2   | 用户删除通知。         |
673