1、用户通知服务 Notification Kit 介绍
Notification Kit（用户通知服务）为开发者提供本地通知发布通道，开发者可借助 Notification Kit 将应用产生的通知直接在客户端本地推送给用户，本地通知根据通知类型及发布场景会产生对应的铃声、震动、横幅、锁屏、息屏、通知栏提醒和显示。类似 Android 的通知栏功能：
创建通知后以图标的形式在状态栏中显示：
用户可以在状态栏向下滑动以打开抽屉式通知栏，并在其中查看更多详情及对通知执行操作。
还有提醒式通知样式：
HarmonyOS 也提供了类似的能力 Notification Kit。
2、用户通知服务与 Call Kit、Push Kit 区别
用户通知是允许开发者自己调用接口创建定义的
Push Kit（推送服务）是华为提供的消息推送平台，建立了从云端到终端的消息推送通道。所有 HarmonyOS 应用可通过集成 Push Kit，实现向应用实时推送消息，使消息易见，构筑良好的用户关系，提升用户的感知度和活跃度。Push Kit 与云端的链接的是系统守护进程，一直运行在后台，当点击通知服务厂商的通知栏时会拉起对应应用进程。显示场景主要包括通知中心、锁屏、横幅、桌面图标角标与通知图标。
Call Service Kit（通话服务）是 HarmonyOS 为开发者提供的应用内通话管理服务。开发者通过集成 Call Service Kit，可以实现便捷的来电一键接听、横幅通知、静音与取消静音等功能，提升用户体验。当应用在后台时，如果有来电，需要 Push Kit（推送服务）先拉起应用主进程，应用才能给 Call Service Kit 上报来电。Call Kit 与 Push Kit 关系如下：
可以理解为应用有个独立守护进程一直与华为云端通信，这个是 Push Kit，当有通知到达时，这个进程调用 Notification Kit 创建对应通知栏通知，当对应通知时通话时，点击通知栏拉起进程，应用给 Call Kit 上报来电。
3、用户通知服务 Notification Kit 能力及 API
使用 Notification Kit 的主要业务流程如下：
1.请求通知授权。
2.应用发布通知到通知服务。
3.将通知展示到通知中心。
请求通知授权
首先应用需要获取用户授权才能发送通知。在通知发布前调用 requestEnableNotification()方法，弹窗让用户选择是否允许发送通知，后续再次调用 requestEnableNotification()方法时，则不再弹窗。
授权通知接口功能如下：
首先导入 NotificationManager 模块：
import { notificationManager } from '@kit.NotificationKit';import { BusinessError } from '@kit.BasicServicesKit';import { hilog } from '@kit.PerformanceAnalysisKit';import { common } from '@kit.AbilityKit';
const TAG: string = '[PublishOperation]';const DOMAIN_NUMBER: number = 0xFF00;
复制代码
可通过 requestEnableNotification 的错误码判断用户是否授权。若返回的错误码为 1600004，即为拒绝授权。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;notificationManager.isNotificationEnabled().then((data: boolean) => { hilog.info(DOMAIN_NUMBER, TAG, "isNotificationEnabled success, data: " + JSON.stringify(data)); if(!data){ notificationManager.requestEnableNotification(context).then(() => { hilog.info(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification success`); }).catch((err : BusinessError) => { if(1600004 == err.code){ hilog.error(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification refused, code is ${err.code}, message is ${err.message}`); } else { hilog.error(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification failed, code is ${err.code}, message is ${err.message}`); } }); }}).catch((err : BusinessError) => { hilog.error(DOMAIN_NUMBER, TAG, `isNotificationEnabled fail, code is ${err.code}, message is ${err.message}`);});
复制代码
发布通知
Notification Kit 中常用的通知样式如下：
发布文本类型通知
文本类型通知主要应用于发送短信息、提示信息等，支持普通文本类型和多行文本类型。
首先导入对应模块：
import { notificationManager } from '@kit.NotificationKit';import { BusinessError } from '@kit.BasicServicesKit';import { hilog } from '@kit.PerformanceAnalysisKit';
const TAG: string = '[PublishOperation]';const DOMAIN_NUMBER: number = 0xFF00;
复制代码
接着构造 NotificationRequest 对象，并发布通知。
//普通文本类型通知由标题、文本内容和附加信息三个字段组成。let notificationRequest: notificationManager.NotificationRequest = { id: 1, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, // 普通文本类型通知 normal: { title: 'test_title', text: 'test_text', additionalText: 'test_additionalText', } }};notificationManager.publish(notificationRequest, (err: BusinessError) => { if (err) { hilog.error(DOMAIN_NUMBER, TAG, `Failed to publish notification. Code is ${err.code}, message is ${err.message}`); return; } hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in publishing notification.');});
//多行文本类型通知继承了普通文本类型的字段，同时新增了多行文本内容、内容概要和通知展开时的标题。let notificationRequest: notificationManager.NotificationRequest = { id: 3, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_MULTILINE, // 多行文本类型通知 multiLine: { title: 'test_title', text: 'test_text', briefText: 'test_briefText', longTitle: 'test_longTitle', lines: ['line_01', 'line_02', 'line_03'], } }};// 发布通知notificationManager.publish(notificationRequest, (err: BusinessError) => { if (err) { hilog.error(DOMAIN_NUMBER, TAG, `Failed to publish notification. Code is ${err.code}, message is ${err.message}`); return; } hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in publishing notification.');});
复制代码
进度条类型通知
进度条通知也是常见的通知类型，主要应用于文件下载、事务处理进度显示。当前系统提供了进度条模板，发布通知应用设置好进度条模板的属性值，如模板名、模板数据，通过通知子系统发送到通知栏显示。
目前系统模板仅支持进度条模板，通知模板 NotificationTemplate 中的 data 参数为用户自定义数据，用于显示与模块相关的数据。
首先需要先查询系统是否支持进度条模板，查询结果为支持 downloadTemplate 模板类通知。
notificationManager.isSupportTemplate('downloadTemplate').then((data:boolean) => { hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in supporting download template notification.'); let isSupportTpl: boolean = data; // isSupportTpl的值为true表示支持downloadTemplate模板类通知，false表示不支持}).catch((err: BusinessError) => { hilog.error(DOMAIN_NUMBER, TAG, `Failed to support download template notification. Code is ${err.code}, message is ${err.message}`);});
复制代码
如果支持，则构造进度条模板对象，并发布通知：
let notificationRequest: notificationManager.NotificationRequest = { id: 5, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, normal: { title: 'test_title', text: 'test_text', additionalText: 'test_additionalText' } }, // 构造进度条模板，name字段当前需要固定配置为downloadTemplate template: { name: 'downloadTemplate', data: { title: 'File Title', fileName: 'music.mp4', progressValue: 45 } }}
// 发布通知notificationManager.publish(notificationRequest, (err: BusinessError) => { if (err) { hilog.error(DOMAIN_NUMBER, TAG, `Failed to publish notification. Code is ${err.code}, message is ${err.message}`); return; } hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in publishing notification.');});
复制代码
取消通知
用户收到通知提醒后，点击通知并拉起应用到前台时，应用可以选择取消某条通知或所有通知。
例如，用户收到某个好友的 IM 消息，点击通知进入应用查看消息后，应用可以取消相关通知提醒。
取消通知代码示例：
// 当拉起应用到前台，查看消息后，调用该接口取消通知。 notificationManager.cancel(1, (err: BusinessError) => { if (err) { hilog.error(DOMAIN_NUMBER, TAG, `Failed to cancel notification. Code is ${err.code}, message is ${err.message}`); return; } hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in canceling notification.'); });
复制代码
用户通知服务 Notification Kit 适用场景
当应用处于前台运行时，开发者可以使用 Notification Kit 向用户发布通知。当应用转为后台时，本地通知发布通道关闭，开发者需要接入 Push Kit 进行云侧离线通知的发布。
开发者可以在多种场景中运用本地通知能力。如同步用户的上传下载进度、发布即时的客服支付通知、更新运动步数等。
Notification Kit 支持的能力主要包括:
HarmonyOS 对通知的使用做了下面限制：
单个应用已发布的通知在通知中心等系统入口的留存数量有限（当前规格最多 24 条）。
通知的长度不能超过 200KB（跨进程序列化大小限制）。
通知的发布频次和更新频次需要满足如下要求，否则会导致发布或更新失败，返回相应错误码。
单个应用发布新通知的频次累计不能超过每秒 10 条，更新通知的频次累计不能超过每秒 20 条。
所有三方应用发布新通知的频次累计不能超过每秒 15 条，更新通知的频次累计不能超过每秒 30 条。
4、IM 场景下通知实战
基础设置
IM 场景应用，比如微信、企微等，目前由于鸿蒙不像 Android 一样可以保活，在应用切换到后台后应用本身无法再做任何事情，目前采用类似于 iOS 的方式，提供了 Push Kit，应用在后台时可以通过 Push Kit 接收通知。但是目前 Push Kit 有个问题，iOS 的 Push Kit 可以在通知展示前通过询问应用的方式让 APP 干预通知是否展示，HarmonyOS 目前应用无法干预，就算应用在前台也无法干预。不过 HarmonyOS Push Kit 提供了应用在后台时展示通知消息，应用在前台时只接收通知消息自行完成业务处理，而不展示通知消息，只需在调用 REST API 推送通知消息，消息体中携带 foregroundShow 字段，并且设置为 false（默认为 true，表示前后台都展示），则应用在前台时不会展示通知消息：
// Request Body{ "payload": { "notification": { "category": "MARKETING", "title": "普通通知标题", "body": "普通通知内容", "profileId": "111***222", "clickAction": { "actionType": 0 }, "foregroundShow": false // 设置为false则应用在前台时不会展示通知消息 } }, "target": { "token": ["IQAAAA**********4Tw"] }}
复制代码
通过 receiveMessage()方法传入 PushType 为"DEFAULT"获取通知消息，用于应用在前台时接收通知消息，示例代码如下
import { UIAbility } from '@kit.AbilityKit';import { pushService } from '@kit.PushKit';import { BusinessError } from '@kit.BasicServicesKit';import { hilog } from '@kit.PerformanceAnalysisKit';
/** * 此处以PushMessageAbility为例，用于应用在前台时接收通知消息 */export default class PushMessageAbility extends UIAbility { onCreate(): void { try { // receiveMessage中的参数固定为DEFAULT pushService.receiveMessage('DEFAULT', this, (data) => { // process message，并建议对Callback进行try-catch try { // get notification passed by REST API const notification = JSON.parse(data.data)?.notification; hilog.info(0x0000, 'testTag', 'Succeeded in getting notification,data=%{public}s', JSON.stringify(notification)); } catch (e) { let errRes: BusinessError = e as BusinessError; hilog.error(0x0000, 'testTag', 'Failed to process data: %{public}d %{public}s', errRes.code, errRes.message); } }); } catch (err) { let e: BusinessError = err as BusinessError; hilog.error(0x0000, 'testTag', 'Failed to get message: %{public}d %{public}s', e.code, e.message); } }}
复制代码
应用在前台实现了类似透传消息的效果。
接下来我们在收到透传消息后根据业务逻辑自定义通知，比如正在跟 A 聊天停留在 A 聊天页面，那么此时 A 来消息则不进行通知栏通知，如果此时是另一个用户 B 来消息则要正常展示。
这里我们解析 Push Kit 透传内容，弹出普通文本通知：
const notification = JSON.parse(data.data)?.notification;let notificationRequest: notificationManager.NotificationRequest = { id: 1, content: { notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, // 普通文本类型通知 normal: { title: notification.title, text: 'notification.text', additionalText: 'notification.additional', } }};notificationManager.publish(notificationRequest, (err: BusinessError) => { if (err) { hilog.error(DOMAIN_NUMBER, TAG, `Failed to publish notification. Code is ${err.code}, message is ${err.message}`); return; } hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in publishing notification.');});
复制代码
角标设置
HarmonyOS 针对未读的通知，系统提供了角标设置接口，将未读通知个数显示在桌面图标的右上角角标上。通知增加时，角标上显示的未读通知个数需要增加。通知被查看后，角标上显示的未读通知个数需要减少，没有未读通知时，不显示角标。
增加角标个数：发布通知在 NotificationRequest 的 badgeNumber 字段里携带，下面示例为调用 setBadgeNumber 接口增加角标，在发布完新的通知后，调用该接口。
let setBadgeNumberCallback = (err: BusinessError): void => { if (err) { hilog.error(DOMAIN_NUMBER, TAG, `Failed to set badge number. Code is ${err.code}, message is ${err.message}`); return; } hilog.info(DOMAIN_NUMBER, TAG, `Succeeded in setting badge number.`);}
let badgeNumber = 9;notificationManager.setBadgeNumber(badgeNumber, setBadgeNumberCallback);
复制代码
减少角标个数。一条通知被查看后，应用需要调用接口设置剩下未读通知个数，桌面刷新角标。
let setBadgeNumberCallback = (err: BusinessError): void => { if (err) { hilog.error(DOMAIN_NUMBER, TAG, `Failed to set badge number. Code is ${err.code}, message is ${err.message}`); return; } hilog.info(DOMAIN_NUMBER, TAG, `Succeeded in setting badge number.`);}
let badgeNumber = 8;notificationManager.setBadgeNumber(badgeNumber, setBadgeNumberCallback);
复制代码
注意：由于 setBadgeNumber 为异步接口，使用 setBadgeNumber 连续设置角标时，为了确保执行顺序符合预期，需要确保上一次设置完成后才能进行下一次设置。
通知渠道设置
一些特殊的业务场景，不同类型的消息可能会有不同的提示音等配置，比如聊天消息和营销通知，HarmonyOS 系统支持多种通知渠道，不同通知渠道对应的通知提醒方式不同，可以根据应用的实际场景选择适合的通知渠道，并对通知渠道进行管理（支持创建、查询、删除等操作）。
不同类型的通知渠道对应的通知提醒方式不同，详见下表。其中，Y 代表支持，N 代表不支持。
// addslot回调let addSlotCallBack = (err: BusinessError): void => { if (err) { hilog.error(DOMAIN_NUMBER, TAG, `addSlot failed, code is ${err.code}, message is ${err.message}`); } else { hilog.info(DOMAIN_NUMBER, TAG, `addSlot success`); }}notificationManager.addSlot(notificationManager.SlotType.SOCIAL_COMMUNICATION, addSlotCallBack);
复制代码
自定义铃声
不同类型消息如果要设置不同铃声，可以通过 sound 字段，应用通知自定义铃声文件名。该文件必须放在 resources/rawfile 目录下，支持 m4a、aac、mp3、ogg、wav、flac、amr 等格式。
仅当应用申请并获得通知自定义铃声权益后，该字段方可生效。
当前该权益仅面向 AppGallery Connect 中“应用分类”为“应用/社交”且“应用标签”为“通讯”的应用开放。
开发者可以通过登录 AppGallery Connect，选择需要查看的应用，在左侧导航栏选择“应用上架 > 应用信息”，查询应用分类和应用标签是否符合条件。
通知点击
当发布通知时，我们一般期望用户可以通过点击通知栏拉起我们应用对应用户的聊天页，可以通过 Ability Kit 申请 WantAgent 封装至通知消息中。
处理流程如下：
下面示例是创建拉起 UIAbility 的 WantAgent 的 WantAgentInfo 信息。
let wantAgentObj:WantAgent; // 用于保存创建成功的wantAgent对象，后续使用其完成触发的动作。
// 通过WantAgentInfo的operationType设置动作类型let wantAgentInfo:wantAgent.WantAgentInfo = { wants: [ { deviceId: '', bundleName: 'com.samples.notification', abilityName: 'SecondAbility', action: '', entities: [], uri: '', parameters: {} } ], actionType: wantAgent.OperationType.START_ABILITY, requestCode: 0, wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]};
复制代码
5、总结
HarmonyOS 的 Notification Kit 为开发者提供本地通知管理能力，支持创建文本、多行文本、进度条等通知样式，并可实现角标更新、通知取消及自定义铃声等功能。与 Push Kit（云端推送）和 Call Kit（通话管理）形成互补：Notification Kit 处理本地即时通知，Push Kit 负责后台云消息推送，Call Kit 则专注于通话场景的交互管理。核心流程包括请求授权（isNotificationEnabled 查询、requestEnableNotification 弹窗）、构建通知模板（含标题、内容及扩展字段），通过 publish 接口触发展示，并支持按 ID 取消或批量清理通知。应用需注意系统限制：单应用通知留存上限 24 条，内容大小不超过 200KB，发布频次受限（前台每秒 10 条新通知）。实战中结合 Push Kit 可实现 IM 场景消息同步，通过 foregroundShow 字段控制前后台通知展示策略，并利用角标接口动态更新未读计数。该服务适用于即时通讯、进度同步等需用户即时感知的场景，但需注意通知渠道分类（如社交通信类支持全通道提醒）及自定义权益申请（如铃声需特定应用标签）。
评论