引言通知是移动应用中连接用户与信息的桥梁。一条好的通知——在恰当的时机、以恰当的形式、携带恰当的信息量——可以显著提升用户活跃度和留存率。反之通知权限被拒绝、通知内容不当、通知频率过高则会让用户直接卸载应用。HarmonyOS NEXT 提供了完整的通知管理 API——ohos.notificationManagerNotification Kit支持从权限检测、授权请求、通知发布、通知取消到多种内容类型的基础/长文本/多行/图片通知的统一管理。所有 API 均为异步操作支持 Promise 和 callback 两种调用方式完美集成在 ArkTS 开发流程中。本文构建一个通知管理实验室Demo在页面内实现通知权限检测与请求、三种通知内容类型基础文本/长文本/多行文本的创建与发布、通知取消管理按 ID 取消 / 全部取消、操作日志追踪等功能全面演示通知管理的完整工作流。读完本文你将掌握权限管理isNotificationEnabled()/requestEnableNotification()— 检测与请求通知权限发布通知publish(NotificationRequest)— 构造通知请求体并发布取消通知cancel(id)/cancelAll()— 按 ID 或全部清除通知三种内容类型NOTIFICATION_CONTENT_BASIC_TEXT/LONG_TEXT/MULTILINE— 适配不同信息密度的场景NotificationContent 数据结构每种类型对应的normal/longText/multiLine字段错误处理Promise.catch() 模式捕获发布失败、权限拒绝等异常一、notificationManager 体系总览1.1 导入与模块结构import{notificationManager}fromkit.NotificationKit;notificationManager是一个全局单例对象所有 API 通过它调用。在 API 24 DevEco Studio 6.1.1 环境中推荐使用kit.NotificationKit导入路径。1.2 核心 API 速查表API说明返回值权限要求isNotificationEnabled()检查当前应用通知是否已启用Promiseboolean无requestEnableNotification()弹出系统对话框请求通知权限Promisevoid无publish(request)发布一条通知Promisevoid无基础通知cancel(id)按 ID 取消指定通知Promisevoid无cancelAll()取消当前应用所有通知Promisevoid无setBadgeNumber(num)设置桌面角标数字Promisevoid无isBadgeDisplayed()检查角标是否启用Promiseboolean无addSlot(slot)添加通知渠道Promisevoid无getSlot(slotType)获取通知渠道配置PromiseNotificationSlot无核心发现基本的发布/取消/权限操作全部无需声明任何权限开箱即用。这是鸿蒙通知系统设计中非常友好的一个特点——Android 的通知权限管理相对复杂需要 NotificationChannel 运行时权限而 HarmonyOS 将其大幅简化。1.3 通知内容类型总览HarmonyOS 支持四种通知内容类型内容类型枚举值对应字段适用场景基础文本NOTIFICATION_CONTENT_BASIC_TEXTnormal即时通讯消息、系统提醒长文本NOTIFICATION_CONTENT_LONG_TEXTlongText邮件预览、详情摘要多行文本NOTIFICATION_CONTENT_MULTILINEmultiLine待办事项列表、消息汇总图片通知NOTIFICATION_CONTENT_PICTUREpicture截图分享、富媒体推送每种类型对应NotificationContent中不同的数据字段下文将逐一展开。二、NotificationRequest — 通知请求体详解NotificationRequest是publish()方法的核心参数它定义了一条通知的全部属性interfaceNotificationRequest{id:number;// 通知 ID同一应用内唯一用于后续取消content:NotificationContent;// 通知内容根据 contentType 选择不同字段deliveryTime?:number;// 定时发布时间戳毫秒showDeliveryTime?:boolean;// 是否在通知栏显示发送时间notificationSlotType?:notificationManager.SlotType;// 通知渠道类型isFloatingIcon?:boolean;// 是否显示浮动图标tapDismissed?:boolean;// 点击后是否自动消失color?:number;// 通知颜色badgeNumber?:number;// 角标数字可覆盖全局角标}关键字段说明id整数类型同一应用中每条通知必须有唯一 ID。发布同 ID 的通知会覆盖之前的那条。contentNotificationContent类型是通知内容的核心载体结构因notificationContentType而异。notificationSlotType通知渠道类型社交、服务提醒、内容资讯等影响系统对通知的排序和展示策略。tapDismissed设为true时用户点击通知后自动从通知栏消失。三、NotificationContent — 四种内容类型详解3.1 NOTIFICATION_CONTENT_BASIC_TEXT — 基础文本最基本的通知类型包含标题和正文letcontent:notificationManager.NotificationContent{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,normal:{title:会议提醒,text:14:00 在 3 号会议室进行项目评审,additionalText:还有 3 人未确认出席// 可选补充信息}};normal对应的NotificationBasicContent接口字段类型必填说明titlestring是通知标题textstring是通知正文内容additionalTextstring否补充文本显示在标题上方或下方基础文本通知适合绝大多数场景即时通讯消息、任务提醒、状态变更通知等。3.2 NOTIFICATION_CONTENT_LONG_TEXT — 长文本当通知正文很长时使用长文本类型——系统在通知栏只显示摘要用户展开后看到完整内容letcontent:notificationManager.NotificationContent{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_LONG_TEXT,longText:{title:邮件预览,text:周报本周进度正常完成了核心模块开发,// 收起的摘要briefText:周报摘要,// 展开前的简洁描述longText:详细内容本周完成了用户模块、订单模块的接口开发...此处可放大量文字}};longText对应的NotificationLongTextContent接口字段类型必填说明titlestring是通知标题textstring是通知概要收起状态显示briefTextstring是展开前的简短摘要longTextstring是完整长文本展开后显示使用场景邮件摘要、新闻摘要、系统更新日志ChangeLog等需要携带较多信息的通知。3.3 NOTIFICATION_CONTENT_MULTILINE — 多行文本以列表形式展示多条信息每条占一行letcontent:notificationManager.NotificationContent{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_MULTILINE,multiLine:{title:今日待办,text:共 4 项待处理任务,briefText:点击查看详情,lines:[代码评审PR #234 — 需要你的 Review,Bug 修复登录页偶发崩溃 — 优先级 P0,会议16:00 周会 — 3 楼会议室,文档更新 API 对接文档 — 本周五前]}};multiLine对应的NotificationMultiLineContent接口字段类型必填说明titlestring是通知标题textstring是概要描述briefTextstring否展开前的简短描述linesArraystring是每行一条文本在通知栏展开后逐行显示注意lines数组的元素数量没有硬性上限但建议控制在 5-8 条以内以保证可读性。3.4 NOTIFICATION_CONTENT_PICTURE — 图片通知附带大图的富媒体通知letcontent:notificationManager.NotificationContent{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_PICTURE,picture:{title:截图已保存,text:截屏已保存到相册,additionalText:点击查看,picture:pixelMap// image.PixelMap 对象}};图片通知需要提供一个image.PixelMap对象适用于截图分享、图片消息推送等场景。由于需要获取 PixelMap这部分实现比文本通知复杂本文 Demo 以三种文本类型为主图片通知作为知识扩展。四、权限管理 — 检测与授权4.1 isNotificationEnabled() — 检测通知状态notificationManager.isNotificationEnabled().then((enabled:boolean){if(enabled){// 通知已启用可以直接发布}else{// 通知未启用需要引导用户开启}}).catch((err:Error){console.error(检测失败: err.message);});这个 API 返回一个Promisebooleantrue表示用户已允许通知false表示用户关闭了通知或从未授权。最佳实践在应用首次启动或关键操作前调用此方法根据结果决定 UI 展示显示开启通知引导按钮或正常的通知功能入口。4.2 requestEnableNotification() — 请求授权notificationManager.requestEnableNotification().then((){// 用户同意了通知授权}).catch((err:Error){// 用户拒绝了授权// 注意用户拒绝后不会再次弹出系统对话框// 需要引导用户前往系统设置手动开启});重要行为说明第一次调用弹出系统级对话框显示允许和禁止两个选项用户拒绝后再次调用不会弹出对话框系统层面的防骚扰机制直接进入 catch用户已经允许后调用直接进入 then不弹窗因此如果用户拒绝了通知权限唯一的恢复方式是引导用户前往系统设置手动开启。五、发布与取消 — 通知的完整生命周期5.1 publish() — 发布通知letrequest:notificationManager.NotificationRequest{id:100,content:{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,normal:{title:新消息,text:你有一条来自张三的未读消息}}};notificationManager.publish(request).then((){console.log(通知发布成功);}).catch((err:Error){console.error(发布失败: err.message);});发布注意事项ID 管理同一 ID 的通知后发会覆盖先发。应用中应维护一个递增计数器或使用时间戳来生成唯一 ID立即生效publish()调用成功后通知几乎立即出现在通知栏无deliveryTime的情况下通知栏限流系统对短时间内大量发布有流控机制批量通知场景需要控制频率5.2 cancel() — 按 ID 取消notificationManager.cancel(100).then((){console.log(通知 #100 已取消);});关键点只能取消当前应用发布的通知不能取消其他应用的通知这保证了系统安全。5.3 cancelAll() — 取消全部notificationManager.cancelAll().then((){console.log(所有通知已清除);});cancelAll()会清除当前应用在通知栏的所有通知无需逐个指定 ID。典型使用场景用户退出登录时清除所有与该账户相关的通知应用启动时清除旧会话的残留通知一键已读功能取消所有通知并更新角标5.4 错误处理模式所有 notificationManager API 都返回 Promise推荐使用统一的错误处理notificationManager.publish(request).then((){// 成功}).catch((err:Error){// 失败 — 常见原因// 1. 通知权限被拒绝// 2. 通知 ID 非法负数或 0// 3. content 必填字段缺失console.error(通知操作失败: err.message);});六、实战 Demo通知管理实验室页面结构通知管理实验室 ├── 标题栏 — 通知管理实验室 ohos.notificationManager ├── 通知状态卡片 │ ├── 通知启用状态指示器绿色圆点 已启用/红色圆点 未启用 │ └── 请求通知权限按钮仅在未启用时显示 ├── 发布通知卡片 │ ├── 通知类型选择器水平滚动标签基础文本/长文本/多行文本 │ ├── 标题输入框 │ ├── 正文内容输入框 │ ├── 条件内容区按类型动态切换 │ │ ├── 基础文本无额外字段 │ │ ├── 长文本长文本正文输入框多行 TextArea │ │ └── 多行文本动态行列表每行可编辑/可删除可添加新行 │ ├── 发布按钮 │ └── 已发布计数和下一个 ID 显示 ├── 通知管理卡片 │ ├── 取消最近一条按钮 │ ├── 取消全部通知按钮 │ └── 重新检测状态链接 ├── 操作日志卡片 │ └── 时间 操作类型颜色区分 详情最多 30 条 ├── 通知内容类型参考卡片4 种类型说明 └── 核心 API 参考 — 8 个关键 API4 个交互点通知权限检测与请求— 页面启动时自动检测通知状态未启用时显示请求通知权限按钮点击后弹出系统授权对话框三种通知类型切换发布— 顶部标签栏切换基础文本/长文本/多行文本每种类型显示对应的内容输入区填写后点击发布通知将通知发送到系统通知栏通知取消管理— 取消最近一条按 ID 精确取消取消全部通知一键清除所有通知发布计数实时更新操作日志追踪— 每次发布/取消/权限操作都会生成时间戳日志日志以颜色区分操作类型蓝色发布红色取消绿色权限最多保留 30 条核心代码实现权限检测aboutToAppear():void{notificationManager.isNotificationEnabled().then((enabled:boolean){this.notifyEnabledenabled?已启用:未启用;}).catch((){this.notifyEnabled检测失败;});}页面启动时自动检测结果存入State notifyEnabledUI 根据状态显示绿色/红色指示器和相应按钮。按类型构造 NotificationContentpublishNotification():void{letidthis.nextId;this.nextId;letcontent:notificationManager.NotificationContent{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,normal:{title:this.notifTitle,text:this.notifText}};if(this.activeType1){content{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_LONG_TEXT,longText:{title:this.notifTitle,text:this.notifText,briefText:this.notifText,longText:this.longText}};}elseif(this.activeType2){letlinesthis.multilineLines.split(\n);content{notificationContentType:notificationManager.ContentType.NOTIFICATION_CONTENT_MULTILINE,multiLine:{title:this.notifTitle,text:this.notifText,briefText:共 lines.length 条信息,lines:lines}};}letrequest:notificationManager.NotificationRequest{id:id,content:content};notificationManager.publish(request).then((){this.publishCount;this.addLog(发布,#id — this.notifTitle);}).catch((err:Error){this.addLog(失败,#id 发布失败: err.message);});}核心逻辑根据activeType0/1/2选择对应的notificationContentType和内容字段构造NotificationContent嵌入NotificationRequest调用publish()。动态多行编辑多行文本的通知需要用户编辑多行内容Demo 通过split(\n)将字符串转换为数组再通过ForEach渲染每一行为独立的TextInputForEach(this.getLineArray(),(line:string,idx:number){Row(){TextInput({text:line}).fontSize(11).layoutWeight(1).height(34).onChange((v:string){this.updateLine(idx,v);})Text(✕).fontColor(#EF4444).width(28).textAlign(TextAlign.Center).onClick((){this.deleteLine(idx);})}.width(100%).margin({bottom:4})})addLine()追加新行deleteLine(index)移除指定行至少保留 1 行updateLine(index, value)更新指定行的内容。操作日志追踪addLog(action:string,detail:string):void{letnownewDate();lettimenow.getHours().toString().padStart(2,0):now.getMinutes().toString().padStart(2,0):now.getSeconds().toString().padStart(2,0);letcopy:NotifyLog[][];for(leti0;ithis.logs.length;i){copy.push(this.logs[i]);}copy.push(newNotifyLog(time,action,detail));if(copy.length30){copycopy.slice(copy.length-30);}this.logscopy;}日志数组的更新遵循 ArkTS 不可变状态更新模式创建新数组 → 拷贝旧元素 → push 新条目 → slice 限长 → 赋值给State。预览效果预期状态检测页面加载后通知状态栏显示绿色已启用或红色未启用未启用时出现蓝色授权按钮基础文本通知填写标题和内容后点击发布通知通知栏立即出现一条标准通知长文本通知切换到长文本标签填写长文本正文后发布通知在通知栏展开后显示完整内容多行文本通知切换到多行文本标签动态添加/编辑/删除行发布后通知栏显示多行列表取消操作点击取消最近一条移除最新发布的通知取消全部通知清除所有日志追踪每次操作产生一条彩色日志发布蓝、取消红、授权绿七、与 Android NotificationManager 的对比维度HarmonyOS notificationManagerAndroid NotificationManager导入kit.NotificationKitandroid.app.NotificationManager权限检测isNotificationEnabled()返回 PromiseareNotificationsEnabled()同步返回权限请求requestEnableNotification()弹系统对话框无直接 API需跳转到设置页通知渠道NotificationSlotType枚举简化必须创建NotificationChannel发布方式publish(NotificationRequest)Promisenotify(id, notification)同步内容类型NotificationContent 四种 contentTypeNotificationCompat.Builder StyleBuilder 模式无 Builder直接构造对象NotificationCompat.Builder流式 API多行文本multiLine.lines: string[]NotificationCompat.InboxStyleHarmonyOS 的优势无需 Builder直接构造对象代码更简洁权限请求内置requestEnableNotification()一键弹窗Android 需要手动跳转设置通知渠道简化枚举值选择而非强制性创建降低初学者的心智负担Android 的优势通知渠道的精细控制重要性等级、振动模式、LED 颜色等可逐渠道独立配置通知组的折叠展开控制更灵活八、实战技巧与常见问题8.1 通知 ID 管理策略推荐的 ID 生成方式// 方式一递增计数器privatenextId:numberDate.now();// 用时间戳初始化避免与旧通知冲突nextId;// 方式二业务 ID 映射如消息 IDletnotificationIdmessage.messageId;注意使用较小的固定数字作为 ID 容易导致覆盖。建议使用 4 位以上的递增整数或业务相关 ID。8.2 被拒绝后的用户引导requestEnableNotification()被拒绝后不会再次弹窗。此时应检测isNotificationEnabled()返回false显示引导文字“通知权限已被关闭请前往系统设置 应用 通知管理中开启”提供去设置按钮通过bundleManager.canOpenLink或openLink跳转到应用设置页8.3 通知发布失败的常见原因通知权限未开启—isNotificationEnabled()返回 false必填字段缺失—title或text为空字符串contentType 与内容字段不匹配— 声明了 BASIC_TEXT 但赋值了longText字段通知 ID 非法— 使用负数或 0 作为 ID九、总结ohos.notificationManager是 HarmonyOS 通知系统的统一入口提供了一套简洁、Promise-first 的异步 API覆盖了从权限管理到通知发布/取消的完整生命周期零权限起步基础的通知发布/取消/检测无需任何权限声明降低了接入门槛四种内容类型BASIC_TEXT / LONG_TEXT / MULTILINE / PICTURE 覆盖了从简单文本到富媒体的全场景Promise 驱动所有 API 返回 Promise天然适配 async/await 和链式处理权限管理简单isNotificationEnabled()requestEnableNotification()两步完成检测与授权取消灵活支持按 ID 精确取消和全部清除满足消息撤回、已读管理等需求数据结构清晰NotificationRequest→NotificationContent→ 类型对应的内容字段层次分明对于 HarmonyOS 开发者而言Notification Kit 是应用与用户保持连接的基础设施。无论是即时通讯的消息推送、协作工具的任务提醒、还是电商应用的活动通知这套 API 都提供了足够灵活和强大的支持。结合实战 Demo 中的三种通知类型切换、多行动态编辑、操作日志追踪等功能开发者可以快速上手并集成到实际项目中。
