"鸿蒙OS开发文档"的目录
鸿蒙OS开发文档 鸿蒙OS 通知开发指导
场景介绍
HarmonyOS 提供了通知功能，即在一个应用的 UI 界面之外显示的消息，主要用来提醒用户有来自该应用中的信息。当应用向系统发出通知时，它将先以图标的形式显示在通知栏中，用户可以下拉通知栏查看通知的详细信息。常见的使用场景：
- 显示接收到短消息、即时消息等。
- 显示应用的推送消息，如广告、版本更新等。
- 显示当前正在进行的事件，如播放音乐、导航、下载等。
接口说明
通知相关基础类包含 [ NotificationSlot ]、[ NotificationRequest ]和[ NotificationHelper ]。基础类之间的关系如下所示：
图1 通知基础类关系图
- NotificationSlot
NotificationSlot 可以对提示音、振动、锁屏显示和重要级别等进行设置。一个应用可以创建一个或多个 NotificationSlot，在发送通知时，通过绑定不同的 NotificationSlot，实现不同用途。
说明
NotificationSlot 需要先通过 NotificationHelper 的 addNotificationSlot(NotificationSlot)方法发布后，通知才能绑定使用；所有绑定该 NotificationSlot 的通知在发布后都具备相应的特性，对象在创建后，将无法更改这些设置，对于是否启动相应设置，用户有最终控制权。
不指定 NotificationSlot 时，当前通知会使用默认的 NotificationSlot，默认的 NotificationSlot 优先级为 LEVEL_DEFAULT 。
| 接口名 | 描述 |
|---|---|
| NotificationSlot(String id, String name, int level) | 构造 NotificationSlot。 |
| setLevel(int level) | 设置 NotificationSlot 的级别。 |
| setName(String name) | 设置 NotificationSlot 的命名。 |
| setDescription(String description) | 设置 NotificationSlot 的描述信息。 |
| enableBypassDnd(boolean bypassDnd) | 设置是否绕过系统的免打扰模式。 |
| setEnableVibration(boolean vibration) | 设置收到通知时是否使能振动。 |
| setLockscreenVisibleness(int visibleness) | 设置在锁屏场景下，收到通知后是否显示，以及显示的效果。 |
| setEnableLight(boolean isLightEnabled) | 设置收到通知时是否开启呼吸灯，前提是当前硬件支持呼吸灯。 |
| setLedLightColor(int color) | 设置收到通知时的呼吸灯颜色。 |
| setSlotGroup(String groupId) | 绑定当前 NotificationSlot 到一个 NotificationSlot 组。 |
NotificationSlot 的级别目前支持如下几种， 由低到高：
- LEVEL_NONE： 表示通知不发布。
- LEVEL_MIN：表示通知可以发布，但是不显示在通知栏，不自动弹出，无提示音；该级别不适用于前台服务的场景。
- LEVEL_LOW：表示通知可以发布且显示在通知栏，不自动弹出，无提示音。
- LEVEL_DEFAULT：表示通知发布后可在通知栏显示，不自动弹出，触发提示音。
- LEVEL_HIGH：表示通知发布后可在通知栏显示，自动弹出，触发提示。
- NotificationRequest
NotificationRequest 用于设置具体的通知对象，包括设置通知的属性，如：通知的分发时间、小图标、大图标、自动删除等参数，以及设置具体的通知类型，如普通文本、长文本等。
| 接口名 | 描述 |
|---|---|
| NotificationRequest() | 构建一个通知。 |
| NotificationRequest(int notificationId) | 构建一个通知，指定通知的id。通知的Id在应用内容具有唯一性，如果不指定，默认为0。 |
| setNotificationId(int notificationId) | 设置当前通知id。 |
| setAutoDeletedTime(long time) | 设置通知自动取消的时间戳。 |
| setContent(NotificationRequest.NotificationContent content) | 设置通知的具体类型。 |
| setCreateTime(long createTime) | 设置通知的创建的时间戳。 |
| setDeliveryTime(long deliveryTime) | 设置通知分发的时间戳。 |
| setSlotId(String slotId) | 设置通知的 NotificationSlot id。 |
| setTapDismissed(boolean tapDismissed) | 设置通知在用户点击后是否自动取消。 |
| setLittleIcon(PixelMap smallIcon) | 设置通知的小图标，在通知左上角显示。 |
| setBigIcon(PixelMap bigIcon) | 设置通知的大图标，在通知的右边显示。 |
| setGroupValue(String groupValue) | 设置分组通知，相同分组的通知在通知栏显示时，将会折叠在一组应用中显示。 |
| addActionButton(NotificationActionButton actionButton) | 设置通知添加通知 ActionButton。 |
| setIntentAgent(IntentAgent agent) | 设置通知承载指定的 IntentAgent，在通知中实现即将触发的事件。 |
具体的通知类型：目前支持六种类型，包括普通文本 NotificationNormalContent、长文本 NotificationLongTextContent、图片 NotificationPictureContent、多行 NotificationMultiLineContent、社交 NotificationConversationalContent、媒体 NotificationMediaContent。
| 类名 | 接口名 | 描述 |
|---|---|---|
| NotificationNormalContent | setTitle(String title) | 设置通知标题。 |
| NotificationNormalContent | setText(String text) | 设置通知内容。 |
| NotificationNormalContent | setAdditionalText(String additionalText) | 设置通知次要内容，是对通知内容的补充。 |
| NotificationPictureContent | setBriefText(String briefText) | 设置通知概要内容，是对通知内容的总结。 |
| NotificationPictureContent | setExpandedTitle(String expandedTitle) | 设置通知一旦设置了，折叠时显示setTitle(String)的值，展开时当前设置的展开标题。 |
| NotificationPictureContent | setBigPicture(PixelMap bigPicture) | 设置通知的图片内容，附加在setText(String text)下方。 |
| NotificationLongTextContent | setLongText(String longText) | 设置通知的长文本。 |
| NotificationConversationalContent | setConversationTitle(String conversationTitle) | 设置社交通知的标题。 |
| NotificationConversationalContent | addConversationalMessage(ConversationalMessage message) | 通知添加一条消息。 |
| NotificationMultiLineContent | addSingleLine(String line) | 在当前通知中添加一行文本。 |
| NotificationMediaContent | setAVToken(AVToken avToken) | 将媒体通知绑定指定的AVToken。 |
| NotificationMediaContent | setShownActions(int[] actions) | 设置媒体通知待展示的按钮。 |
说明
通知发布后，通知的设置不可修改。如果下次发布通知使用相同的 id，就会更新之前发布的通知。
- NotificationHelper
NotificationHelper 封装了发布、更新、订阅、删除通知等静态方法。订阅通知、退订通知和查询系统中所有处于活跃状态的通知，有权限要求需为系统应用或具有订阅者权限。
| 接口名 | 描述 |
|---|---|
| publishNotification(NotificationRequest request) | 发布一条通知。 |
| publishNotification(String tag, NotificationRequest) | 发布一条带TAG的通知。 |
| cancelNotification(int notificationId) | 取消指定的通知。 |
| cancelNotification(String tag, int notificationId) | 取消指定的带 TAG 的通知。 |
| cancelAllNotifications() | 取消之前发布的所有通知。 |
| addNotificationSlot(NotificationSlot slot) | 创建一个 NotificationSlot。 |
| getNotificationSlot(String slotId) | 获取 NotificationSlot。 |
| removeNotificationSlot(String slotId) | 删除一个 NotificationSlot。 |
| getActiveNotifications() | 获取当前应用发的活跃通知。 |
| getActiveNotificationNums() | 获取系统中当前应用发的活跃通知的数量。 |
| setNotificationBadgeNum(int num) | 设置通知的角标。 |
| setNotificationBadgeNum() | 设置当前应用中活跃状态通知的数量在角标显示。 |
开发步骤
通知的开发指导分为创建 NotificationSlot、发布通知和取消通知等开发场景。
创建NotificationSlot
NotificationSlot 可以设置公共通知的震动，锁屏模式，重要级别等，并通过调用 NotificationHelper.addNotificationSlot() 发布 NotificationSlot 对象。
NotificationSlot slot = new NotificationSlot("slot_001","slot_default", NotificationSlot.LEVEL_MIN); // 创建notificationSlot对象
slot.setDescription("NotificationSlotDescription");
slot.setEnableVibration(true); // 设置振动提醒
slot.setLockscreenVisibleness(NotificationRequest.VISIBLENESS_TYPE_PUBLIC);//设置锁屏模式
slot.setEnableLight(true); // 设置开启呼吸灯提醒
slot.setLedLightColor(Color.RED.getValue());// 设置呼吸灯的提醒颜色
try {
NotificationHelper.addNotificationSlot(slot);
} catch (RemoteException ex) {
HiLog.warn(LABEL, "addNotificationSlot occur exception.");
} 发布通知
- 构建 NotificationRequest 对象，应用发布通知前，通过 NotificationRequest 的 setSlotId() 方法与 NotificationSlot 绑定，使该通知在发布后都具备该对象的特征。
int notificationId = 1;
NotificationRequest request = new NotificationRequest(notificationId);
request.setSlotId(slot.getId());
- 调用 setContent() 设置通知的内容。
String title = "title";
String text = "There is a normal notification content.";
NotificationNormalContent content = new NotificationNormalContent();
content.setTitle(title)
.setText(text);
NotificationContent notificationContent = new NotificationContent(content);
request.setContent(notificationContent); // 设置通知的内容
- 调用 publishNotification() 发送通知。
try {
NotificationHelper.publishNotification(request);
} catch (RemoteException ex) {
HiLog.warn(LABEL, "publishNotification occur exception.");
} 取消通知
取消通知分为取消指定单条通知和取消所有通知，应用只能取消自己发布的通知。
- 调用 cancelNotification() 取消指定的单条通知。
int notificationId = 1;
try {
NotificationHelper.cancelNotification(notificationId);
} catch (RemoteException ex) {
HiLog.warn(LABEL, "cancelNotification occur exception.");
}
- 调用 cancelAllNotifications() 取消所有通知。
try {
NotificationHelper.cancelAllNotifications();
} catch (RemoteException ex) {
HiLog.warn(LABEL, "cancelAllNotifications occur exception.");
}