通知 | Koreyoshi

type

status

date

slug

summary

通知

通知概述

通知简介

应用可以通过通知接口发送通知消息，终端用户可以通过通知栏查看通知内容，也可以点击通知来打开应用。

通知常见的使用场景：

显示接收到的短消息、即时消息等。

显示应用的推送消息，如广告、版本更新等。

显示当前正在进行的事件，如下载等。

HarmonyOS通过ANS（Advanced Notification Service，通知系统服务）对通知类型的消息进行管理，支持多种通知类型，如基础类型通知、进度条类型通知。

通知业务流程

通知业务流程由通知子系统、通知发送端（用户）、通知订阅端（操作系统）组成。一条通知从通知发送端产生，通过IPC通信发送到通知子系统，再由通知子系统分发给通知订阅端。

通知发送端：可以是三方应用或系统应用。开发者重点关注。

通知订阅端：只能为系统应用，比如通知中心。通知中心默认会订阅手机上所有应用对当前用户的通知。开发者无需关注。

发布通知

发布基础类型通知

基础类型通知主要应用于发送短信息、提示信息、广告推送等，支持普通文本类型、长文本类型、多行文本类型和图片类型。

表1 基础类型通知中的内容分类

类型	描述
NOTIFICATION_CONTENT_BASIC_TEXT	普通文本类型。
NOTIFICATION_CONTENT_LONG_TEXT	长文本类型。
NOTIFICATION_CONTENT_MULTILINE	多行文本类型。
NOTIFICATION_CONTENT_PICTURE	图片类型。

目前系统仅通知栏订阅了通知，将通知显示在通知栏里。基础类型通知呈现效果示意图如下所示。

说明
根据设计样式的不同，通知的实际显示效果可能有所差异。本文中所涉及的通知效果图仅供参考，请以实际运行结果为准。

基础类型通知呈现效果示意图

接口说明

通知发布接口如下表所示，不同发布类型通知由NotificationRequest的字段携带不同的信息。

接口名	描述
publish(request: NotificationRequest, callback: AsyncCallback<void>): void	发布通知。
cancel(id: number, label: string, callback: AsyncCallback<void>): void	取消指定的通知。
cancelAll(callback: AsyncCallback<void>): void;	取消所有该应用发布的通知。

开发步骤

略

普通文本类型通知由标题、文本内容和附加信息三个字段组成，其中标题和文本内容是必填字段。

长文本类型通知继承了普通文本类型的字段，同时新增了长文本内容、内容概要和通知展开时的标题。通知默认显示与普通文本相同，展开后，标题显示为展开后标题内容，内容为长文本内容。

多行文本类型通知继承了普通文本类型的字段，同时新增了多行文本内容、内容概要和通知展开时的标题。通知默认显示与普通文本相同，展开后，标题显示为展开后标题内容，多行文本内容多行显示。

图片类型通知继承了普通文本类型的字段，同时新增了图片内容、内容概要和通知展开时的标题，图片内容为PixelMap型对象，其大小不能超过2M。

发布进度条类型通知

进度条通知也是常见的通知类型，主要应用于文件下载、事务处理进度显示。HarmonyOS提供了进度条模板，发布通知应用设置好进度条模板的属性值，如模板名、模板数据，通过通知子系统发送到通知栏显示。

目前系统模板仅支持进度条模板，通知模板NotificationTemplate中的data参数为用户自定义数据，用于显示与模块相关的数据，效果示意如下图所示。

接口说明

isSupportTemplate()是查询模板是否支持接口，目前仅支持进度条模板。

接口名	描述
isSupportTemplate(templateName: string, callback: AsyncCallback<boolean>): void	查询模板是否存在。

开发步骤

1.导入模块。

2.查询系统是否支持进度条模板，查询结果为支持downloadTemplate模板类通知。

说明
查询系统支持进度条模板后，再进行后续的步骤操作。

3.构造进度条模板对象，并发布通知。

为通知添加行为意图

WantAgent提供了封装行为意图的能力，这里所说的行为意图主要是指拉起指定的应用组件及发布公共事件等能力。HarmonyOS支持以通知的形式，将WantAgent从发布方传递至接收方，从而在接收方触发WantAgent中指定的意图。例如，在通知消息的发布者发布通知时，通常期望用户可以通过通知栏点击拉起目标应用组件。为了达成这一目标，开发者可以将WantAgent封装至通知消息中，当系统接收到WantAgent后，在用户点击通知栏时触发WantAgent的意图，从而拉起目标应用组件。

为通知添加行为意图的实现方式如下图所示：发布通知的应用向应用组件管理服务AMS（Ability Manager Service）申请WantAgent，然后随其他通知信息一起发送给桌面，当用户在桌面通知栏上点击通知时，触发WantAgent动作。

图1 携带行为意图的通知运行机制

接口说明

具体接口描述，详见WantAgent接口文档。

接口名	描述
getWantAgent(info: WantAgentInfo, callback: AsyncCallback<WantAgent>): void	创建WantAgent。
trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: Callback<CompleteData>): void	触发WantAgent意图。
cancel(agent: WantAgent, callback: AsyncCallback<void>): void	取消WantAgent。
getWant(agent: WantAgent, callback: AsyncCallback<Want>): void	获取WantAgent的want。
equal(agent: WantAgent, otherAgent: WantAgent, callback: AsyncCallback<boolean>): void	判断两个WantAgent实例是否相等。

开发步骤

1.导入模块。

2.创建WantAgentInfo信息。

场景一：创建拉起UIAbility的WantAgent的WantAgentInfo信息。

场景二：创建发布公共事件的WantAgent的WantAgentInfo信息。

3.创建WantAgent。

4.构造NotificationRequest对象。

4.发布WantAgent通知。

6. 用户通过点击通知栏上的通知，系统会自动触发WantAgent的动作。

Notification Kit（用户通知服务）

请求通知授权

应用需要获取用户授权才能发送通知。在通知发布前调用requestEnableNotification()方法，弹窗让用户选择是否允许发送通知，后续再次调用requestEnableNotification()方法时，则不再弹窗。

通知授权接口功能介绍

接口名	描述
isNotificationEnabled():Promise<boolean>	查询通知是否授权。
requestEnableNotification(context: UIAbilityContext): Promise<void>	请求发送通知的许可，第一次调用会弹窗让用户选择。

开发步骤

1.导入NotificationManager模块。

2.请求通知授权。

可通过requestEnableNotification的错误码判断用户是否授权。若返回的错误码为1600004，即为拒绝授权。

管理通知角标

针对未读的通知，系统提供了角标设置接口，将未读通知个数显示在桌面图标的右上角角标上。

通知增加时，角标上显示的未读通知个数需要增加。

通知被查看后，角标上显示的未读通知个数需要减少，没有未读通知时，不显示角标。

接口说明

当角标设定个数取值0时，表示清除角标。取值大于99时，通知角标将显示99+。

增加角标数，支持如下两种方法：

发布通知时，在NotificationRequest的badgeNumber字段里携带，桌面收到通知后，在原角标数上累加、呈现。
调用接口setBadgeNumber()设置，桌面按设置的角标数呈现。

减少角标数，目前仅支持通过setBadgeNumber()设置。

接口名	描述
setBadgeNumber(badgeNumber: number, callback: AsyncCallback<void>): void	设置角标个数。

开发步骤

1.导入NotificationManager模块。

2.增加角标个数。

发布通知在NotificationRequest的badgeNumber字段里携带，可参考通知发布章节。

示例为调用setBadgeNumber接口增加角标，在发布完新的通知后，调用该接口。

3.减少角标个数。

一条通知被查看后，应用需要调用接口设置剩下未读通知个数，桌面刷新角标。

常见问题

由于setBadgeNumber为异步接口，使用setBadgeNumber连续设置角标时，为了确保执行顺序符合预期，需要确保上一次设置完成后才能进行下一次设置。

反例

每次接口调用是相互独立的、没有依赖关系的，实际执行时无法保证调用顺序。

示例如下：

正例

多次接口调用存在依赖关系，确保上一次设置完成后才能进行下一次设置。

示例如下：

管理通知渠道

系统支持多种通知渠道，不同通知渠道对应的通知提醒方式不同，可以根据应用的实际场景选择适合的通知渠道，并对通知渠道进行管理（支持创建、查询、删除等操作）。

通知渠道类型说明

不同类型的通知渠道对应的通知提醒方式不同，详见下表。其中，Y代表支持，N代表不支持。

SlotType	取值	分类	通知中心	横幅	锁屏	铃声/振动	状态栏图标	自动亮屏
UNKNOWN_TYPE	0	未知类型	Y	N	N	N	N	N
SOCIAL_COMMUNICATION	1	社交通信	Y	Y	Y	Y	Y	Y
SERVICE_INFORMATION	2	服务提醒	Y	Y	Y	Y	Y	Y
CONTENT_INFORMATION	3	内容资讯	Y	N	N	N	N	N
CUSTOMER_SERVICE	5	客服消息	Y	N	N	Y	Y	N
OTHER_TYPES	0xFFFF	其他	Y	N	N	N	N	N

接口说明

通知渠道主要接口如下。其他接口介绍详情参见API参考。

接口名	描述
addSlot(type: SlotType): Promise<void>	创建指定类型的通知渠道。
getSlot(slotType: SlotType): Promise<NotificationSlot>	获取一个指定类型的通知渠道。
removeSlot(slotType: SlotType): Promise<void>	删除此应用程序指定类型的通知渠道。

除了可以使用addslot()创建通知渠道，还可以在发布通知的NotificationRequest中携带notificationSlotType字段，如果对应渠道不存在，会自动创建。

开发步骤

1.导入notificationManager模块。

2.创建指定类型的通知渠道。

3.查询指定类型的通知渠道。

获取对应渠道是否创建以及该渠道支持的通知提醒方式，比如是否有声音提示，是否有震动，锁屏是否可见等。

4.删除指定类型的通知渠道。

发布通知：文本类型

文本类型通知主要应用于发送短信息、提示信息等，支持普通文本类型和多行文本类型。

表1 基础类型通知中的内容分类

类型	描述
NOTIFICATION_CONTENT_BASIC_TEXT	普通文本类型。
NOTIFICATION_CONTENT_MULTILINE	多行文本类型。

接口说明

通知发布接口说明详见下表，通知发布的详情可通过入参NotificationRequest来进行指定，可以包括通知内容、通知ID、通知的通道类型和通知发布时间等信息。

接口名	描述
publish(request: NotificationRequest, callback: AsyncCallback<void>): void	发布通知。
cancel(id: number, label: string, callback: AsyncCallback<void>): void	取消指定的通知。
cancelAll(callback: AsyncCallback<void>): void	取消所有该应用发布的通知。