永远雪山1. HarmonyOS通知服务开发概述
在移动应用开发中，通知服务是连接用户与应用的重要桥梁。HarmonyOS的Notification Kit提供了一套完整的通知管理机制，支持从简单的文本通知到复杂的交互式通知。作为开发者，掌握这套API不仅能提升应用的用户体验，还能充分利用HarmonyOS的分布式能力实现跨设备通知流转。
当前HarmonyOS Next的适配工作正在如火如荼地进行，许多头部应用已经完成了对新一代通知系统的适配。从技术角度看，Notification Kit相比传统Android通知系统有几个显著优势：更低的功耗、更灵活的样式定制以及原生的分布式支持。这些特性使得HarmonyOS应用能够实现"一次开发，多端部署"的愿景。
提示：在开始开发前，请确保你的DevEco Studio已更新至最新版本，并创建了支持API Version 9+的项目。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 基础通知功能实现
2.1 创建简单文本通知
最基本的通知只需要几行代码就能实现。以下是一个发送简单文本通知的完整示例：
typescript复制import notification from '@ohos.notification';
async function sendBasicNotification() {
let request: notification.NotificationRequest = {
content: {
contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: {
title: '会议提醒',
text: '下午3点有项目评审会',
additionalText: '请准时参加'
}
},
id: 1 // 通知ID需要唯一
};
try {
await notification.publish(request);
console.log('通知发送成功');
} catch (err) {
console.error(`发送通知失败: ${err.code}, ${err.message}`);
}
}
这段代码展示了Notification Kit最基本的用法。其中几个关键点需要注意：
contentType指定了通知类型，基础文本通知使用NOTIFICATION_CONTENT_BASIC_TEXTnormal对象包含了通知的主要内容：标题(title)、正文(text)和附加文本(additionalText)- 每个通知需要唯一的
id，用于后续更新或取消通知
2.2 通知渠道配置
从API Version 9开始，HarmonyOS引入了类似Android的通知渠道概念，但实现更加灵活：
typescript复制async function createNotificationChannel() {
let channel: notification.NotificationChannel = {
id: 'important_channel',
name: '重要通知',
description: '用于接收重要系统通知',
importance: notification.ImportanceLevel.LEVEL_HIGH,
enableVibration: true,
vibrationValues: [200, 300, 200, 300] // 振动模式：震动200ms，暂停300ms，重复
};
try {
await notification.addSlot(channel);
console.log('通知渠道创建成功');
} catch (err) {
console.error(`创建渠道失败: ${err.code}, ${err.message}`);
}
}
在实际项目中，建议在应用启动时就创建好所有需要的通知渠道。渠道一旦创建就不能修改大部分属性（除了名称和描述），所以前期设计很重要。
3. 高级通知功能开发
3.1 交互式通知实现
交互式通知允许用户直接在通知栏完成操作，无需打开应用。以下是带按钮的通知实现：
typescript复制async function sendActionNotification() {
let request: notification.NotificationRequest = {
content: {
contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: {
title: '新消息',
text: '您收到一条好友请求',
additionalText: '点击查看详情'
}
},
actions: [
{
title: '接受',
wantAgent: {
pkgName: 'com.example.myapp',
abilityName: 'AcceptFriendAbility'
}
},
{
title: '拒绝',
wantAgent: {
pkgName: 'com.example.myapp',
abilityName: 'RejectFriendAbility'
}
}
],
id: 2
};
try {
await notification.publish(request);
} catch (err) {
console.error(`发送交互通知失败: ${err.code}, ${err.message}`);
}
}
注意：wantAgent配置需要与config.json中声明的ability对应，否则点击按钮不会有任何响应。
3.2 进度条通知
对于下载、上传等长时间运行的任务，进度条通知能提供良好的用户反馈：
typescript复制async function showProgressNotification() {
let request: notification.NotificationRequest = {
content: {
contentType: notification.ContentType.NOTIFICATION_CONTENT_PROGRESS,
progress: {
title: '文件下载中',
text: 'project.zip',
progressValue: 0,
progressMaxValue: 100
}
},
isOngoing: true, // 设置为持续通知，用户无法手动清除
id: 3
};
// 首次发布通知
await notification.publish(request);
// 模拟进度更新
for (let i = 0; i <= 100; i += 10) {
request.content.progress.progressValue = i;
await new Promise(resolve => setTimeout(resolve, 500));
await notification.publish(request);
}
// 下载完成后更新为完成状态
request.content = {
contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: {
title: '下载完成',
text: 'project.zip已下载完毕'
}
};
request.isOngoing = false;
await notification.publish(request);
}
4. 分布式通知实战
4.1 跨设备通知实现
HarmonyOS的分布式能力是其核心特色之一，通知服务也支持跨设备流转：
typescript复制async function sendDistributedNotification() {
let request: notification.NotificationRequest = {
content: {
contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: {
title: '跨设备提醒',
text: '这条通知来自你的手机',
additionalText: '试试在其他设备上查看'
}
},
distributedOptions: {
isDistributed: true,
supportDisplayDevices: ['phone', 'tablet', 'tv'], // 支持显示的设备类型
supportOperateDevices: ['phone'] // 支持操作的设备类型
},
id: 4
};
try {
await notification.publish(request);
} catch (err) {
console.error(`发送分布式通知失败: ${err.code}, ${err.message}`);
}
}
4.2 分布式通知权限管理
要实现分布式通知，需要在config.json中声明必要权限：
json复制{
"module": {
"reqPermissions": [
{
"name": "ohos.permission.NOTIFICATION_CONTROLLER",
"reason": "用于发送分布式通知"
},
{
"name": "ohos.permission.DISTRIBUTED_DATASYNC",
"reason": "用于设备间数据同步"
}
]
}
}
同时，应用安装后需要用户手动授权这些权限。可以在应用启动时检查并请求权限：
typescript复制import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
async function requestNotificationPermissions() {
let atManager = abilityAccessCtrl.createAtManager();
try {
await atManager.requestPermissionsFromUser(
getContext(this),
['ohos.permission.NOTIFICATION_CONTROLLER', 'ohos.permission.DISTRIBUTED_DATASYNC']
);
} catch (err) {
console.error(`权限请求失败: ${err.code}, ${err.message}`);
}
}
5. 通知样式深度定制
5.1 多媒体通知样式
对于音乐、视频类应用，可以使用多媒体通知样式：
typescript复制async function sendMediaNotification() {
let request: notification.NotificationRequest = {
content: {
contentType: notification.ContentType.NOTIFICATION_CONTENT_MEDIA,
media: {
title: '正在播放',
text: 'HarmonyOS主题曲',
additionalText: '华为音乐',
mediaImage: $r('app.media.music_cover'), // 引用资源文件
showControls: true // 显示播放控制按钮
}
},
actions: [
{
title: '上一首',
wantAgent: {
pkgName: 'com.example.music',
abilityName: 'PrevSongAbility'
}
},
// 其他按钮...
],
id: 5
};
try {
await notification.publish(request);
} catch (err) {
console.error(`发送媒体通知失败: ${err.code}, ${err.message}`);
}
}
5.2 自定义通知布局
对于需要高度定制化的场景，可以使用NotificationTemplate：
typescript复制async function sendCustomNotification() {
let template: notification.NotificationTemplate = {
name: 'custom_template',
data: {
title: '自定义通知',
content: '这是一个完全自定义布局的通知',
icon: $r('app.media.custom_icon'),
// 其他自定义字段...
}
};
let request: notification.NotificationRequest = {
template: template,
id: 6
};
try {
await notification.publish(request);
} catch (err) {
console.error(`发送自定义通知失败: ${err.code}, ${err.message}`);
}
}
提示：自定义模板需要在应用的resources/base/profile/目录下创建对应的json模板文件，定义布局结构。
6. 通知管理与最佳实践
6.1 通知生命周期管理
良好的通知管理能提升用户体验并节省系统资源：
typescript复制// 取消单个通知
async function cancelNotification(id: number) {
try {
await notification.cancel(id);
console.log('通知已取消');
} catch (err) {
console.error(`取消通知失败: ${err.code}, ${err.message}`);
}
}
// 取消所有通知
async function cancelAllNotifications() {
try {
await notification.cancelAll();
console.log('所有通知已取消');
} catch (err) {
console.error(`取消所有通知失败: ${err.code}, ${err.message}`);
}
}
// 获取所有活动通知
async function getActiveNotifications() {
try {
let notifications = await notification.getActiveNotifications();
console.log(`当前有${notifications.length}个活动通知`);
return notifications;
} catch (err) {
console.error(`获取活动通知失败: ${err.code}, ${err.message}`);
return [];
}
}
6.2 通知策略优化
在实际开发中，有几个关键点需要注意：
-
通知ID管理：建议使用业务相关的ID生成策略，避免简单的自增数字。例如，聊天消息可以使用"chat_"+消息ID作为通知ID。
-
通知更新策略：对于频繁更新的通知（如下载进度），不要每次都创建新通知，而是更新已有通知，避免通知栏闪烁。
-
分布式通知限制：考虑到设备性能差异，分布式通知的内容大小应控制在合理范围内，建议不超过5KB。
-
多语言支持：所有通知文本都应支持多语言，可以通过资源引用的方式实现：
typescript复制normal: {
title: $r('app.string.notification_title'),
text: $r('app.string.notification_text')
}
- 性能考虑：避免在短时间内发送大量通知，这可能导致系统限制你的应用发送通知。对于批量消息，考虑合并通知。
7. 常见问题排查
7.1 通知不显示的排查步骤
当通知没有按预期显示时，可以按照以下步骤排查：
-
检查权限：确认应用已经获得了ohos.permission.NOTIFICATION_CONTROLLER权限。
-
验证渠道：确保通知使用的渠道已经正确创建，并且没有被用户禁用。
-
查看系统设置：检查系统设置中是否禁用了应用的通知权限。
-
日志分析：查看DevEco Studio的Log窗口，过滤"Notification"相关日志。
-
测试简单通知：尝试发送一个最基本的文本通知，确认是否是代码问题还是特定通知类型的问题。
7.2 分布式通知不工作的解决方案
分布式通知依赖设备间的连接和同步，常见问题包括：
-
设备未连接：确保设备登录了相同的华为账号，并在同一局域网下。
-
能力未声明：在config.json中正确声明分布式能力：
json复制"abilities": [
{
"name": "MainAbility",
"supportDistributed": true,
// 其他配置...
}
]
-
权限不足：除了通知权限，还需要DISTRIBUTED_DATASYNC权限。
-
设备不支持：检查目标设备是否支持分布式通知功能。
8. HarmonyOS Next适配要点
随着HarmonyOS Next的推出，通知服务也有一些新的变化需要适配：
-
新的权限模型：Next版本引入了更严格的权限管理，需要重新检查权限申请逻辑。
-
后台限制：对后台应用的通知发送有更严格的限制，建议使用系统任务机制替代长时间后台运行。
-
模板系统升级：自定义通知模板的语法有更新，需要检查现有模板是否兼容。
-
分布式能力增强：Next版本支持更丰富的设备类型，可以探索手表、车载设备等新场景。
适配HarmonyOS Next的关键步骤：
- 更新DevEco Studio到最新版本
- 修改项目配置文件中的compileSdkVersion和compatibleSdkVersion
- 测试现有通知功能，特别是分布式场景
- 根据控制台警告和错误信息逐步修复兼容性问题
在实际项目中，我发现及时关注官方文档更新非常重要。华为开发者联盟会定期发布API变更说明，建议每周至少查看一次。对于关键业务功能的通知，最好在真机上进行全面测试，因为模拟器的行为有时与真实设备有差异。