Electron-OH 鸿蒙实战:应用内弹窗之外,把提醒推成系统横幅
Electron-OH 鸿蒙实战:应用内弹窗之外,把提醒推成系统横幅
待办提醒这个东西,应用开着、窗口在前台的时候,一个应用内弹窗就够了;可用户一收起窗口、一切到别的应用,弹窗就跟着页面一起消失,提醒等于没提醒。这篇文章用一个跑在鸿蒙 2in1 上的 Electron-OH 笔记应用,把「renderer 发一条 HTML5 Notification,移植层把它接成系统横幅」这条链路拆开讲:桥是怎么预置的、权限的时机怎么选、降级怎么做成三态——连同我摸边界和踩坑的全过程,一次讲透。
本文素材来自我自己的工程 ohos_hap(本机壳笔记应用,应用版本 1.0.12,versionCode 1000012),全部业务代码在 src/renderer.js,没有自写一行 ArkTS。文中的代码都是工程里的实际代码,系统通知最终显示成什么样子取决于移植层的 NotificationAdapter 实现;渲染层逻辑(到点判定、双通道触发、降级分支)已用 DOM 桩测试验证过。
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| 工程 | ohos_hap(Electron-OH 本机壳笔记应用) |
| 应用版本 | 1.0.12(versionCode 1000012,AppScope/app.json5) |
| compatibleSdkVersion | 6.0.0(20)(release 阶段,build-profile.json5) |
| Electron-OH 移植层 | libelectron,底座 Electron 40(构建 20261028.2-release) |
| 渲染层 | src/renderer.js(纯 JS,约 1900 行) |
| 自写 ArkTS | 无 |
| 实测设备 | HarmonyOS 平板 / 2in1(API 20) |
| DevEco Studio | 版本号待补,本文结论以真机实测为准 |
表里最关键的一行是「自写 ArkTS:无」。这次整条提醒链路都是 renderer 里那几百行 JS 在跑,ArkTS 侧只有移植层自带的绑定。这也正是这篇文章想说的重点:在 Electron-OH 上,应用能碰到哪些系统能力,不由应用决定,由移植层决定。
1. 收起窗口之后,弹窗就死了——这个问题是怎么找上我的
笔记应用里我加了一套待办:每条待办可以设截止时间、勾上「到点提醒」。实现很朴素,renderer.js 里起一个 30 秒的定时器,轮询一遍待办列表,发现有条目的截止时间已经过去、又还没标记过「已提醒」,就弹一个应用内的提醒卡。
第一版做出来的时候我挺满意:到点弹卡、可以推迟十分钟、可以一键全部确认,逻辑闭环。直到有一天我把它最小化到 Dock(2in1 上是收起窗口),过了截止时间再切回来——提醒卡是弹了,但那段时间里什么都没发生。应用在后台,页面不可见,弹窗弹给谁看?
那几天的排查日志是这样的:
[todo] tick: 到期待提醒 2 条
这是我用 diagLog 打到主进程再落日志的真实一行。轮询在跑、条目也算对了,但「提醒」这件事只发生在窗口里面。窗口收起来,用户那边就是零反馈。
我一开始也以为这个问题不难:鸿蒙有 reminderAgentManager,可以做系统级后台提醒,应用被杀都能弹;大不了再退一步用 notificationManager 直接发通知。以我在原生鸿蒙上的经验,这两个都是 @ohos 命名空间下的 API,import 进来就能调。
结果把 Electron-OH 的结构翻了一遍才发现,事情完全不是这样。主进程是 Node 环境,renderer 是 Chromium 环境,两边都拿不到 @ohos——它们和 ArkTS 世界之间隔着一层移植层。移植层确实提供了一堆 ArkTS 绑定,但那些绑定是给 C++ 侧通过 AKI 框架预置调用的,应用层无法新增绑定。想在 Electron-OH 里加一条 calendarManager 或者 reminderAgentManager 的桥?可以,前提是去改移植层的 C++。
但同一个调研里我也看到了好消息:renderer 的 HTML5 Notification,在 Electron-OH 上不是空壳。移植层把它接到了 NotificationAdapter,最终落成系统通知——横幅会弹,通知中心里也能看到。
所以这个题目的边界很清楚:在 Electron-OH 上,应用 JS 能碰到的系统能力只有移植层预置的那几条桥;做后台可见的提醒,通道就选 HTML5 Notification 这一条,应用内弹窗降级兜底。
拆下来是三件事:
- 摸清 Electron-OH 的 JS↔ArkTS 绑定边界,确认到底哪条桥能用、哪条不能用;
- renderer 用 HTML5
Notification发通知,真机验证它是不是真的落到系统通知中心; - 把「通知能不能发」做成可观测的三态,可用、不可用、没测过,三种状态界面都要说人话。
下面是干完之后的完整记录,包括我踩的每一个坑。
2. 效果展示
按老规矩,先给效果再讲原理。

这是前台到点的样子:应用内提醒卡在页面中间列出到期的待办标题,同时系统弹了横幅。这里每一行都不是装饰:卡片标题「待办提醒(2 条到点)」来自 tickReminders() 里对多条待办的拼接;横幅的正文是各条待办标题用「;」连接后截到 120 字的结果。

应用内弹窗在前台看一眼就没了,这张图才是这次改造的真正收益:下拉通知中心,这条提醒还在。标签是 ohos-notes-remind,同一 tag 的新通知会覆盖旧的,不会在通知中心堆一屏。
提醒中心面板顶部有一行状态文案。sysNotifyOk === false 时显示「系统通知:当前环境不可用,提醒只走应用内弹窗」,否则显示「系统通知:可用(到点同时弹系统横幅与应用内提醒)」。这行字是 renderRemindCenter() 根据实测结果渲染的,不是写死的。也就是说,如果哪天移植层换了个版本、通知桥出了变化,界面会自己告诉我,不用我翻日志猜。
两张截图都是在 2in1 真机上拍的,compatibleSdkVersion 6.0.0(20)。到点提醒的完整行为是:30 秒内轮询命中 → 应用内弹卡 + 系统横幅同时出 → 用户确认或推迟后 reminded 标记落盘,下一轮不再重复。
3. 原理:一条 HTML5 Notification 是怎么变成系统横幅的
先上链路表:
| 环节 | 谁在干 | 干什么 |
|---|---|---|
new Notification(title, opts) | renderer.js | Web 标准 API 调用,只是个入口 |
| Chromium 通知分发 | Electron 40 内核 | 把通知请求交给平台实现层 |
NotificationAdapter.SendNotification | jsbindings 里的 ArkTS 绑定 | 把 JS 调用转成 ArkTS adapter 调用 |
NotificationAdapter | 移植层 adapter(ArkTS) | 调系统通知 API 落成系统通知 |
| 横幅 + 通知中心 | HarmonyOS 系统 | 弹横幅、通知中心常驻记录 |
这个表里最值得盯的是第三行。Electron-OH 的移植层在 web_engine/src/main/ets/jsbindings/ 下放了一整套 ArkTS 绑定文件,我 ls 过这个目录,四十多个 *AdapterBind.ets:BatteryAdapterBind.ets、GeolocationAdapterBind.ets、FilePickerAdapterBind.ets……当然也有这次的主角:
// web_engine/src/main/ets/jsbindings/NotificationAdapterBind.ets - bind()(节选)
export class NotificationAdapterBind {
static bind() {
JsBindingUtils.bindFunction('NotificationAdapter.SendNotification', sendNotification);
JsBindingUtils.bindFunction("NotificationAdapter.CloseNotification", closeNotification);
JsBindingUtils.bindFunction("NotificationAdapter.GetAllNotification", getAllNotification);
}
}
这些绑定不是给应用层用的。它们是移植层启动时预置给 C++ 侧的——C++ 代码通过 AKI 框架按名字调这些 ArkTS 函数,Chromium 内核里「发一条通知」的平台实现,最终就是走到 NotificationAdapter.SendNotification 这里。
这带来两个结论,都是我调研之后才真正吃透的:
第一,主进程 JS 拿不到 @ohos API。 主进程是 Node 环境,没有 ArkTS 运行时;想从主进程直接调系统通知、系统日历、系统提醒,此路不通。
第二,应用层无法新增绑定。 绑定清单是 C++ 侧启动时注册的,我往 jsbindings 里放一个自己写的 CalendarAdapterBind.ets,没人会去调它。想加新桥,唯一路径是改移植层 C++,把新绑定加进预置流程——那是改底座的活,不是应用开发的活。
所以 HTML5 Notification 的真实身份就清楚了:它在这里不是 Web API,是移植层预置好的一条系统能力桥。renderer 里的 new Notification(...) 看着是标准浏览器写法,实际走的是「Chromium 通知分发 → 预置绑定 → NotificationAdapter → 系统通知」这条移植层专线。桥上能不能跑车、跑车会不会翻,都不归 W3C 规范管,归移植层管。
还有一层:@ohos.notificationManager 发的系统通知,和应用内弹窗是两套完全独立的呈现通道。前者归系统通知服务管,应用收起、切后台、甚至窗口销毁前发的通知,都留在通知中心;后者跟着页面走,页面不可见它就不可见。提醒要覆盖「用户不在窗口里」的时间段,通道必须建在系统上,而系统通道在应用 JS 这一层,只有预置桥这一种接法。
这两个事实——桥只有预置的、通知走 NotificationAdapter——决定了后面所有的降级逻辑。第 5 节逐段拆代码。
4. 工程怎么搭
先看目录。这是整个工程的骨架,和提醒链路相关的文件我都标了职责:
ohos_hap/
├── AppScope/
│ └── app.json5 # versionCode 1000012 / versionName 1.0.12
├── build-profile.json5 # compatibleSdkVersion "6.0.0(20)"
├── electron/ # Electron-OH 运行底座
├── web_engine/
│ └── src/main/
│ ├── ets/jsbindings/ # 移植层 JS↔ArkTS 绑定(C++ 经 AKI 预置,应用层不可新增)
│ │ ├── NotificationAdapterBind.ets
│ │ ├── FilePickerAdapterBind.ets
│ │ └── …(四十多个 *AdapterBind.ets)
│ └── resources/resfile/resources/app/ # 应用本体,随 resfile 分发
│ └── src/
│ ├── index.html # 单页结构:编辑区 + 待办面板 + 提醒中心
│ ├── renderer.js # 全部业务:笔记、待办、提醒、诊断
│ └── style.css
├── hvigorfile.ts
└── oh-package.json5
这次整理最关键的变化,是把「能提醒」变成「提醒可依赖」。三条边界:
- 系统能力只走预置桥。 renderer 里所有碰系统的代码,只用移植层确认提供的接口(这次的 HTML5 Notification、之前的文件导出),不猜、不绕。
- 降级必须可观测。 通知发不出去不能是静默失败,
sysNotifyOk三态 + 提醒中心状态行 +diagLog日志,三层都能看到原因。 - 应用内弹窗永远是兜底。 系统横幅是增强,不是依赖。横幅发不出去时,前台提醒卡必须在。
接入的「协议」其实非常薄,就是 Notification 构造参数本身:title 是通知标题,body 是正文,tag 控制通知中心的覆盖行为,silent 控制是否有声。最小用法三步:
// src/renderer.js - fireSystemNotification() 的最小形态(示意)
// 1. 探测:环境里有没有 Notification 构造器
if (typeof Notification === 'undefined') { /* 降级 */ }
// 2. 权限:default 状态下静默请求,不阻塞本轮
if (Notification.permission === 'default') {
Notification.requestPermission().then(() => {});
}
// 3. 发送:同一业务固定同一个 tag
const n = new Notification('待办提醒', { body: '下午三点评审', tag: 'ohos-notes-remind' });
整条链路里有一个很容易被忽略的窗口期:权限请求是个 Promise,requestPermission() 发出去之后、授权结果回来之前,下一个 30 秒 tick 可能已经到了。这轮通知是在权限还是 default 的状态下发的——我的处理是照样发,让实测结果反写 sysNotifyOk,而不是先 await 权限再发。为什么这么做,5.2 细说。
另一个窗口期在后台:HarmonyOS 对后台页面的定时器有节流,30 秒的 setInterval 在收起窗口后可能被拖长甚至暂停。错过的检查不能永远丢掉,所以窗口重新获得焦点时补查一次。5.4 讲这个双保险。
5. 把代码讲透
整条链路的代码都在 src/renderer.js 的 1644–1690 行附近,下面按五个具体问题拆开。
5.1 三态探测:sysNotifyOk 为什么不是一个布尔
接收侧最容易写错的是状态建模。通知可不可用,看起来是个布尔问题,其实不是:
// src/renderer.js - 模块顶层(1649 行)
let sysNotifyOk = null; // null=没测过, true/false=实测结果
function fireSystemNotification(title, body) {
try {
if (typeof Notification === 'undefined') {
sysNotifyOk = false;
diagLog('[notify] 环境无 Notification,降级为应用内提醒');
return false;
}
// …发送逻辑…
sysNotifyOk = true;
diagLog('[notify] 系统通知已发送: ' + title.slice(0, 30));
return true;
} catch (e) {
sysNotifyOk = false;
diagLog('[notify] 系统通知失败,降级应用内提醒: ' + ((e && e.message) || e));
return false;
}
}
三个细节值得单独说:
第一,初值是 null 不是 false。 页面刚加载、一次通知都没发过的时候,我根本不知道这个环境支不支持通知——这是「没测过」,和「测过了、确认不可用」是两种状态。如果用 false 打头,提醒中心会把一个还没验证过的环境直接宣判死刑。
第二,每次发送都是一次实测。 sysNotifyOk 不做预检,只在真正发通知的瞬间被结果反写:发成功置 true,探测失败或抛异常置 false。移植层是黑盒,与其启动时猜,不如让第一次真实发送当试金石。
第三,三态要落到界面上。 提醒中心的状态行是这么渲染的:
// src/renderer.js - renderRemindCenter()(1826 行)
if (rcNotifyEl) {
rcNotifyEl.textContent = sysNotifyOk === false
? '系统通知:当前环境不可用,提醒只走应用内弹窗'
: '系统通知:可用(到点同时弹系统横幅与应用内提醒)';
}
null(没测过)和 true 都显示「可用」那条——文案上略激进,但逻辑上说得通:没测过的环境下轮询还会继续实测,一旦翻车这行字立刻变。只有 false 是确凿的不可用,才换降级文案。
反直觉的点在这里:不能用「上一次发送成功」推断「下次一定成功」。移植层版本一换、系统通知开关一关,上次还好的桥这次就断了。三态加持续实测,等于把「探测」变成「监控」。
5.2 权限的时机:requestPermission 静默请求,下一轮生效
HTML5 通知有权限模型,Notification.permission 有三个值:granted、denied、default。我的处理在 fireSystemNotification 中间这几行:
// src/renderer.js - fireSystemNotification()(1658 行)
if (Notification.permission === 'default') {
// 尽量别在弹提醒的瞬间弹权限框,首次先静默请求,下一轮生效
Notification.requestPermission().then((p) => { sysNotifyOk = p === 'granted'; }).catch(() => {});
}
const n = new Notification(title, { body, tag: 'ohos-notes-remind', silent: false });
注意这里没有 await。权限是 default 的时候,我先发一个不阻塞的授权请求,然后本轮照发不误。这是刻意的:
- 如果
await权限结果再发,第一次到点的提醒就会被权限弹窗拦下来,用户面对一个莫名其妙的系统授权框,提醒本身反而迟到了; - 如果不请求直接发,权限永远是
default,有的实现会拒绝发送,那这一轮通知就白发了; - 「静默请求 + 本轮照发」是折中:授权请求挂出去,结果回来反写
sysNotifyOk;本轮通知能不能出去,交给实测。到点的那个瞬间,优先保证提醒送达,权限框永远不插队。
下一轮 tick 进来时,权限大概率已经变成 granted,分支直接跳过,走正常发送。也就是说权限的生效是「下一轮生效」,延迟最多 30 秒,换来的是用户第一次见到提醒时,看到的是提醒,不是授权框。
catch(() => {}) 也不是偷懒:requestPermission 在某些实现上可能直接抛拒绝,这个 Promise 的失败不影响本轮主流程,属于噪音,吞掉。
5.3 tag:把通知风暴压成一条
发送这一行的参数不是随手填的:
// src/renderer.js - fireSystemNotification()(1662 行)
const n = new Notification(title, { body, tag: 'ohos-notes-remind', silent: false });
为什么会想到 tag,得从 tickReminders 的轮询说起:
// src/renderer.js - tickReminders()(1676 行)
function tickReminders() {
const now = Date.now();
const due = todos.filter((t) => !t.done && t.remind && t.due && t.due <= now && !t.reminded);
diagLog('[todo] tick: 到期待提醒 ' + due.length + ' 条');
console.log('[todo] tick: 到期待提醒 ' + due.length + ' 条');
if (due.length && remindModalEl.hidden) {
showRemindModal(due);
// 应用内弹窗只在前台可见;系统通知负责"切到后台/收起时也看得见"
fireSystemNotification(
due.length > 1 ? '待办提醒(' + due.length + ' 条到点)' : '待办提醒',
due.map((t) => t.title).join(';').slice(0, 120)
);
}
}
轮询是 30 秒一次。想象一下七条待办先后到期:第一次 tick 命中 3 条,第二次 tick 又命中 2 条,第三次再 2 条——如果每次通知用不同的标识,通知中心会堆出一屏「待办提醒」,用户下拉一看全是重复内容,提醒就变成了骚扰。
tag: 'ohos-notes-remind' 解决的就是这个:同一 tag 的新通知覆盖旧通知。不管轮询命中多少轮、每轮几条,通知中心里永远只有最新的一条。多条待办合并进同一条通知的标题和正文(「待办提醒(3 条到点)」),信息不丢,条数不涨。
body 截到 120 字是同一条防线上另一环:待办标题是用户随便起的,可能有几十字的长句,七条拼起来正文能上四百字,横幅上根本读不了。120 字看个开头,详情留给应用内提醒卡和提醒中心。
5.4 tickReminders:30 秒轮询加 focus 补查的双保险
轮询的注册只有两行,但两行都不能少:
// src/renderer.js - 模块顶层(1730 行)
remindTimer = setInterval(tickReminders, 30000);
// 窗口重新获得焦点时立刻查一次:后台时定时器被节流,错过的检查在回来瞬间补上
window.addEventListener('focus', tickReminders);
三个细节值得单独说:
第一,30 秒是延迟和打扰的折中。 提醒这种业务,秒级轮询纯浪费——待办的截止时间本来就是分钟级的;再长(比如 5 分钟)又会把「12:00 到点」的提醒拖到 12:04。30 秒意味着最坏情况提醒晚到半分钟,轮询本身的开销可以忽略。
第二,focus 补查是给节流擦屁股的。 后台时定时器被节流,这是浏览器的标准行为,移植层也照章办事。收起窗口一小时,setInterval 可能只跑了几轮甚至没跑;用户切回来的那一瞬间 focus 事件触发,立刻补一次检查,错过的提醒最多迟到、不会消失。这条注释是真实踩过之后写上去的——补查不加的话,收起窗口期间到期的待办,回来之后如果 reminded 还是 false,会在下一轮 tick 才弹,用户体感就是「我都打开应用了提醒才冒出来」。
第三,reminded 标记防止重复轰炸。 tick 的过滤条件是 !t.reminded,弹过一次提醒卡,这条待办就被标记、落盘,之后的轮询不再命中。确认按钮批量置位、推迟按钮重置 due 并清标记,两边共用同一套过滤条件,不会出现「确认完了还在弹」的鬼打墙。
这里有一个很容易被忽略的窗口期:提醒卡弹出但用户还没点确认的时候,remindModalEl.hidden 是 false,后续 tick 命中了新到期的条目也不会重复弹卡——if (due.length && remindModalEl.hidden) 里的这个条件就是闸门。代价是弹卡期间新到期的条目暂时不发系统通知,等这张卡被处理后由下一轮 tick 收编。提醒这种场景,宁可不及时,不能刷屏。
5.5 onclick:不确定的支持就用 try/catch 兜住
通知对象的事件绑定只有两行,但写法有讲究:
// src/renderer.js - fireSystemNotification()(1663 行)
n.onclick = () => {
try { window.focus(); n.close(); } catch (_) { /* 移植层不支持 onclick 时不影响 */ }
};
HTML5 通知的标准行为里,点击通知应该聚焦应用窗口。但这是 Web 标准,不是移植层的合同——移植层对 Notification.onclick 支持到什么程度,我没有在文档里找到确切说法,真机行为也可能随移植层版本变化。
我的判断是:onclick 是锦上添花,不是必选路径。通知已经送达了,点击能不能聚焦窗口,只影响体验的最后一厘米,不能因为它影响送达本身。所以 try/catch 包住整个回调——移植层实现了 onclick,就多赚一次 window.focus() 和 n.close();没实现,catch 吞掉,通知照样是有效的。
这不是洁癖:在不确定的桥上,每一处锦上添花的代码都必须有能力自证「我挂了也不影响主线」。整个 fireSystemNotification 就三层 try/catch 套着:最外层兜发送异常(降级置 sysNotifyOk = false),中间层兜权限请求失败,最里层兜 onclick。哪一层炸都不影响「提醒已经发出去了」这个事实。
6. 我踩过的坑(每一条都有真实报错或真实权衡)
这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实调研、真实日志和真实设计取舍。有几条没有报错堆栈——因为坑本身是「没有报错」,那种更难查。
坑一:主进程 JS 调不了系统能力,绑定是 C++ 预置的。 做方案的时候我的第一版规划是「主进程调 reminderAgentManager,做应用被杀也能弹的系统级提醒」。听起来天衣无缝:原生鸿蒙里这就是标准做法。结果调研 Electron-OH 的绑定层,发现 JS 世界和 ArkTS 世界之间根本没有应用可用的直连通道——绑定全在 web_engine/src/main/ets/jsbindings/*.ets,由 C++ 侧通过 AKI 框架预置调用,应用层无法新增绑定。想加 calendarManager、reminderAgentManager 的桥,唯一路径是改移植层 C++。排查过程:先在主进程尝试直接使用系统能力,发现根本没有 @ohos 模块可加载;然后翻移植层源码,ls 了 jsbindings 目录才看清全貌。最终方案退到 renderer 的 HTML5 Notification——它能用,但只覆盖应用进程活着的时间。移植层给了什么桥就用什么桥,先摸清边界再定方案。
坑二:权限框的时机,到点弹框等于提醒失败。 第一版我图省事,在发通知前 await Notification.requestPermission(),想着「先把权限要到手再发」。结果第一次到点,用户看到的不是提醒,是一个突然弹出的系统授权框——提醒本身被压在权限框后面,到点提醒变成了到点惊吓。后来改成静默请求:本轮到点时不阻塞,先发授权请求、本轮照发,授权结果下一轮生效。提醒送达的优先级高于权限流程的完整性,权限框永远不该插在提醒和用户之间。
坑三:onclick 的支持是未知数,不能赌。 标准里点击通知应该聚焦窗口,我在第一版直接写 n.onclick = () => window.focus(),没有兜底。写完冷静下来一想:移植层对 onclick 支持到什么程度没有文档背书,万一是「赋值不报错但回调里调 DOM 方法就炸」的实现,一条 try/catch 能省掉多少真机翻车。现在的写法是回调整体 try/catch,挂了只丢体验不丢送达。在不确定的移植层上,任何锦上添花的回调都要假设它可能不存在。
坑四:通知风暴,tag 不加就是刷屏。 30 秒轮询意味着同一批到期条目可能分多轮被命中,多轮通知如果各自独立,通知中心会堆一屏「待办提醒」。这个坑我没等真机翻车就拦下了——推理链条很短:轮询 30 秒一轮 × 一批待办集中在同一时段到期 = 必然多轮通知。所有通知统一 tag: 'ohos-notes-remind',后发覆盖先发;多条合并标题、正文截 120 字。轮询型业务给通知加 tag 不是优化项,是上线前置条件。
坑五:布尔建模会把「没测过」和「确认不可用」混成一团。 最初 sysNotifyOk 我想都不想就是个 false 打头。写提醒中心状态行的时候才反应过来:页面刚加载、一次通知没发过的时候,这个 false 是什么意思?「不可用」?可我根本没测过。三态建模(null/true/false)之后,「没测过」显示可用文案、持续实测反写,只有确凿的失败才显示降级文案。状态建模要多问一句:这个值在「从未发生」的时候是什么?
坑六:渲染层 console 在真机 hilog 里看不到。 这个坑不是这次才发现的,但它直接决定了这次通知链路怎么排查。renderer 里的 console.log 在真机的 hilog 里看不到——调试通知这种「发没发、发了什么」的问题,没日志就是盲飞。所以 renderer 里有一条 IPC 诊断通道,关键路径全部双写:
// src/renderer.js - diagLog()(14 行)
function diagLog(msg) {
try {
if (diagApi) diagApi.log(String(msg === null || msg === undefined ? '' : msg));
} catch (_) { /* 诊断通道断了只靠界面提示,别影响业务 */ }
}
tickReminders 里那对 diagLog + console.log 双写就是这么来的:真机看 diagLog 落的日志,开发环境看 console。这次通知链路的三条关键日志——环境无 Notification、发送成功、发送失败——全是 diagLog 通道。看不到日志不等于没执行,先把观测通道修好,再谈排查业务。
坑七:本机壳的 contextBridge 会把顶层声明变成语法炸弹。 这是个基础设施级的坑,值得单独记一笔。本机壳的 contextBridge 会把 exposeInMainWorld 注入的每个名字注成页面全局的 const 词法绑定,renderer 顶层再声明同名变量会直接 SyntaxError——而且不是炸一行,是整个脚本一行都不执行,页面直接白板。renderer.js 的开头就留着这段注释:
// src/renderer.js - 文件头(1–3 行,节选)
// 本机壳的 contextBridge 会把 exposeInMainWorld 的每个名字都注成页面全局的
// const 词法绑定,顶层再声明同名变量会直接 SyntaxError,整个脚本一行都不执行。
// 所以整个文件必须包在 IIFE 里,让顶层声明留在函数作用域。
提醒相关的全局变量(sysNotifyOk、remindTimer)全都活在 IIFE 作用域里,就是这个原因。「能跑」和「能编译」之间,隔着一个词法作用域。
7. 现在怎么用:从 Demo 到依赖
这套提醒链路没有独立打包,它是 ohos_hap 1.0.12 的一部分。如果你也在 Electron-OH 上做类似的事,接入路径是这样的:
- 确认你的移植层版本带
NotificationAdapterBind(web_engine/src/main/ets/jsbindings/下看一眼); - 把
fireSystemNotification、tickReminders两段代码搬进 renderer,改掉业务过滤条件里的字段名(t.due、t.remind、t.reminded); - 提醒中心状态行可选,但强烈建议保留——三态展示是这套方案的自我诊断能力;
- 构建走 DevEco Studio 的 HAP 构建(
hvigorw assembleHap),签名材料不进仓库,本机配置留本机。
当前真机验证结果:应用 1.0.12 在 HarmonyOS 2in1(API 20)上,到点提醒的应用内弹卡、系统横幅、通知中心常驻、状态行文案、推迟十分钟重置计时,全部按预期工作。轮询在窗口收起时被节流的现象真实存在,focus 补查兜住了。
免得读者踩到同一堵墙,硬限制清单:
- 主进程拿不到
@ohosAPI,系统能力只能走移植层预置桥,应用层无法新增绑定,加新桥要改移植层 C++; - HTML5 Notification 依赖移植层实现,环境里
typeof Notification === 'undefined'不是不可能,降级路径必须常备; - 提醒只在应用进程活着时有效,进程被杀之后 tick 就停了;想要「被杀也能弹」,那是移植层 C++ 侧的活;
- 后台定时器被节流,30 秒轮询在后台会拖长,
focus补查是必备件不是优化件; - 权限对话框的时机自己控制不了细节,但可以控制「绝不阻塞当轮发送」;静默请求、下一轮生效,是实测下来体验最好的折中。
写到这里,我对「提醒」的理解已经和最初完全不同了。最初我以为提醒就是一个弹窗,弹出来就完了;做完这条链路才明白,弹窗只是提醒在窗口可见时的那个切面,真正定义提醒的是「用户不在窗口里时他还能不能被通知到」。应用内弹窗覆盖前台,系统横幅覆盖后台,sysNotifyOk 的三态覆盖「我知不知道自己覆盖了」——三者拼起来,提醒才是可依赖的。如果这篇文章只能留一句话,我会留这句:应用内弹窗只对看得见窗口的人有效,提醒要做给不在窗口里的人。
8. 快问快答
Q1:为什么不用 reminderAgentManager 做系统级提醒?
绑定层是移植层 C++ 侧 AKI 预置的,应用层无法新增绑定。用上它需要改移植层,超出应用开发的边界。当前解是 HTML5 Notification,覆盖应用进程存活期。
Q2:应用被杀之后,到点还提醒吗?
不提醒。tick 轮询活着,提醒才活着。这是当前方案的真实边界,也是第 6 节坑一里我调研 reminderAgentManager 的原因——想要那条能力,得从移植层动手。
Q3:点击系统横幅能回到应用吗?
onclick 回调里做了 window.focus(),但整体 try/catch 兜底。移植层对 onclick 的支持程度没有文档背书,能聚焦算赚到,不能聚焦不影响送达。
Q4:权限被拒绝之后会怎样?
requestPermission 结果是 denied 时 sysNotifyOk 置 false,提醒中心状态行切到「当前环境不可用」,提醒只走应用内弹窗。用户至少能在界面上看到原因,而不是面对一个静默失效的功能。
Q5:30 秒轮询会不会漏提醒?
最坏延迟 30 秒,不会漏。后台节流会把轮询拖长,但窗口回焦时 focus 补查一次,错过的检查当场补上。提醒迟到,但不缺席。
Q6:通知中心会不会被提醒刷屏?
不会。所有提醒通知共用 tag: 'ohos-notes-remind',后发覆盖先发;多条待办合并进一条通知的标题和正文,正文截 120 字。
Q7:想在桥上加 calendarManager、reminderAgentManager 怎么办?
改移植层 C++,把新绑定加进预置流程,再随移植层版本分发。在 jsbindings 里自己放一个绑定文件是没用的——没人会去调它。
Q8:怎么知道我这份移植层支不支持通知?
别猜,发一条试试。sysNotifyOk 的三态设计就是为了这个:第一次真实发送就是探测,结果反写状态、上屏、进日志。黑盒面前,实测比文档可靠。
更多推荐


所有评论(0)