用户通知服务，轻松实现应用与用户的多场景交互
用户在使用应用时，经常想要了解应用程序在执行的操作，如下载完成、新邮件到达、发布即时的客服支付通知等，这些通知除了携带基本的文本图片信息外，最好还可以支持文件上传下载进度场景下的进度条通知，以及点击通知栏可以拉起目标应用的意图类型通知。开发者只有满足用户多种场景本地通知的需求，才能带来更好的用户体验。
HarmonyOS SDK用户通知服务（Notification Kit）为开发者提供本地通知发布通道，开发者可借助Notification Kit将应用产生的通知直接在客户端本地推送给用户，本地通知根据通知类型、用户设置及发布场景会产生对应的铃声、震动、横幅、锁屏、息屏、通知栏提醒和显示。
能力范围
Notification Kit支持的能力主要包括：
• 发布文本、进度条等类型通知。
• 携带或更新应用通知数字角标。
• 取消曾经发布的某条或全部通知。
• 查询已发布的通知列表。
• 查询应用自身通知开关状态。
• 应用通知用户的能力默认关闭，开发者可拉起授权框，请求用户授权发布通知。
业务流程
使用Notification Kit的主要业务流程如下：
1.请求用户通知授权。
2.应用发布通知到通知服务。
3.用户通过授权后，将通知展示到通知中心。
通知样式
Notification Kit中常用的通知样式如下：
开发步骤
请求通知授权
- 导入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 = getContext(this) 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}`);
});
管理通知角标
- 导入NotificationManager模块。
import { notificationManager } from '@kit.NotificationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 增加角标个数。
发布通知在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);
管理通知渠道
- 导入notificationManager模块。
import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 创建指定类型的通知渠道。
// addslot回调
let addSlotCallBack = (err: BusinessError): void => {if (err) {hilog.info(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);
- 查询指定类型的通知渠道。
获取对应渠道是否创建以及该渠道支持的通知提醒方式，比如是否有声音提示，是否有震动，锁屏是否可见等。
// getSlot回调
let getSlotCallback = (err: BusinessError, data: notificationManager.NotificationSlot): void => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `getSlot failed, code is ${JSON.stringify(err.code)}, message is ${JSON.stringify(err.message)}`);} else {hilog.info(DOMAIN_NUMBER, TAG, `getSlot success. `);if (data != null) {hilog.info(DOMAIN_NUMBER, TAG, `slot enable status is ${JSON.stringify(data.enabled)}`);hilog.info(DOMAIN_NUMBER, TAG, `slot level is ${JSON.stringify(data.level)}`);hilog.info(DOMAIN_NUMBER, TAG, `vibrationEnabled status is ${JSON.stringify(data.vibrationEnabled)}`);hilog.info(DOMAIN_NUMBER, TAG, `lightEnabled status is ${JSON.stringify(data.lightEnabled)}`);}}
}
let slotType: notificationManager.SlotType = notificationManager.SlotType.SOCIAL_COMMUNICATION;
notificationManager.getSlot(slotType, getSlotCallback);
- 删除指定类型的通知渠道。
// removeSlot回调
let removeSlotCallback = (err: BusinessError): void => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `removeSlot failed, code is ${JSON.stringify(err.code)}, message is ${JSON.stringify(err.message)}`);} else {hilog.info(DOMAIN_NUMBER, TAG, "removeSlot success");}
}
let slotType: notificationManager.SlotType = notificationManager.SlotType.SOCIAL_COMMUNICATION;
notificationManager.removeSlot(slotType, removeSlotCallback);
发布通知
发布文本类型通知
- 导入模块。
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对象，并发布通知。
普通文本类型通知由标题、文本内容和附加信息三个字段组成，其中标题和文本内容是必填字段，大小均需要小于200字节，超出部分会被截断。
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.');
});
多行文本类型通知继承了普通文本类型的字段，同时新增了多行文本内容、内容概要和通知展开时的标题，其字段均小于200字节，超出部分会被截断。通知默认显示与普通文本相同，展开后，标题显示为展开后标题内容，多行文本内容多行显示。
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', 'line_04'],}}
};
// 发布通知
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.');
});
发布进度条类型通知
- 导入模块。
import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 查询系统是否支持进度条模板，查询结果为支持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字段当前需要固定配置为downloadTemplatetemplate: {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.');
});
为通知添加行为意图
- 导入模块。
import { notificationManager } from '@kit.NotificationKit';
import { wantAgent, WantAgent } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;
- 创建WantAgentInfo信息。
场景一：创建拉起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]
};
场景二：创建发布公共事件的WantAgent的WantAgentInfo信息。
let wantAgentObj:WantAgent; // 用于保存创建成功的WantAgent对象，后续使用其完成触发的动作。
// 通过WantAgentInfo的operationType设置动作类型
let wantAgentInfo:wantAgent.WantAgentInfo = {wants: [{action: 'event_name', // 设置事件名parameters: {},}],actionType: wantAgent.OperationType.SEND_COMMON_EVENT,requestCode: 0,wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG],
};
- 调用getWantAgent()方法进行创建WantAgent。
// 创建WantAgent
wantAgent.getWantAgent(wantAgentInfo, (err: BusinessError, data:WantAgent) => {if (err) {hilog.error(DOMAIN_NUMBER, TAG, `Failed to get want agent. Code is ${err.code}, message is ${err.message}`);return;}hilog.info(DOMAIN_NUMBER, TAG, 'Succeeded in getting want agent.');wantAgentObj = data;
});
- 构造NotificationRequest对象，并发布WantAgent通知。
// 构造NotificationRequest对象
let notificationRequest: notificationManager.NotificationRequest = {content: {notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,normal: {title: 'Test_Title',text: 'Test_Text',additionalText: 'Test_AdditionalText',},},id: 6,label: 'TEST',// wantAgentObj使用前需要保证已被赋值（即步骤3执行完成）wantAgent: wantAgentObj,
}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.');
});
- 用户通过点击通知栏上的通知，系统会自动触发WantAgent的动作。
了解更多详情>>
获取用户通知服务开发指导文档