真机交互鸿蒙 PC 实战:一条 `publish()` 之下,通知其实拆成了渠道、分组、角标、WantAgent 和活跃列表五类对象
真机交互鸿蒙 PC 实战:一条 publish() 之下,通知其实拆成了渠道、分组、角标、WantAgent 和活跃列表五类对象
订单状态从「下单成功」到「已发货」再到「已送达」,我一开始以为就是换个标题多调几次
publish(),结果真机上要么点了没反应、要么三条通知挤在一起分不清、要么点了通知回不到应用。后来把notificationManager的 API 摊开才看清楚:一条通知背后根本不是一个对象,而是NotificationRequest(内容)、NotificationSlot(渠道)、groupName(分组)、badgeNumber(角标)、WantAgent(点击意图)五类各自独立的系统对象,还有getActiveNotifications()那个只认系统通知栏、不认我内存数组的活跃列表。这篇文章用 tauri-hello「真机交互」页从 4 个通知方法扩到 12 个、把一条订单的推送跑成一套完整通知体系的真实记录,把content到底要凑齐哪些字段、渠道分级为什么不能只用一个 slot、批量 id 相同为什么是更新不是新增、点通知拉起应用要挂什么、浏览器预览为什么不该假装弹了状态栏这几个问题一次讲透。
先交代这一篇在代码里的落点,免得读者翻的时候找不到:
- 通知能力实现:
tauri-hello/entry/src/main/ets/bridge/SystemCapability.ets(1951 行,notify*方法集中在 974–1542 行) - 分发入口:
SystemCapability.call()的 500–511 行,interact.notify.*共 12 个 case - Bridge 转发:
entry/src/main/ets/bridge/MallBridge.ets,sysCall(method, params)一处 - 注入白名单:
entry/src/main/ets/pages/Index.ets,javaScriptProxy.methodList里只放sysCall - 前端交互:
www/js/app.js的capInteractNotify*(1574–1666 行,12 个函数) - 页面区块:
www/index.html996–1028 行(真机交互页),855–870 行(系统能力页那套模拟) - 统一回包:
ok()/err()在 1850–1859 行,{ ok, code, data, message } - SDK 依据:
@ohos.notificationManager.d.ts、notification/notificationContent.d.ts、@ohos.app.ability.wantAgent.d.ts(API 26) - 设备能力清单:
ets/api/device-define/2in1.json
这一系列四篇各讲一个真机交互能力,知识点不串台:这一篇只讲通知 notificationManager;日历 calendarManager 的授权时序与 Event 结构放第二篇;声音 audio 的全局音量受限与 AudioRenderer 放第三篇;亮度 window 的窗口级边界放第四篇。
0. 环境与实测设备
| 项 | 版本 / 型号 |
|---|---|
| 设备 | HarmonyOS PC(aarch64,API 26,2in1 形态) |
| DevEco Studio | 本机安装版,hvigor 7.26.11 |
| 鸿蒙 SDK | API 26.0.0,compatibleSdkVersion 26.0.0,runtimeOS HarmonyOS |
| 应用 | com.example.myapplication,versionCode 1000000 |
| 通知 Kit | @kit.NotificationKit 的 notificationManager |
| WantAgent | @kit.AbilityKit 顶层导出 WantAgent 类型 + wantAgent 命名空间(API) |
| 设备 syscap | SystemCapability.Notification.Notification(device-define/2in1.json 确认在列) |
| 承载方式 | ArkWeb + javaScriptProxy,注入名 MallBridge |
| 应用上下文 | common.UIAbilityContext |
| 前端业务层 | 原生 JS 无框架,www/js/app.js 104044 字节 |
| Web 预览实现 | www/js/platform/web.js 41158 字节 |
| 页面规模 | www/index.html 82924 字节,104 个 onclick 入口 |
| 能力方法数 | SystemCapability.call() 分发 56 个 case,其中 interact.notify.* 12 个、interact.* 合计 23 个 |
| 构建产物 | entry-default-signed.hap,748020 字节 |
| 构建结果 | BUILD SUCCESSFUL in 11 s 783 ms(仅 WARN,无 ERROR) |
| 前端自测 | 7 个 JS node --check 全过、104 个 onclick 全导出、无重复 id |
有一点得先说清楚:这张表里没有「模拟器」这一行。通知是绑死在系统通知服务上的能力,浏览器预览里物理上不存在 notificationManager,所以我在 web.js 里给 interact.* 一律回 1004 needsDevice,不造一个假的状态栏出来。降级验证靠的是把回包结构和 code 全打在页面上的调试区,而不是找个能弹通知的替代环境——这一篇后面会反复回到这个边界。
1. 问题是怎么找上我的:我把通知当成了一个函数
我一开始对「系统通知」这四个字的理解特别省事:一个 publish(标题, 正文),调一次弹一条,标题换换就是「下单成功」「已发货」「已送达」。项目最早那版 notifyPublish() 也确实就是这么写的,三个字段一个对象:
// SystemCapability.ets - notifyPublish()(最早一版,节选)
const req: notificationManager.NotificationRequest = {
content: { normal: { title: title, text: text } },
id: this.noticeId,
notificationSlotType: notificationManager.SlotType.SERVICE_INFORMATION
};
await notificationManager.publish(req);
ArkTS 编译一次过。content 是必填我给了,id 给了,slot 给了,看着挑不出毛病。结果装到真机上,点「发自定义通知」,状态栏纹丝不动,回包是这么一句:
调用失败(1003):通知发布失败:{"code":401,"message":"Parameter error."}
我当时的排查顺序特别典型,也特别浪费时间:先怀疑 id 是不是不能从 0 开始,改成固定值;再怀疑 SERVICE_INFORMATION 这个 SlotType 是不是在 PC 上不支持,换成别的枚举一个个试;最后甚至怀疑是不是签名 profile 少了通知权限。全没用。真正的原因不在我改的这三个字段上,而在我以为「给了就行」的那个 content 里——翻到 notification/notificationContent.d.ts 才看到,NotificationContent 要的是 notificationContentType 和对应内容体成对出现,光给 normal 等于告诉系统「有内容」却没告诉它「这是什么布局的内容」。401 是系统在做参数校验,不是权限、不是 id、不是 slot。
把这一层想明白之后,题目就变了。所以这个题目的边界很清楚:通知不是一个 publish() 调用,它是「构造一个合法的 NotificationRequest → 走某个 NotificationSlot 渠道 → 挂一段 WantAgent 点击意图 → 用 id/groupName 决定它在通知栏里怎么聚合 → 用 badgeNumber 决定桌面角标 → 最后 getActiveNotifications() 读回来」这一整套系统对象协作,少任何一环,表现就是「点了没反应」或者「弹出来了但不对」。
拆开之后要干的事就三件:
- 让一条通知真的发出去(
content结构 + 通知开关的正确处理); - 让一组订单通知在系统里表现得像个体系(渠道分级、批量、分组、点回应用、角标);
- 把「浏览器预览」和「真机系统服务」彻底分开,别用假成功把后面所有排查带偏。
下面是干完之后的完整记录,包括我踩的每一个坑。第 6 节会把开头这个 401 收回来,讲清楚它到底该怎么一眼定位。
2. 效果展示
按老规矩,先给效果再讲原理。「真机交互」页的通知区块现在是三行按钮加四个输入框,对应 12 个 capInteractNotify* 函数:

这一片按钮不是随便铺的,每一行对应 notificationManager 的一类系统对象,UI 上每个状态位都能映射回一次真实 API 调用:

- 第一行是单条通知生命周期:
申请通知授权打的是requestEnableNotification(context)加isNotificationEnabled()回读;发自定义通知是publish(NotificationRequest);读系统活跃通知数是getActiveNotifications();读通知渠道是getSlots();清空通知栏是cancelAll()。状态行「真机 notificationManager · 未查询」在第一次调用后会被capInteractState()改成具体结果。 - 第二行是渠道、批量、分组:
三模板分渠道发一次落三条到SOCIAL_COMMUNICATION/SERVICE_INFORMATION/CONTENT_INFORMATION三个 slot;批量推 N 条用递增 id 连发;分组发 3 条共享groupName;整组撤销走cancelGroup(groupName);撤单条(id)走cancel(id)。 - 第三行是点击意图与角标:
点击拉起应用(WantAgent)挂START_ABILITY;设置应用角标调setBadgeNumber()。

四个输入框(标题、正文、条数/分组名/通知 id/角标数)直接喂给 Platform.syscap.call(method, paramsJson),回包原样打在下面那个 cap-out-interact-notify 的 <pre> 里。这里每一行都不是装饰:data.api 字段写的是这一条回包对应的真实 API 串,比如 notificationManager.getSlots(): Promise<Array<NotificationSlot>>,是为了真机上对着 hilog 排查时不用猜「这个数到底哪来的」。



第二张图是另一个页签「系统能力」页的那套 notify.*。它长得几乎一样,也写着「推送下单成功」「申请通知授权」,但下面多了一行醒目的说明:浏览器预览只把消息写进页面内的通知中心(localStorage 模拟),不会弹系统状态栏通知。这张图要专门放出来,是因为用户报「系统推送没用」的时候,十有八九点的是这一套——它回包里 simulated: true / needsDevice: true,写得清清楚楚,但按钮名字太像了。这两套入口的区分我在第 6 节坑 6 里单独算一笔账。


主动交代边界:这些截图里的 code、data 都是真机 notificationManager 服务的回包;在浏览器里点同样位置,会得到 1004:
{"ok":false,"code":1004,"message":"「interact.notify.publish」是真机系统能力,浏览器预览无对应服务,请装 entry-default-signed.hap 到鸿蒙 PC 验证(Web 端不模拟、不伪造成功)","data":{"needsDevice":true,"method":"interact.notify.publish"}}


3. 原理:一条通知在系统里到底要过几道门
鸿蒙的通知不是应用往屏幕上画一条横幅,而是应用向 notificationManager 这个系统服务提交一个 NotificationRequest,由系统按渠道策略决定要不要弹、怎么弹、聚不聚合、点开去哪。把这次用到的能力按「对象 → 方向 → 系统回调结果 → 应用要回答什么」摊开:
| 系统对象 / API | 方向 | 系统给回什么 | 应用要回答什么 |
|---|---|---|---|
isNotificationEnabled() | 查 | boolean,本应用通知总开关 | 开关关了就别硬发,先拉起授权 |
requestEnableNotification(context) | 弹 | Promise<void>,只负责拉起开关 | 用户可能拒绝,必须回读不能假设成功 |
publish(NotificationRequest) | 提交 | Promise<void>,失败抛 BusinessError | content 合不合法、id 是不是新的、slot 有没有被禁 |
NotificationSlot / getSlots() | 查 | NotificationSlot[],渠道及 level | 这条通知走哪个提醒级别 |
getActiveNotifications() | 查 | 系统通知栏里的活跃 NotificationRequest[] | 现在是几条、是不是我发的 |
cancel(id) / cancelGroup(groupName) / cancelAll() | 撤 | Promise<void> | 撤一条、撤一组、还是全清 |
wantAgent.getWantAgent() | 构造 | 一个 WantAgent 对象挂到 wantAgent 字段 | 点通知时系统该拉起谁 |
setBadgeNumber(n) | 设 | Promise<void> | 桌面图标角标显示几 |
publish() 只是「提交」,不是「显示」;真正决定显示与否的是渠道策略和通知开关,这两样都不在应用进程里。 这句话是这一篇最要紧的模型判断。我最早那个 401,就是把「提交一个请求」理解成了「直接画一条通知」,以为参数给齐就行,完全没意识到后面还有一道系统侧的校验。
三个细节决定了后面所有的降级逻辑:
第一,content 里的 notificationContentType 和 normal 是配套的。notification/notificationContent.d.ts:457 那一段把 NotificationContent 定义成一个带类型标签的联合结构,normal 只是 NOTIFICATION_CONTENT_BASIC_TEXT 这一种类型的内容体。系统先读 notificationContentType 再决定怎么解析 normal,标签没给,401。
第二,id 是通知的身份,不是订单号。publish() 遇到相同 id 走的是「更新」语义,批量推送如果 id 不递增,N 条会叠成 1 条。groupName 又是另一个维度的身份——相同 groupName 的通知在通知中心折叠成一组,撤销用 cancelGroup(groupName) 而不是逐条 cancel(id)。
第三,通知能力本身不需要在 module.json5 声明任何权限。它要过的是「应用通知开关」这道用户可改的设置,不是 requestPermissions 那套 ACL。这一点后面第 4 篇讲亮度、第二篇讲日历时会形成很清楚的对照:日历要 user_grant 权限弹窗,通知不用,但它有 isNotificationEnabled() 这个开关,两者是不同的门。
4. 工程怎么搭
先给这次通知能力相关的目录树,标清楚每个文件在这一条链路里干什么:
tauri-hello/
├── entry/src/main/
│ ├── module.json5 # 4 项权限,通知不占其中任何一项
│ ├── ets/
│ │ ├── bridge/
│ │ │ ├── MallBridge.ets # H5 → ArkTS 唯一桥,sysCall(method, params)
│ │ │ └── SystemCapability.ets # 12 个 notify* 方法 + call() 分发 + ok/err 回包
│ │ └── pages/
│ │ └── Index.ets # ArkWeb javaScriptProxy,methodList: ['sysCall']
│ └── resources/rawfile/www/
│ ├── index.html # 真机交互页通知区块(12 按钮 + 4 输入)
│ ├── js/
│ │ ├── app.js # 12 个 capInteractNotify* + CAP_INTERACT_MATRIX
│ │ └── platform/
│ │ ├── adapter.js # 运行时选边:有 MallBridge 走鸿蒙,否则走 Web
│ │ ├── harmony.js # syscap.call → MallBridge.sysCall
│ │ └── web.js # interact.* 统一回 1004 needsDevice
│ └── css/mall.css
└── entry/build/default/outputs/default/
└── entry-default-signed.hap # 748020 字节,23 个 interact.* 全进包
这次整理最关键的变化,是把「一条通知能弹」变成「一套通知体系能复用」。我给通知能力钉了三条边界:
- 能力全在
SystemCapability里,页面不碰系统 API。app.js只发interact.notify.xxx加一段 JSON 参数,永远不知道notificationManager是什么,这样 Web 端能整块替换成 1004 而不动业务代码。 - 分发只认一个
sysCall白名单。12 个通知方法不用在Index.ets的methodList里逐个注入,call()里一个switch全接住,加一个新能力不用改 ArkWeb 配置。 - 回包统一
{ ok, code, data, message }。data.api带真实 API 串,前端原样展示,真机排查时回包本身就是证据链。
最小接入就三步,探能力 → 调 → 看回包:
// www/js/app.js - capInteractNotifyPublish()(节选)
function capInteractNotifyPublish() {
return capCall('interact.notify.publish', {
title: capVal('cap-nt-title'),
text: capVal('cap-nt-text')
}, 'cap-out-interact-notify');
}
// capCall → Platform.syscap.call(method, paramsJson)
// harmony.js → MallBridge.sysCall(method, params)
// ArkTS → SystemCapability.call() case 'interact.notify.publish'
通道协议是 MallBridge 上唯一一个 sysCall(method: string, params: string): Promise<string>,params 是 JSON 字符串,method 走 interact.notify.* 命名空间。一次「读系统活跃通知数」的回包长这样:
{"ok":true,"code":0,"data":{"activeCount":3,"api":"notificationManager.getActiveNotifications(): Promise<Array<NotificationRequest>>"},"message":"系统通知栏当前有 3 条活跃通知"}
这里有一个很容易被忽略的窗口期:requestEnableNotification() 是「拉起开关」不是「保证授权」。用户点了拒绝之后系统不再重复弹窗,如果代码里在 await 之后直接写 enabled: true,页面就会显示「已授权」但通知照样发不出去。所以我在 notifyEnable() 里做的是拉起之后再 isNotificationEnabled() 回读一次,把用户可能拒绝这件事当成正常分支处理,而不是异常。这个反直觉点在第 5 节 5.2 会展开。
5. 把代码讲透
5.1 一个合法的 NotificationRequest:content 必须带类型标签
接收侧最容易写错的是 content 的结构。修复后 notifyPublish() 的核心是这样:
// SystemCapability.ets - notifyPublish()(1024–1046 行,节选)
const req: notificationManager.NotificationRequest = {
id: this.noticeId,
notificationSlotType: notificationManager.SlotType.SERVICE_INFORMATION,
content: {
notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: { title: title, text: text, additionalText: '订单状态' }
}
};
await notificationManager.publish(req);
三个细节值得单独说:
第一,notificationContentType 用的是 notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,不是随便一个数字。normal 这个内容体只有配上这个标签系统才认,这是 notificationContent.d.ts 里写死的配对关系。
第二,additionalText 是 NotificationBasicContent 的可选字段,适合塞「订单状态」这种副信息,不影响主标题正文,也不额外占一个 slot。
第三,id 用的是 this.noticeId 这个自增成员(413 行定义、1030 行 += 1),保证每次 publish() 都是新身份。
一个反直觉陷阱:ArkTS 编译期完全不拦你漏 notificationContentType。NotificationRequest.content 是必填,但 content 里所有字段都是可选的,所以「只给 normal」能编过、能打包、能装,就是不发——这也是我一开始被 401 卡住却往 id/slot 上瞎怀疑的原因。降级说明:ContentType 从 API 早期就在,NORMAL 之外的长文本、多行、图片类型各有各的内容体,但这一篇只用 BASIC_TEXT 一种,PC 的 2in1 形态下最稳。
5.2 通知开关:拉起之后必须回读,不能假设用户同意
notifyEnable() 是整套能力里最容易被写成假成功的地方:
// SystemCapability.ets - notifyEnable()(994–1018 行,节选)
let enabled: boolean = await notificationManager.isNotificationEnabled();
if (!enabled) {
try {
// 无参重载 since 12 已废弃,真机用带 UIAbilityContext 的重载
await notificationManager.requestEnableNotification(this.context);
} catch (e) {
return this.err(SystemCapability.CODE_PERMISSION_DENIED,
'通知授权弹窗调用失败或用户已拒绝过(系统不再重复弹窗,需到「设置 > 通知」手动开启):' +
JSON.stringify(e));
}
enabled = await notificationManager.isNotificationEnabled(); // 关键:再读一次
}
if (!enabled) {
return this.err(SystemCapability.CODE_PERMISSION_DENIED, '通知开关仍未开启……');
}
const d: SimpleData = { enabled: true, hint: 'isNotificationEnabled() → requestEnableNotification(context) → 再次回读' };
return this.ok(d, '通知已开启');
三个细节值得单独说:
第一,requestEnableNotification() 的无参重载在 @ohos.notificationManager.d.ts 里标了 @deprecated since 12,真机上要传 this.context(UIAbilityContext)。用废弃重载本机编译会给 WARN,某些 API 组合下直接不弹。
第二,弹窗只负责「拉起」,不负责「成功」。用户点拒绝后系统不再重复弹窗,这就是为什么 catch 分支的信息要写「需到设置里手动开启」,而不是「重试一下」。
第三,enabled 用 let 不用 const,就是为了在 await 之后被第二次 isNotificationEnabled() 覆盖。
反直觉陷阱:一次「申请通知授权」的成功,不等于这个应用以后都能发通知——用户随时能在「设置 > 通知」里关掉。所以 publish() 那一侧我特意删掉了 5 处 isNotificationEnabled() 的前置硬拦截,改成直接发、失败由 notifyFail() 翻译原生码(见 5.5 和坑 2)。用一次授权结果去管后续所有发布,是把一个动态开关当成了静态状态。降级说明:不同设备「通知总开关」的默认策略可能不同,isNotificationEnabled() 才是唯一可信的当前值。
5.3 渠道分级:一条订单三类提醒为什么不能挤在一个 slot
notifyTemplate() 一次发三条,分别落到三个 SlotType:
// SystemCapability.ets - notifyTemplate()(1331–1376 行,节选)
const slots: notificationManager.SlotType[] = [
notificationManager.SlotType.SOCIAL_COMMUNICATION, // 下单成功
notificationManager.SlotType.SERVICE_INFORMATION, // 已发货
notificationManager.SlotType.CONTENT_INFORMATION // 已送达
];
for (let i = 0; i < slots.length; i++) {
this.noticeId += 1;
const req: notificationManager.NotificationRequest = {
id: this.noticeId,
notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: { title: titles[i], text: texts[i], additionalText: this.slotName(slots[i]) },
notificationSlotType: slots[i]
};
await notificationManager.publish(req);
}
三个细节值得单独说:
第一,SlotType 决定提醒级别(是否响铃、震动、能不能横幅),三类业务消息挤在一个 slot 里,用户没法在系统设置里单独关掉「已送达」而保留「已发货」。分级不是洁癖,是让通知权限的设置粒度对齐业务粒度。
第二,notifySlots() 用 getSlots() 读回系统里真实存在的渠道(1305–1329 行),把 level、vibration 这些字段摊在回包里,slotName()(1292 行)把数值翻成可读名。这条是排查「渠道被禁用」的入口。
第三,id 在循环里递增,和 5.1 一样,保证三条是三条不是一条。
反直觉陷阱:SERVICE_INFORMATION 这类 slot 即便代码里写了,也可能被用户在系统设置里关掉,此时 publish() 不报错但也不弹——这正是坑 3 里 1600005 的来源。降级说明:getSlots() 返回的 NotificationSlot 在不同设备上数量可能不同,前端展示时按真实返回渲染,不假设一定有哪几个。
5.4 批量、分组、撤销:id 和 groupName 是两个维度
notifyBatch()、notifyGroup()、notifyCancelGroup()、notifyCancel() 四个方法处理的是「一堆通知怎么在系统里存续」:
// SystemCapability.ets - notifyGroup()(1415–1442 行,节选)
const groupName: string = this.str(p, 'groupName', 'mall_order_group');
const ids: number[] = [];
for (let i = 0; i < titles.length; i++) {
this.noticeId += 1;
const req: notificationManager.NotificationRequest = {
id: this.noticeId,
notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: { title: titles[i], text: '订单 ' + orderId + ' · ' + groupName },
notificationSlotType: notificationManager.SlotType.SERVICE_INFORMATION,
groupName: groupName
};
ids.push(this.noticeId);
await notificationManager.publish(req);
}
// 整组撤销:cancelGroup(groupName),不必记住每一条 id
await notificationManager.cancelGroup(groupName); // 在 notifyCancelGroup() 里
三个细节值得单独说:
第一,id 是「更新 vs 新增」的判据。批量推送里如果忘了 this.noticeId += 1,N 次 publish() 全用同一个 id,通知栏里只会有一条被反复覆盖。这是我给 notifyBatch() 的回包里专门放 ids: number[] 的原因——让递增这件事可观测。
第二,groupName 是「折叠成组」的判据,和 id 完全正交。三条不同 id、相同 groupName 的通知在通知中心是一个组,整组撤销用 cancelGroup(groupName),撤单条用 cancel(id),全清用 cancelAll()。
第三,id 是通知 id,不是订单号。我在文档里反复强调这一点,是因为「撤单条(id)」那个输入框如果被人填了 HD20261122001 这种业务单号,cancel() 什么也撤不掉还不报错。
反直觉陷阱:分组撤销不需要遍历自己发的 id 列表。我一开始在 calendarEvents 那种内存数组思路上绕了一下,后来才反应过来 groupName 本身就是系统侧的聚合键,cancelGroup() 直接吃这个字符串。降级说明:不是所有桌面形态的通知中心都展示分组折叠,但 cancelGroup() 的语义在 API 层是一致的,回包里 count 按实际发布条数给。
5.5 点击意图与角标:WantAgent 和 badgeNumber 收尾
notifyClickable() 让点通知能拉起应用,notifyBadge() 改桌面角标:
// SystemCapability.ets - notifyClickable()(1482–1525 行,节选)
const flags: wantAgent.WantAgentFlags[] = [wantAgent.WantAgentFlags.CONSTANT_FLAG];
const info: wantAgent.WantAgentInfo = {
wants: [{ bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility' }],
actionType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
actionFlags: flags
};
const agent: WantAgent = await wantAgent.getWantAgent(info);
const req: notificationManager.NotificationRequest = {
id: this.noticeId,
notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: { title: title, text: text, additionalText: 'START_ABILITY' },
wantAgent: agent,
tapDismissed: true,
notificationSlotType: notificationManager.SlotType.SERVICE_INFORMATION
};
await notificationManager.publish(req);
三个细节值得单独说:
第一,WantAgentInfo 用新版的 actionType / actionFlags,旧的 operationType / wantAgentFlags 自 API 11 起废弃。这一条是我真机编译踩过 10505001 之后翻 @ohos.app.ability.wantAgent.d.ts 改对的(见坑 7)。
第二,WantAgent 这个类型是从 @kit.AbilityKit 顶层导出的,不在 wantAgent 命名空间下。所以 import 写的是 import { ..., WantAgent, wantAgent } from '@kit.AbilityKit'——一个类型、一个命名空间,两样都要。
第三,tapDismissed: true 让通知点完自动消失;setBadgeNumber(n) 改的是桌面图标角标(1529–1542 行),和通知栏里的条目数是两回事。
同时,notifyFail()(974–992 行)把原生错误码翻成能定位的中文,这一层是整套能力「不闷声失败」的收口:
// SystemCapability.ets - notifyFail()(974–992 行,节选)
private notifyFail(action: string, raw: string): string {
let why: string = '原生错误:' + raw;
if (raw.indexOf('1600004') >= 0) why = '1600004 应用通知开关被关闭:到「设置 > 通知」打开本应用的通知……';
else if (raw.indexOf('1600020') >= 0) why = '1600020 系统权限设置不允许本应用发通知……';
else if (raw.indexOf('1600005') >= 0) why = '1600005 通知渠道(slot)被禁用:先点「读通知渠道」确认……';
else if (raw.indexOf('1600014') >= 0) why = '1600014 无发送通知权限……';
else if (raw.indexOf('1600009') >= 0) why = '1600009 发送频率达到系统上限……';
else if (raw.indexOf('1600003') >= 0) why = '1600003 连不上通知服务:确认运行在真机鸿蒙 PC……';
else if (raw.indexOf('401') >= 0) why = '401 参数校验失败:检查 content 是否带 notificationContentType + normal';
return action + '失败:' + why;
}
反直觉陷阱:把 JSON.stringify(e) 直接贴回前端几乎没有用,用户看到的是 {"code":1600004} 一串数字,不知道要去哪里改设置。翻译成「到设置里打开通知」才是一次能解决问题的回包。降级说明:getWantAgent() 依赖 @kit.AbilityKit,在不支持 START_ABILITY 的形态上会抛错,catch 走 notifyFail(),绝不假装「已挂点击意图」。
6. 我踩过的坑(每一条都有真实报错)
这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。
坑 1:content 只给 normal,真机回 401。 就是开头那一幕:
调用失败(1003):通知发布失败:{"code":401,"message":"Parameter error."}
一开始以为 id 从 0 开始不行、SERVICE_INFORMATION 在 PC 上不支持、签名缺通知权限,把三个字段挨个换了一轮全没用。后来翻 notification/notificationContent.d.ts:457-466 才反应过来:NotificationContent 是带类型标签的联合结构,notificationContentType 和 normal 必须成对。修法是五处 publish() 的 content 全部补 NOTIFICATION_CONTENT_BASIC_TEXT。编译能过不等于参数合法,content 里的字段全是可选,系统侧的校验才是第一道门。 这条正好把第 1 节埋的那个 401 收回来。
坑 2:5 处 isNotificationEnabled() 前置硬拦截,把所有发布按钮变成哑巴。 第一版 notifyPublish() 们开头都有这么一段:
// SystemCapability.ets - 旧代码(已删)
const enabled: boolean = await notificationManager.isNotificationEnabled();
if (!enabled) {
return this.err(SystemCapability.CODE_PERMISSION_DENIED, '通知权限未开启,请先点「申请通知授权」');
}
真机上开关没开时,点任何发布按钮都只回这一句 1007,系统真正的错误码(1600005 渠道禁用、401 参数错)全被吞了,用户完全不知道该改哪里。一怒之下把 5 处硬拦截全删,改成直接 publish()、失败交给 notifyFail() 翻译。notifyEnable() 里那个 let enabled 的回读逻辑保留,两者不冲突。前置检查不该替代真实错误,尤其是当那个检查本身还不如原生错误码精确的时候。
坑 3:以为 publish() 成功就一定弹得出来(1600005)。 有次三模板分渠道发,回包全是 ok:true,通知栏却只有两条:
{"ok":true,"code":0,"data":{"items":[{"type":"order","slot":"SOCIAL_COMMUNICATION","id":1},...]},"message":"三模板已发布"}
一开始以为是漏发,后来点「读通知渠道(getSlots)」才看到其中一个 slot 的 level 被设成了关闭。系统对 slot 被禁用的 publish() 不一定抛异常,它是「收下了但不提醒」。ok:true 只说明请求被系统接受,不说明用户看见了横幅;渠道状态得用 getSlots() 单独读。 这也是 notifySlots() 这个能力存在的理由。
坑 4:批量推送 N 条,通知栏只出现 1 条。 notifyBatch() 第一版循环里忘了递增 id:
// SystemCapability.ets - notifyBatch()(错误写法)
for (let i = 0; i < count; i++) {
const req = { id: 1, /* ... */ }; // 固定 id
await notificationManager.publish(req);
}
回包 published: 5,通知栏 1 条。一开始以为是系统合并了同类通知,后来才反应过来 publish() 对相同 id 是「更新」。改成循环里 this.noticeId += 1、回包带 ids: number[] 之后立刻变 5 条。id 是身份不是序号,相同 id 的系统语义是覆盖,不是追加。
坑 5:groupName 撤销想自己遍历 id。 做「整组撤销」时,我下意识照着 calendarEvents 那种内存数组的思路,打算存下每条 id 再循环 cancel(id)。写到一半翻 @ohos.notificationManager.d.ts 才发现有 cancelGroup(groupName):
function cancelGroup(groupName: string): Promise<void>;
一个字符串搞定,不用记任何 id。一开始以为分组只是前端展示层的概念,后来才反应过来 groupName 是系统侧的聚合键。能被系统直接聚合的东西,别在应用里重造一份索引。
坑 6:两套「系统通知」入口互相误伤,用户报「推送没用」。 「系统能力」页那套 notify.* 在 web.js 里是 localStorage 应用内通知中心模拟,第一版却回:
{"ok":true,"code":0,"data":{"notification":{"id":"N...","type":"ship"},"enabled":true,"simulated":true},"message":"通知已推送"}
enabled: true + 「通知已推送」,可状态栏什么都没有。用户点的是这一套,来看的是「真机交互」页那 12 个 interact.notify.*,当然觉得整个推送功能是坏的。修法:notify.enable / notify.publish 一律改 enabled: false + simulated: true + needsDevice: true,message 明写「浏览器预览不会弹系统状态栏」,index.html 两个区块各加一段醒目的区分说明。演示态必须在回包里自报家门,假成功比不做更伤排查。
坑 7:wantAgent.WantAgent 类型引用报 10505001。 加「点击拉起应用」时,第一版这样写:
1 ERROR: 10505001 ArkTS Compiler Error
Error Message: Namespace '...wantAgent' has no exported member 'WantAgent'.
COMPILE RESULT:FAIL {ERROR:2 WARN:40}
BUILD FAILED in 6 s 746 ms
WantAgent 类型我下意识当成了 wantAgent 命名空间下的成员。翻 @kit.AbilityKit.d.ts 才确认它是顶层导出,改成 import { ..., WantAgent, wantAgent } 且 const agent: WantAgent。kit 的顶层导出和命名空间导出是两回事,ArkTS 严格模式下猜一次就编译不过。
坑 8:能跑不等于能装——受限权限顺带连累通知那轮调试。 这轮通知增强之前的排查里,module.json5 一度声明了 PRINT / WINDOW_TOPMOST / WRITE_MEDIA 三项普通应用拿不到的权限,调试 profile 是 apl: normal + allowed-acls: [],装包阶段直接被拒。通知能力本身不需要任何权限声明,却被整包的安装失败挡在门外,一点都验证不了。把权限收敛到 4 项(INTERNET / GET_NETWORK_INFO / READ_CALENDAR / WRITE_CALENDAR)之后 HAP 才装得上。系统能力再对,包进不去真机也等于零。 这一条的权限模型全貌放本系列第二篇讲,这里只记它对通知验证的连累。
7. 现在怎么用:从 Demo 到真机
构建命令(本机验证过的那条,DEVECO_SDK_HOME 要指到带 HarmonyOS-26.0.0/sdk-pkg.json 的目录):
cd /storage/Users/currentUser/Documents/DevEcoStudioProjects/tauri-hello
export DEVECO_SDK_HOME=/storage/Users/currentUser/WorkBuddy/2026-11-21-17-24-54/harmony-sdk-home
node /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/hvigor/bin/hvigorw.js \
--mode module -p product=default assembleHap --no-daemon
# BUILD SUCCESSFUL in 11 s 783 ms
# 产物:entry/build/default/outputs/default/entry-default-signed.hap(748020 字节)
签名用的是 DevEco 自动生成的调试材料(build-profile.json5 里 signingConfigs[0],type: HarmonyOS),签名材料不进仓库。自测交代:7 个 JS node --check 全过、104 个 onclick 全导出、HTML 无重复 id;HAP 里 ets/modules.abc 校验过 23 个 interact.* 全在包、NOTIFICATION_CONTENT_BASIC_TEXT / getWantAgent / getSlots / cancelGroup / setBadgeNumber 符号都命中。真机验证顺序是:先点「申请通知授权」确认回包 enabled:true,再点「发自定义通知」,然后依次验渠道、分组、点击拉起、角标;DevEco 里过滤 hilog DOMAIN 0x5504(SystemCapability)能看原生侧打印。
免得读者踩到同一堵墙,硬限制清单:
- 通知不需要
module.json5权限声明,但受「应用通知开关」控制,开关关了publish()会失败,得去「设置 > 通知」手动开。 - 浏览器预览发不出系统通知,
interact.*一律回1004 needsDevice;要看到状态栏必须装 HAP 到鸿蒙 PC。 content必须notificationContentType+normal成对,只给normal真机回 401。- id 相同是更新、不是新增;
groupName相同是折叠成组,两者不是一个维度,cancel(id)里的 id 不是订单号。 getActiveNotifications()读的是系统通知栏,不是应用内存里的数组;setActiveNotifications之类的模拟数据一概不认。- 点通知拉起应用靠
WantAgent(actionType: START_ABILITY),WantAgent类型从@kit.AbilityKit顶层导入。
最开始我以为它是应用往屏幕上画的一条横幅,一个函数调用的事;现在我知道它是往系统服务提交的一个带类型标签的请求,渠道决定它怎么提醒、id/groupName 决定它在通知栏里怎么存续、WantAgent 决定点开去哪、badgeNumber 决定桌面长什么样,而 ok:true 仅仅意味着「系统收下了」。把这几类对象分开之后,那些「点了没反应」「弹了但不对」的现象才有地方安放。
更多推荐




所有评论(0)