-

场景介绍

HarmonyOS 提供了通知功能，即在一个应用的 UI 界面之外显示的消息，主要用来提醒用户有来自该应用中的信息。当应用向系统发出通知时，它将先以图标的形式显示在通知栏中，用户可以下拉通知栏查看通知的详细信息。常见的使用场景：

  • 显示接收到短消息、即时消息等。
  • 显示应用的推送消息，如广告、版本更新等。
  • 显示当前正在进行的事件，如播放音乐、导航、下载等。

接口说明

通知相关基础类包含 [ NotificationSlot ]、[ NotificationRequest ]和[ NotificationHelper ]。基础类之间的关系如下所示：

图1 通知基础类关系图

img

  • 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.");
}

发布通知

  1. 构建 NotificationRequest 对象，应用发布通知前，通过 NotificationRequest 的 setSlotId() 方法与 NotificationSlot 绑定，使该通知在发布后都具备该对象的特征。

   int notificationId = 1;
   NotificationRequest request = new NotificationRequest(notificationId);
   request.setSlotId(slot.getId());

  1. 调用 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); // 设置通知的内容

  1. 调用 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.");
  }

(c) 2024 chaojicainiao.com MIT license