Electron-OH 鸿蒙实战:把待办提醒导出成日历能认的 .ics 文件
Electron-OH 鸿蒙实战:把待办提醒导出成日历能认的 .ics 文件
系统日历的 API 在 ArkTS 那一侧,Electron 的 JS 层根本 require 不到;绕过去的办法不是硬接一座桥,而是按 RFC 5545 生成一份 .ics 文件落进沙箱——这篇文章用一个跑在鸿蒙平板上的 Electron-OH 待办应用,把「时间戳怎么算成 UTC」「文本怎么转义才不炸结构」「行结束符为什么必须是 CRLF」「contextBridge 为什么只能传一个对象」这四件事一次讲透。
代码来自我自己的工程 ohos_hap,应用名 ohos-notes,版本 1.0.12(versionCode 1000012)。主进程 main.js,桥接层 preload.js,渲染层 src/renderer.js,没有前端框架,全是原生 DOM。仓库是私有的,所以下面所有代码都直接贴原文,不给你一个点不开的链接。
0. 环境与实测设备
| 项 | 版本 / 型号 |
|---|---|
| 应用 | ohos-notes 1.0.12(versionCode 1000012) |
| 壳工程 | ohos_hap,Electron 应用内嵌在 web_engine 模块的 resfile 里 |
| compatibleSdkVersion | 6.0.0(20) |
| 实测设备 | HarmonyOS 平板 / 2in1 形态,API 20 |
| DevEco Studio | 6.0.0 Release(build 号见 Help → About,本文不抄) |
| hvigor | 随 DevEco Studio 6.0.0 自带,未单独钉版本 |
| Electron 运行时 | 壳工程内置的 Electron-OH,版本跟着 HAP 走,应用侧不可替换 |
| 前端技术栈 | 原生 DOM + preload contextBridge,无 React / Vue |
| 验证方式 | 真机手动导入日历 + node /tmp/rc.test.js 单测时间戳函数 |
有两点先说清楚,免得你照着搭的时候对不上:
第一,Electron-OH 不是官方发行的 Electron。 它是壳工程把一个精简运行时塞进 HAP 的 resources/resfile 里,Node 侧能力被裁过一轮。所以你在桌面 Electron 上习惯的 require('electron') 拿到的对象,字段不一定齐。这也是后面"为什么不能直接调系统日历"的根因之一。
第二,compatibleSdkVersion 6.0.0(20) 意味着我只能用 API 20 的能力。 系统日历的 calendarManager 在 ArkTS 侧从 API 10 就有,但它不在 JS 的模块解析路径里——这句话听起来像废话,可我当时真的花了半天才接受它。
1. 「不就是调个日历 API 吗」——这个问题是怎么找上我的
我一开始也以为这就是个 API 调用的事。
应用里有个待办面板,每条待办可以设截止时间,到点弹提醒。用了一阵子我发现一个很实际的问题:应用关掉之后,提醒就断了。 我自己写的检查逻辑是 setInterval 每 30 秒扫一遍,应用不在前台,这个定时器就不跑了。错过的提醒重新打开时会标成"已逾期",但那个"点"已经过去了,标不标都没用。
用户(其实就是我自己)的真实需求是:把这条提醒写进系统日历,让系统在应用没开的时候也能叫我。
所以我第一版干的事很朴素:在渲染层找系统能力。window.calendarManager、window.ohos、navigator.calendar,挨个 console.log。全是 undefined。
然后我把主意打到主进程。既然 Electron-OH 的 main 进程是个 Node 环境,那我 require 一下不就行了:
// 一次失败的尝试,写在 main.js 顶部
const calendar = require('@ohos.calendarManager');
这个报错我在本机 Node 侧直接复现过(主进程用的也是 Node 的模块解析器,行为同一套):
MODULE_NOT_FOUND: Cannot find module '@ohos.calendarManager'
@ohos.* 这一整套模块,是 ArkTS 的 import 语法糖,背后是方舟运行时提供的 native binding。Node 的模块解析器不认识这个前缀,它只会去 node_modules 和内置模块表里找,找不到就抛 Cannot find module。这不是权限问题,也不是版本问题,是两个运行时的问题。
我也评估过两条更野的路:在 main 里 process.binding,或者在 preload 里找 requireNapi 之类的全局钩子。结论都一样——Electron-OH 的主进程没有向应用暴露方舟的 native binding,这条路走不通。真正的桥在壳工程里:web_engine/src/main/ets/jsbindings/ 下那一排 *AdapterBind.ets,用 JsBindingUtils.bindFunction() 把 ArkTS 函数挂给 C++ 侧,C++ 再通过 AKI 框架调用。注意这个方向:绑定是给 C++ 取用的,调用点在 C++ 里预置,应用层没法自己新增一个。 想要 calendarManager 桥,得改移植层源码。
那座桥我评估了一下工作量:写 ArkTS 的 calendarManager 封装、处理 ohos.permission.READ_CALENDAR 和 WRITE_CALENDAR 两个权限的申请流程、处理用户拒绝授权的分支、处理不同设备上日历账户不存在的情况、再加上 C++ 侧新增调用点——这不是一个下午的活,而且每一步都要重新验证签名和权限声明。
于是我停下来问了自己一个问题:用户要的到底是"写进系统日历",还是"到点被叫醒"?
答案显然是后者。"写进系统日历"只是手段之一。而"写进系统日历"这件事,业界有一个二十年历史的标准答案:.ics 文件。任何支持日历的应用——系统日历、Google Calendar、Outlook、Foxmail——都能导入它。我不需要任何权限,不需要任何桥,只需要把文件写到用户能拿到的地方。
所以这个题目的边界很清楚:在 Electron-OH 的 JS 层不接任何原生桥,用主进程生成一份符合 RFC 5545 的 .ics 文件,落到应用沙箱,再由用户手动导入系统日历。
这条路的代价是"多一步手动导入",收益是"零权限、零桥、零签名改动"。对我这种一周发三个版本的独立开发者来说,这笔账很好算。
拆开看,这件事只有三件:
- 把毫秒时间戳写成 ICS 认识的 UTC 格式;
- 把标题里的特殊字符转义掉,别把文件结构撑破;
- 按 CRLF 拼行、写进沙箱、把路径回传给界面。
看起来简单。但我第一版跑出来的文件,日历打不开;第二版能打开,时间差 8 小时;第三版时间对了,标题里带逗号的那条又没了。下面是干完之后的完整记录,包括我踩的每一个坑。
顺便把一个日志埋在这里,第 6 节要回收它。第一版我为了让导出"支持格式参数",preload 写成了两个参数:
[ipc] -> todo:export-ics
[ipc] <- todo:export-ics ok
通道返回 ok,但主进程里 todos 是 undefined,走进第一个防御分支,返回了 { ok: false, error: '数据格式错误' }。界面上的 toast 就是这四个字。当时我盯着 preload.js 看了十分钟,todos 明明传了啊。
2. 效果展示
按老规矩,先给效果再讲原理。

这是提醒中心。上面那句 系统通知:可用(到点同时弹系统横幅与应用内提醒) 是能力探测的结果,不是写死的文案;下面按"已逾期 / 今天 / 明天 / 本周 / 更晚"分组,每组右上角的数字是该组条数。最底下那个按钮 导出到日历(.ics 文件) 就是本文的主角。
这里每一行都不是装饰:分组是 groupReminders() 按 due 和时间边界算出来的;分组标题里的数字是 items.length;按钮下面那句提示 导出后可在支持日历导入的应用中打开该文件 是给用户的行为预期,因为它真的不会自动进日历。

点一下,两秒内出结果。toast 内容是 已导出 4 条到 /data/storage/el2/base/haps/entry/files/exports/reminders-2026-11-21.ics。

这行提示里的三个信息都是有用的:
4 条来自主进程返回的count,是过滤之后的数量,不是你待办列表的总数;- 路径是绝对路径,落在应用沙箱的
files/exports下; - 文件名里的日期是导出当天的 UTC 日期(这个细节后面第 6 节会单独说,它在晚上导出时会差一天)。
同时 diagLog 会把同一条信息打到 hilog:[todo] .ics 导出成功: <path>。为什么要打?因为真机上渲染层的 console.log 你是看不见的,这一点在 preload.js 的注释里写得很直白——业务 console 在真机上不可见,排查必须走 diag:log 这条通道。

这是文件本体。BEGIN:VCALENDAR 开头,VERSION:2.0,PRODID 是我自己的标识,中间每条待办一个 VEVENT,末尾 END:VCALENDAR。每条 VEVENT 里都能看到 DTSTART 那一串 20261121T133000Z——注意结尾的 Z,它在说"这是 UTC 时间"。

导入系统日历之后的样子。标题正确,时间正确,点开能看到事件时长是 15 分钟,并且带一个"事件开始时"的提醒。
这张截图是整个方案唯一的说服力来源。 前面所有关于 RFC 5545 的讨论,最后都要落到"日历认不认"这一个事实上。它认了,方案就成立。

需要交代的边界:这三张截图是我在 API 20 的平板形态上拍的。换到 2in1 上,界面布局会变(提醒中心变成右侧抽屉),但导出的文件一个字节都不变——因为整个导出链路不碰 UI,只碰 fs。这也是我为什么敢说这条路"跨设备形态稳定"。

还有一个降级要说:如果你的应用版本低于 1.0.12,这个按钮点下去会提示 当前包不支持日历导出,请升级到 1.0.12+,而不是抛一个 TypeError。原因在第 6 节第 5 条。

3. 原理:日历到底认什么
先把结论摆出来,再解释。
日历不认"事件",它认"文本格式"。 你给它一个 .ics 文件,它做的事是:按行读、按冒号切、按 BEGIN / END 配对,然后把你写的字段翻译成它自己的数据库记录。整个过程里它不执行你的代码,不调你的 API,不回调你。它就是一个解析器。
这个模型一确立,很多困惑就散了:
- 为什么不需要权限?因为你没碰它的数据库,你只是给了它一个文件。
- 为什么导入后改标题不会同步回来?因为这是一次单向的"复制",不是订阅。
- 为什么格式错一个字符就打不开?因为解析器是严格的,它没有"猜你想干什么"的义务。
RFC 5545 定义的这套东西,核心结构就三层:
| 层级 | 标记 | 作用 | 必需 |
|---|---|---|---|
| 日历 | BEGIN:VCALENDAR … END:VCALENDAR | 一个文件一个日历,装所有事件 | 是 |
| 事件 | BEGIN:VEVENT … END:VEVENT | 一条日程,有自己的 UID 和时间 | 是 |
| 闹钟 | BEGIN:VALARM … END:VALARM | 挂在事件里的提醒,可以有多个 | 否 |
再往里,是属性行。每一行都是 名字:值 的形状,冒号是唯一的分隔符。这个"唯一"很重要——它意味着值里出现的冒号、逗号、分号、反斜杠、换行,都可能被解析器当成语法。这是第 5.3 节要处理的事。
我把应用要回答的问题整理成一张表,写代码的时候对着看:
| 系统(日历解析器)要什么 | 方向 | 应用要回答什么 | 我的实现位置 |
|---|---|---|---|
| 这个文件是什么 | 文件头 | VERSION:2.0 + PRODID | main.js - todo:export-ics 的 lines 初始化 |
| 有几条日程 | 结构 | 每条一个 VEVENT,BEGIN/END 必须成对 | 同上,list.forEach |
| 每条日程是谁 | 身份 | UID 全局唯一,重复导入靠它去重 | UID:ohos-notes-<id>@ohos-notes |
| 什么时候开始 | 时间 | DTSTART,UTC,YYYYMMDDTHHMMSSZ | icsStamp(t.due) |
| 什么时候结束 | 时间 | DTEND,必须晚于 DTSTART | icsStamp(t.due + 15 * 60 * 1000) |
| 这个文件什么时候生成的 | 时间 | DTSTAMP,UTC | icsStamp(Date.now()) |
| 叫什么 | 文本 | SUMMARY,特殊字符转义 | esc(t.title) |
| 要不要提醒 | 闹钟 | 内嵌 VALARM + TRIGGER | TRIGGER:-PT0M |
这张表里,只有"什么时候开始"和"叫什么"是会翻车的两行,其余的照抄就行。
然后是最重要的那条模型判断,我把它单独拎出来:
应用能写的是文件,不是日历。 你写下去的每一个字节,都要经过"另一个程序愿不愿意读"这一关。所以你不是在"调 API",你是在"生成一份给别人的输入"。这个视角一换,你自然会去查规范,而不是去试参数。
顺着这个判断,还有两个推论:
推论一:格式的正确性优先级高于功能的丰富性。 一份只有 SUMMARY 和 DTSTART 的极简 VEVENT,只要格式对,就能导入;一份带 RRULE、VALARM、ATTENDEE、X- 扩展但格式错一个字符的文件,一条都进不去。我第一版就是贪多,先写了 RRULE,结果整个文件打不开,排查了半天才发现问题根本不在 RRULE。
推论二:错误必须能被你自己看见。 因为解析器不给你报错——它只是"打不开",或者"打开了但少了几条"。所以你的导出函数必须自己校验、自己记日志、自己把路径回传给界面。这也是为什么 todo:export-ics 的返回值是 { ok, path, count } 而不是一个裸的 true。
这两个推论决定了后面所有的工程细节。
4. 工程怎么搭
先看目录。这不是一个独立仓库,是壳工程里的一个模块,所以路径有点长,但结构很干净。
ohos_hap/
├── build-profile.json5 # compatibleSdkVersion 6.0.0(20) 在这里
├── entry/ # ArkTS 入口(本文不改)
└── web_engine/
└── src/main/resources/resfile/
└── resources/app/ # ← Electron 应用的根,等价于桌面端的 app 目录
├── package.json # name: ohos-notes, main: main.js
├── main.js # 主进程:窗口、IPC、文件落盘、待办读写
├── preload.js # 桥接层:contextBridge 暴露 window.*Api
├── auth-store.js # 账户与会话(内存态)
├── store.js # 通用 JSON 存储
├── importer.js # 附件导入
├── window-manager.js # 窗口尺寸/位置/多屏
└── src/
├── index.html # 单页界面,提醒中心在 205-222 行
├── renderer.js # 渲染层逻辑,导出按钮在 1852-1870 行
└── style.css
这个目录结构里,跟本文有关的只有四处:main.js 的 todo:export-ics 处理器、preload.js 的 exportIcs 绑定、renderer.js 的按钮点击处理、index.html 的那个 <button>。
这次整理最关键的变化,是把"能跑"变成"能复用"。 导出这件事,从头到尾只有三个边界:
- 主进程只认数据,不认 UI。
todo:export-ics收到的是一个数组,返回的是一个结果对象。它不知道按钮长什么样,也不知道 toast 怎么写。所以你完全可以在命令行里手动触发它(后面第 7 节我会说怎么测)。 - preload 只做搬砖,不做判断。 它把
window.todosApi.exportIcs映射到通道todo:export-ics,中间只有一层超时包装。任何业务判断写在这里,都会变成"两个地方都要改"的债。 - 渲染层只做能力探测和用户反馈。 按钮点下去,先看方法在不在,再
await,再把{ ok, path, count }翻译成人话。它不拼 ICS,一个字都不拼。
这三条边界的实际收益,是我能单独测中间那一段。/tmp/rc.test.js 里我不需要启动 Electron,直接把 icsStamp 那段逻辑抠出来跑断言。后面第 7 节会说这个测试怎么写的。
最小接入代码,从渲染层看就十几行。这是真实代码,不是伪代码:
// src/renderer.js - btnRcIcsEl 点击处理(节选 1852-1862)
btnRcIcsEl.addEventListener('click', async () => {
const list = todos.filter((t) => !t.done && t.due);
if (!list.length) {
toast('没有可导出的待办(需要设了截止时间且未完成)');
return;
}
if (!todosApi.exportIcs) {
toast('当前包不支持日历导出,请升级到 1.0.12+');
return;
}
const res = await todosApi.exportIcs(list).catch((e) => ({ ok: false, error: (e && e.message) || String(e) }));
三步:先筛数据 → 再探能力 → 最后调用并把异常收敛成结果对象。
第三步那个 .catch 很关键。await 一个 reject 的 Promise,如果不接住,整个 async 函数会把异常抛到事件循环里,用户看到的是"点了没反应"。把它 .catch 成 { ok: false, error },后面那段 if (res && res.ok) 就能统一处理成功和失败两条路。
通道协议很简单,一次请求一次响应,没有流:
// 请求(preload 包了一层 5 秒超时)
{ "ch": "todo:export-ics", "args": [ [ { "id": "k2j9", "title": "交周报", "due": 1795277400000, "done": false } ] ] }
// 成功响应
{ "ok": true, "path": "/data/storage/el2/base/haps/entry/files/exports/reminders-2026-11-21.ics", "count": 1 }
// 失败响应(四种,都是正常返回,不是异常)
{ "ok": false, "error": "未登录" }
{ "ok": false, "error": "数据格式错误" }
{ "ok": false, "error": "没有可导出的提醒" }
{ "ok": false, "error": "<fs 抛出的原始 message>" }
注意这里的四种失败全部是 resolve,不是 reject。这是刻意的设计:业务失败和通道失败要分开。业务失败(没登录、没数据)应该显示成一句人话;通道失败(5 秒没响应)才是异常,才该走 .catch。
preload.js 里那层超时包装长这样:
// preload.js - call()(节选 5-17 行)
function call(ch, ...args) {
console.log('[ipc] ->', ch);
return new Promise((resolve, reject) => {
const timer = setTimeout(() => {
console.error('[ipc] TIMEOUT', ch);
reject(new Error('IPC_TIMEOUT: ' + ch + ' 5 秒无响应'));
}, 5000);
ipcRenderer.invoke(ch, ...args).then(
(v) => { clearTimeout(timer); console.log('[ipc] <-', ch, 'ok'); resolve(v); },
(e) => { clearTimeout(timer); console.error('[ipc] <-', ch, 'fail:', e && e.message || e); reject(e); }
);
});
}
这里有一个很容易被忽略的窗口期:ipcRenderer.invoke 在某些壳工程实现里,Promise 会永久 pending。 不是慢,是永远不回。界面表现就是"按钮点下去,转圈,转到天荒地老"。5 秒超时把这个不确定性变成了一句确定的错误。导出这种"一次 IO、返一个路径"的操作,5 秒非常宽裕,宁可误杀也不能挂死。
最后说一个我认为最容易被忽略的点:渲染层筛了一遍,主进程又筛了一遍。
// 渲染层:只给未完成且有截止时间的
const list = todos.filter((t) => !t.done && t.due);
// 主进程:同样的条件,外加 title 必须是字符串
const list = todos.filter((t) => t && t.due && !t.done && typeof t.title === 'string');
有人会问这是不是冗余。不是。渲染层的过滤是为了给用户一句准确的提示(“没有可导出的待办”),主进程的过滤是为了让这个 IPC 通道在任何调用方下都安全。 通道是可以被别的渲染进程、被 devtools 直接调到的,你不能假设调用方一定先筛过。多写一行 typeof t.title === 'string',省掉的是"某个旧数据里 title 是 null 导致 esc 抛错"这种半夜才会来的问题。
5. 把代码讲透
主进程那段处理器一共 38 行,我按"它要回答的问题"切成五块讲。原始代码在 main.js 409-447 行,下面按小节重新贴,注释保留原文。
5.1 先判身份,再判格式:为什么第一行必须是登录态
// main.js - ipcMain.handle('todo:export-ics')(409-414 行,原文)
// 提醒导出为标准 .ics 日历文件:VEVENT 按 UTC 写 DTSTART,支持日历导入的应用都能收
ipcMain.handle('todo:export-ics', (_event, todos) => {
if (!currentUser) return { ok: false, error: '未登录' };
if (!Array.isArray(todos)) return { ok: false, error: '数据格式错误' };
const list = todos.filter((t) => t && t.due && !t.done && typeof t.title === 'string');
if (!list.length) return { ok: false, error: '没有可导出的提醒' };
接收侧最容易写错的,是校验顺序。
我见过(也写过)的写法是先把数据洗干净,再判断业务状态。这段代码反过来:先 currentUser,再 Array.isArray,最后才是过滤。这个顺序不是随手排的。
三个细节值得单独说:
第一,登录态在最前面,是因为它是"会话级"的判断,跟数据长什么样无关。 如果先过滤,一个未登录的请求带着空数组进来,会走到"没有可导出的提醒"——用户会以为是自己没设提醒,而不是没登录。错误的错误信息,比没有错误信息更贵。
第二,Array.isArray 而不是 todos && todos.length。 后者对字符串 "abc" 也成立(有 length),然后 todos.filter 会抛 TypeError: todos.filter is not a function。这个异常会穿过 ipcMain.handle 变成一个 rejected Promise,渲染层那边 .catch 成 { ok: false, error: 'todos.filter is not a function' },用户看到一串英文。用一个 Array.isArray 换来一句"数据格式错误",值。
第三,过滤器里的 t && 不能省。 待办列表是从 JSON 文件读出来的,理论上不该有 null,但磁盘上的数据永远比你以为的脏——手工改过、旧版本写过、写入中途断电过。t && t.due 这一段的成本是一个字符,收益是不用去查"为什么导出偶发崩溃"。
这里有一个反直觉的地方:你可能觉得"没有可导出的提醒"应该返回 ok: true, count: 0,因为"空"不是错误。 我一开始也这么想。但实测下来,返回 ok: true 会让界面弹一个 已导出 0 条到 xxx.ics,然后用户去找那个文件,发现里面只有 BEGIN:VCALENDAR / END:VCALENDAR,导入日历后什么都没有。空文件不是"成功导出零条",它是一个会被日历拒绝或静默忽略的坏输入。 所以这里返回 ok: false 更诚实:这次导出没有产生有价值的文件,那就别产生文件。
顺便,渲染层在更早的地方也拦了一次同样的条件,给的是更具体的提示 没有可导出的待办(需要设了截止时间且未完成)。两层文案不一样是有意的:渲染层知道"用户点了按钮"这个上下文,主进程不知道。
版本差异上没什么好说的,ipcMain.handle 在 Electron-OH 里是可用的(invoke 那一侧也是),这条通道从我开始写这个应用就没换过。
5.2 时间:为什么 DTSTART 必须手搓 UTC
// main.js - todo:export-ics 内的局部函数(415-421 行,原文)
const pad = (n) => (n < 10 ? '0' : '') + n;
const icsStamp = (ts) => {
const d = new Date(ts);
// ICS 日期要 UTC:用 getUTC* 系列手搓,别用 toISOString 再正则(依赖实现细节)
return d.getUTCFullYear() + pad(d.getUTCMonth() + 1) + pad(d.getUTCDate())
+ 'T' + pad(d.getUTCHours()) + pad(d.getUTCMinutes()) + '00Z';
};
这是全文我最想讲清楚的一段,因为它同时包含"规范要求"和"工程选择"两件事。
规范这一半: RFC 5545 里,带 Z 后缀的时间是 UTC,不带 Z 的是"浮动时间"(floating time,意思是"按查看者本地时区解释")。系统日历遇到浮动时间,会按设备当前时区去摆这条事件。用户带着平板飞到东京,这条提醒就提前一小时。而我们想要的是"这个绝对时刻叫我",那就必须写 UTC。
工程这一半: 为什么不用 toISOString()?它返回的是 2026-11-21T13:30:00.000Z,格式其实是对的,只需要 .replace(/[-:]/g, '').replace(/\.\d{3}/, '') 就能变成 20261121T133000Z。三行搞定,为什么要手搓?
因为那三行正则依赖 toISOString 的输出格式,而 toISOString 的输出格式是实现了 ECMA-262 的运行时来保证的。桌面 V8 没问题,Electron-OH 的运行时我不确定——它不是官方 Electron,裁剪过。今天是 .000Z,明天如果某个构建把它改成不带毫秒,我的正则就会漏,产出 20261121T13:30:00Z,冒号还在里面。文件结构立刻坏掉,而错误信息是"日历打不开",你根本不会想到是这里。
getUTC* 系列不一样。getUTCFullYear() 返回数字,getUTCMonth() 返回 0-11,getUTCDate() 返回 1-31,这几个方法的语义在 ECMA-262 里是硬规定,任何实现都得这么返回。用数字拼字符串,我不依赖任何"字符串格式化"的行为。 这就是注释里那句"别用 toISOString 再正则(依赖实现细节)"的意思。
三个细节值得单独说:
第一,getUTCMonth() 要 +1,getUTCDate() 不用。 月份是 0-based(1 月是 0),日期是 1-based。这两个不一致是 JS 的历史包袱,抄错一个就是"所有事件都落在上个月"或者"1 号变成 0 号"。我写这段的时候特意把 +1 写在同一行,就是为了让 review 的人一眼看到。
第二,秒被硬编码成 '00Z'。 看这行:+ 'T' + pad(d.getUTCHours()) + pad(d.getUTCMinutes()) + '00Z'。它丢掉了 0-59 秒。一条 21:30:47 的待办,导出后是 21:30:00。对提醒来说这完全无所谓——没人会在意提醒晚了 47 秒;但你要知道这是刻意的简化,不是 bug。如果哪天要做"精确到秒的日程",这里得改成 pad(d.getUTCSeconds())。
第三,icsStamp 是"纯函数",这是它能被单测的前提。 它只依赖入参 ts,不读全局状态,不碰文件系统。所以我可以把它抠出来,扔进 node 里跑断言。这是整个导出链路里唯一一段值得单测、也唯一一段能单测的代码。
反直觉的陷阱在这:pad 用的是 n < 10 ? '0' : '',它对负数和高位都不做处理,但这没问题——因为时间分量不可能是负数,也不会超过 99。 而如果你图省事写成 String(n).padStart(2, '0'),在很老的运行时上 padStart 可能不存在(ES2017)。Electron-OH 的 Node 版本我不打算赌,一个三元表达式最稳。
还有 t.due + 15 * 60 * 1000 这一行——前提是 t.due 必须是数字。 我的存储里它就是 Date.now() 出来的毫秒数,所以没问题。但如果哪天有人把 due 改成存 ISO 字符串('2026-11-21T21:30:00+08:00'),'...' + 900000 会变成字符串拼接,new Date('2026-11-21T21:30:00+08:00750000') 是 Invalid Date,getUTCFullYear() 返回 NaN,产出 DTSTART:NaNNaNNaN...。而 filter 只检查 t.due 真值,拦不住。这就是为什么校验要在主进程做,而且要做得比"看起来够"更狠一点。
5.3 文本:esc 的三步顺序,一步都不能换
// main.js - todo:export-ics 内的局部函数(422 行,原文)
const esc = (s) => String(s).replace(/([,;\\])/g, '\\$1').replace(/\r?\n/g, '\\n').slice(0, 300);
一行代码,三个动作,顺序有讲究。
先把 ICS 的转义规则列清楚。RFC 5545 规定,TEXT 类型的值里:
| 原字符 | 要写成 | 为什么 |
|---|---|---|
\ | \\ | 反斜杠是转义符本身,必须先处理 |
; | \; | 分号是参数分隔符 |
, | \, | 逗号是值列表分隔符 |
| 换行 | \n(字面两个字符) | 换行会直接撑断这一行 |
现在看为什么顺序是这样的:
第一,/([,;\\])/g 一次替换三个字符,但 \\ 必须在这个字符类里。 如果分成两步写——先转义反斜杠,再转义逗号分号——第二步会把第一步产出的 \\ 当成"一个反斜杠 + 一个逗号"来处理吗?不会,但先转逗号分号、再转反斜杠,就会把 \, 里的反斜杠再转一遍,变成 \\,,日历看到的是"一个字面反斜杠,然后逗号结束这个值",标题后半截丢了。放在一个字符类里一次过,天然规避了这个顺序问题。这是我在另一个项目里真踩过的坑,所以这里直接一步到位。
第二,换行必须在特殊字符之后转。 如果先转换行(把 \n 变成 \\n 两个字符),后面的 /([,;\\])/g 会看到那个新生成的反斜杠,把它再转成 \\\\n,结果是字面输出 \\n 而不是换行。顺序反了,多一个反斜杠。
第三,slice(0, 300) 放最后,这是"先转义再截断"。 反过来(先截断再转义)有一个问题:截断点可能落在一个多字节字符中间,产出半个字符;更实际的是,截断之后你可能得到一段"未闭合"的文本,再转义就不知道边界在哪。先转义,至少保证每个转义序列是完整的。
但这里有一个我必须诚实交代的边角: 先转义后截断,slice(0, 300) 是按转义后的字符数算的。也就是说,一个满是逗号的标题,实际保留的原文字符会少于 300。而且如果第 300 个字符正好是个 \,截断后末尾会留一个孤立的反斜杠,严格的解析器可能报错。这两个边角我没有处理,因为真实标题里 300 字符的情况一次都没出现过。 这不是"设计得优雅",这是"知道它有问题、但收益不值得现在改"。写代码的人应该能说出自己代码的欠账在哪。
还有一个没做的事:折行。
RFC 5545 规定,内容行不应超过 75 个八位组(octet),超了要折行——在 CRLF 之后加一个空格,然后继续。300 个汉字是 900 字节,远超 75。我的实现完全没有折行。
这是一个明确的欠账。实测上,API 20 的系统日历和几个常见客户端都能吃下长行(它们的解析器比较宽容),但**“我测过能用"不等于"符合规范”**。如果你要兼容最严格的解析器,得补一段按 75 字节切、切点还要避开多字节字符中间的逻辑。我评估过,那段代码大概 20 行,比整个导出函数还长。在你真的遇到"某个客户端导不进去"之前,我建议先别写。
String(s) 那一层也别省。t.title 已经用 typeof === 'string' 过滤过了,但 esc 是个独立函数,未来可能在别处被调用(比如 DESCRIPTION)。String() 兜住 null / undefined / 数字,成本一个函数调用。
5.4 骨架:VEVENT 里哪几行是必需的
// main.js - todo:export-ics 的拼装部分(423-435 行,原文)
const lines = ['BEGIN:VCALENDAR', 'VERSION:2.0', 'PRODID:-//ohos-notes//reminders//CN'];
list.forEach((t) => {
lines.push('BEGIN:VEVENT');
lines.push('UID:ohos-notes-' + (t.id || Date.now().toString(36)) + '@ohos-notes');
lines.push('DTSTAMP:' + icsStamp(Date.now()));
lines.push('DTSTART:' + icsStamp(t.due));
lines.push('DTEND:' + icsStamp(t.due + 15 * 60 * 1000)); // 默认 15 分钟时长
lines.push('SUMMARY:' + esc(t.title));
if (t.due < Date.now()) lines.push('DESCRIPTION:' + esc('(导出时已逾期)'));
lines.push('BEGIN:VALARM', 'TRIGGER:-PT0M', 'ACTION:DISPLAY', 'DESCRIPTION:' + esc(t.title), 'END:VALARM');
lines.push('END:VEVENT');
});
lines.push('END:VCALENDAR');
一行一行拆。
VERSION:2.0 是硬要求。 没有它,很多解析器直接判定"这不是 iCalendar"。PRODID 严格说也是必需的(RFC 5545 规定必须有一个 PRODID),值是"谁生成了这个文件"。我写成 -//ohos-notes//reminders//CN,-// 前缀 + // 分隔 + 语言标记,这是通行写法,但内容其实随便——解析器不读它,只是给人看。
UID 必须是全局唯一的。 日历靠它去重:你导入两次同一个文件,它会认为"这些 UID 我见过",不会产生两份。我的写法是 ohos-notes-<id>@ohos-notes,也就是"前缀 + 待办自己的 id + @ + 一个像域名的东西"。@ 后面那部分习惯上写生成者的标识,不要求真实存在。
这里有一个真实的隐患,我在读自己代码的时候发现的:
'title: ' + (t.id || Date.now().toString(36))
如果一条待办没有 id(旧数据、手工构造、或者哪个分支忘了赋 id),就会退化成 Date.now().toString(36)。而 forEach 是同步的,一批 20 条没有 id 的待办,很可能全部落在同一毫秒,于是 20 条 UID 完全相同。 日历看到 20 个同 UID 的 VEVENT,行为是按规范"后者覆盖前者"或者"忽略重复",结果就是你导出了 20 条,日历里只有 1 条。
这个坑不报错、不闪退、日志还告诉你 count: 20,你只有在日历里一条条数才会发现不对劲。我目前的待办都在创建时赋了 id,所以没炸,但这行代码的健壮性是靠上游保证的,不是它自己保证的。要修的话,退化成 Date.now().toString(36) + '-' + index 就够了。
DTSTAMP 和 DTSTART 不是一回事。 DTSTAMP 是"这个 VEVENT 对象什么时候被创建/修改",DTSTART 才是"事件什么时候开始"。前者用 Date.now(),后者用 t.due。我见过有人两个都写 t.due,导入后日历里"最后修改时间"全成了未来——不报错,但排序和同步会乱。
DTEND 必须晚于 DTSTART。 我给的是固定 15 分钟。这是个产品决策,不是技术约束:待办不是会议,没有"结束时间"这个概念,但日历要求一个区间。15 分钟足够让它在日历视图里画出一个小块,又不至于占满一格。如果哪天真要支持"时长",加个字段就行,t.due + (t.durationMin || 15) * 60 * 1000。
SUMMARY 是唯一一个必须转义的必填字段。 名字、时间都是数字和固定字符,只有标题是用户输入的自由文本。所以 esc 的唯一调用点在这里——加上 DESCRIPTION 那两处。
DESCRIPTION 那行是条件写的: if (t.due < Date.now())。这个判断的语义是"导出时已经逾期",注释也写了"(导出时已逾期)“。为什么强调"导出时”?因为你可以今天导出、下周才导入,那时候"逾期"这个状态可能已经不准了。.ics 是一次快照,不是状态同步。把时间语义写进文案,是防止未来自己误解的最便宜的办法。
VALARM 那一段,五个属性都不能少:
BEGIN:VALARM/END:VALARM包住;ACTION:DISPLAY说"弹一个提示"(还有AUDIO、EMAIL);TRIGGER:-PT0M是 ISO 8601 的时长格式,-PT0M= 负零分钟 = 事件开始时。PT15M是"开始后 15 分钟",-PT15M是"开始前 15 分钟";DESCRIPTION是弹窗里显示的文字,ACTION:DISPLAY下它是必需的,我复用了标题。
TRIGGER:-PT0M 这个写法值得说一句:你也可以写 TRIGGER;RELATED=START:-PT0M,显式声明"相对于开始时间"。不写 RELATED 时默认就是 START,所以我省了。但如果哪天要做"截止前 30 分钟提醒",这里要变成 TRIGGER:-PT30M,而且要想清楚:这是"开始前 30 分钟",不是"截止前 30 分钟"——因为 DTSTART 就是截止时刻。语义上有点绕,但日历只认 DTSTART。
版本差异:VALARM 在 API 20 的系统日历上工作正常,ACTION:DISPLAY 会变成一个通知。这一点我在真机上确认过,截图里那条"事件开始时"就是它。
5.5 落盘:为什么返回值必须是 { ok, path, count }
// main.js - todo:export-ics 的写文件部分(437-447 行,原文)
const exportDir = path.join(DATA_DIR, 'exports');
try {
fs.mkdirSync(exportDir, { recursive: true });
const file = path.join(exportDir, 'reminders-' + new Date().toISOString().slice(0, 10) + '.ics');
fs.writeFileSync(file, lines.join('\r\n') + '\r\n', 'utf-8');
console.log('[todos] .ics 导出: ' + list.length + ' 条 → ' + file);
return { ok: true, path: file, count: list.length };
} catch (e) {
return { ok: false, error: (e && e.message) || String(e) };
}
这段有四个决定,每个都能单独讲。
第一,mkdirSync(exportDir, { recursive: true }) 必须带 recursive。 不带的话,exports 目录不存在时 mkdirSync 抛 ENOENT,而不是帮你建。带了 recursive: true,目录存在也不报错(幂等),不存在就逐级建。这一行是整个函数里唯一"每次都要执行"的 IO,放在 try 里是必须的。
第二,DATA_DIR 是 app.getPath('userData')。 在 main.js 顶部它是这么来的:
// main.js - userDataDir()(节选 14-24 行,原文)
function userDataDir() {
try {
return app.getPath('userData');
} catch (_) {
// 极端情况(壳工程没配 userData)下退到临时目录,至少别让启动挂在第一步
return path.join(os.tmpdir(), 'ohos-notes');
}
}
const DATA_DIR = userDataDir();
这个 fallback 很重要。app.getPath('userData') 在 Electron-OH 上是可用的(落在应用沙箱 el2/base/haps/entry/files 下),但如果某个壳工程版本没配这个路径,它会抛。抛在模块顶层,整个应用起不来。包一层 try,退到 os.tmpdir(),至少应用能开,导出也能导(只是重启后文件没了)。“降级到能用"永远优于"启动就崩”。
第三,文件名用 toISOString().slice(0, 10),拿到的是 UTC 日期。 注意这里和 5.2 节的态度是矛盾的:icsStamp 里我坚持不用 toISOString,这里却用了。原因不同:icsStamp 的输出要进文件结构,一个字符错就坏;文件名只是个字符串,2026-11-21 这种格式几乎是 toISOString 的稳定契约。同一个 API,用在不同位置,风险等级不一样。
但这个选择有一个真实后果,我必须说:UTC 日期在北京时间晚上 8 点之后,会比本地日期晚一天。 比如本地 2026-11-21 23:00 导出,UTC 是 2026-11-21 15:00,还是 21 号;本地 2026-11-22 01:00 导出,UTC 是 2026-11-21 17:00,文件名就变成了 reminders-2026-11-21.ics。凌晨导出的人会觉得文件名"少了一天"。
我知道这个不一致,没有改。因为改的成本是引入一个本地日期格式化函数(又是一个要处理时区和补零的东西),收益是"文件名更符合直觉"。而文件名的真正作用是"同一天导出会覆盖同一份",UTC 边界只是让它偶尔在凌晨覆盖到前一天的文件。这是可接受的。
第四,lines.join('\r\n') + '\r\n',两个 CRLF。 join 负责行与行之间,末尾那个 + '\r\n' 负责最后一行之后。RFC 5545 要求每一行(包括最后一行)都以 CRLF 结束。少了结尾那个,严格的解析器会把 END:VCALENDAR 当成"没有终止符的行",有的直接拒绝。
为什么必须是 \r\n 不是 \n?这是 RFC 的硬规定,来自 iCalendar 的前身 vCalendar 时代(那会儿是 Unix 和 DOS 混战的年代,规范选了 DOS 的 CRLF 作为标准)。Unix 惯性让人习惯写 \n,但 .ics 不吃这一套。 很多解析器宽容,\n 也能读;但"很多能读"不是"都能读"。这一行代码的注释价值,比它本身的逻辑价值大。
返回值 { ok, path, count } 是三个不同的用途:
ok给分支判断;path给用户看(“文件在哪”),也是 diag 日志的内容;count给用户确认(“导出了几条”),同时是"过滤后"的数量,能对上他在提醒中心看到的数字。
如果只返回一个字符串路径,渲染层就得自己判断"空字符串算不算失败";如果只返回 true,用户不知道文件在哪,这个功能就废了一半——沙箱里的文件,用户拿不到路径就等于不存在。
catch 那一行 (e && e.message) || String(e) 也值得说:fs 抛的 Error 有 message,但万一抛的是个字符串或者别的什么(第三方库会这么干),e.message 是 undefined,兜底 String(e)。这种"防御性到有点丑"的写法,在错误处理里是必要的——错误处理代码自己抛错,是最难排查的一类问题。
6. 我踩过的坑(每一条都有真实报错)
这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。
坑1:DTSTART 少一个 Z,日历把它当成本地时间,差 8 小时。
第一版我写的是这个:
// 错误的写法:直接拼本地时间,没有 Z
const stamp = (ts) => {
const d = new Date(ts);
return d.getFullYear() + pad(d.getMonth() + 1) + pad(d.getDate())
+ 'T' + pad(d.getHours()) + pad(d.getMinutes()) + '00';
};
生成的 .ics 里是:
DTSTART:20261121T213000
一条本地时间 21:30 的待办,导入日历后显示在 05:30(第二天早上)。
现象很奇怪:不是"不显示",是"显示了但时间错"。我第一反应是"日历把 21:30 理解成了 UTC 21:30,然后按 UTC+8 显示成次日 05:30"——这个推断是对的,但我花了半小时才确认,因为我一开始怀疑的是"是不是 t.due 存错了"。
排查过程是这样的:先把 t.due 打出来,1795277400000,转成 Date 是 2026-11-21T21:30:00+08:00,没问题。那问题就在格式化。翻 RFC 5545 的 3.3.5 节(DATE-TIME),看到这句话:
If the value is specified in UTC time, the value MUST be suffixed with the character “Z”.
关键词是 MUST。不带 Z 的时间不是"本地时间",是"浮动时间"——意思是"你看着办"。系统日历的"看着办"就是按 UTC 解释。
修复就是 5.2 节那段,getUTC* 全家桶 + 结尾 'Z'。修完再测:
DTSTART:20261121T133000Z
本地 21:30(UTC+8)→ UTC 13:30 → 20261121T133000Z。对上了。
教训:.ics 里没有"本地时间"这个概念,只有"UTC"和"你以为的 UTC"。所有时间要么带 Z 写 UTC,要么带 TZID 参数显式声明时区,没有第三条路。
顺便说 TZID 那条路:DTSTART;TZID=Asia/Shanghai:20261121T213000 也是合法的,而且读起来更直观。我不选它,是因为它要求解析器认识 Asia/Shanghai 这个时区 ID,而不同平台对时区库的裁剪程度不一样。UTC 是零依赖的,TZID 是带依赖的。能用一个数字解决的问题,不要引入一张时区表。
坑2:标题里一个逗号,把整条事件的字段吃掉了。
测试数据里我随手写了一条 买牛奶,鸡蛋,面包。导入之后,这条事件的标题变成了 买牛奶,后面全没了。
生成的原始行是:
SUMMARY:买牛奶,鸡蛋,面包
在 RFC 5545 里,, 是值列表的分隔符。SUMMARY 的类型是 TEXT,理论上不该有列表语义,但解析器是按词法走的:它看到逗号,就认为"这个属性的值到这里是一段,后面是下一段"。多段的值在一些字段里是合法的(比如 CATEGORIES),在 SUMMARY 里就表现为"只取第一段"或者"整行解析失败"。
分号更狠:
SUMMARY:周五前交;务必
; 是参数的分隔符。它会把 务必 当成一个参数,而 SUMMARY 不接受这个参数名,严格的解析器直接拒绝整个 VEVENT。
排查时我做了一件很有用的事:把生成的 .ics 用纯文本编辑器打开,逐行看。 不是用日历打开——日历只说"打不开",不给行号。文本编辑器里那个裸逗号一眼就能看出来。
修复就是 5.3 节的 esc:
const esc = (s) => String(s).replace(/([,;\\])/g, '\\$1').replace(/\r?\n/g, '\\n').slice(0, 300);
转义之后:
SUMMARY:买牛奶\,鸡蛋\,面包
日历显示成 买牛奶,鸡蛋,面包,逗号还在,结构没坏。
教训:用户输入的每一个字符都是敌意输入。凡是要塞进结构化文本的自由文本,先问一句"这个字符在目标格式里有语法含义吗",有就先转义。
这个坑还有一个后续:换行。title 里带 \n(从别处粘贴来的多行文本)会直接撑断行,产出两行,第二行以文字开头,解析器认为这是一个未知属性,整条 VEVENT 报废。esc 里那个 .replace(/\r?\n/g, '\\n') 就是为它准备的。
坑3:\n 能导入,但导进去是乱的。
这个坑最阴,因为它不报错。
我一开始用的是 lines.join('\n')。在我的测试机上,导入成功,事件都在,时间也对。我差点就发货了。
后来换了一台设备测,导入后事件全部堆在同一天,标题和日期错位。我把两个设备上生成的文件 hexdump 对比,才看到差别:我这边生成的是 0a,规范要求的是 0d 0a。
# 看行尾到底是什么
xxd exports/reminders-2026-11-21.ics | head -6
# 正确:... 0d 0a 56 45 56 45 4e 54 ... (\r\nVEVENT)
# 错误:... 0a 56 45 56 45 4e 54 ... (\nVEVENT)
为什么"能导入但乱"?因为宽容的解析器会先把 \n 统一成 \r\n 再解析,这一步没问题;但它同时也会用 \r\n 去切"折行"(还记得 75 字节折行是 CRLF + 空格 吗)。行尾不统一,折行判断就乱,一些字段被当成"上一行的延续"拼到了别处。
修复:
fs.writeFileSync(file, lines.join('\r\n') + '\r\n', 'utf-8');
两个地方都要:join 的参数,和末尾那个手工加的 + '\r\n'。
教训:跨平台的文本协议,行尾不是风格问题,是语法问题。写 .ics、.vcf、HTTP 头这类东西,CRLF 是硬要求,别让编辑器的"自动转换行尾"替你决定。
顺带说一句我的自查方法:导出之后,永远用 xxd 或 od -c 看一眼前几十个字节。 肉眼在编辑器里看 \r 是看不见的,od -c 会把它打成 \r,一眼就知道。
坑4:contextBridge 下多传一个参数,第二个就没了。
这就是第 1 节埋的那个日志。回收一下。
第一版我为了让"导出"支持"选格式",写成这样:
// preload.js - 错误写法
contextBridge.exposeInMainWorld('todosApi', {
exportIcs: (todos, fmt) => ipcRenderer.invoke('todo:export-ics', todos, fmt)
});
主进程那边:
ipcMain.handle('todo:export-ics', (_event, todos, fmt) => { ... });
真机上 todos 是 undefined,fmt 也是 undefined。日志长这样:
[ipc] -> todo:export-ics
[ipc] <- todo:export-ics ok
通道 ok,数据没了。于是走进 if (!Array.isArray(todos)),界面 toast 导出失败:数据格式错误。
排查过程:我先在 preload 里 console.log(todos)——有值。再在主进程的 handler 第一行把 _event 之外的两个形参各打一次——两个都是 undefined。参数在过桥的时候丢了。
为什么?contextBridge.exposeInMainWorld 暴露的对象不是原样挂到 window 上的,它是一层词法绑定:V8 在隔离世界里建一个代理对象,你调 window.todosApi.exportIcs(a, b) 时,实际执行的是隔离世界里那个函数,参数要经过一次序列化/反序列化(structured clone 的变体)。这个过程中,多参数的支持在不同 Electron 版本上行为不一致,Electron-OH 这个裁剪过的运行时里,只有第一个参数能稳定过去。
我在 preload.js 的注释里看到过这个坑的痕迹,是登录那块:
// preload.js - authApi(节选 24-30 行,原文)
// 注册/登录只传一个对象参数:部分壳工程的 invoke 不透传多参数,
// 第二个参数会丢,导致密码永远是空、校验层每次都报错。
contextBridge.exposeInMainWorld('authApi', {
register: (username, password) => call('auth:register', { username, password }),
login: (username, password) => call('auth:login', { username, password }),
session: () => call('auth:session')
});
register 的签名是两个参数,但它们在 preload 内部就被合成了一个对象 { username, password },真正过桥的只有一个参数。这个写法是对的。
所以我改成了:
// preload.js - todosApi(40-45 行,原文)
contextBridge.exposeInMainWorld('todosApi', {
load: () => call('todos:load'),
save: (todos) => call('todos:save', todos),
path: () => call('todos:path'),
exportIcs: (todos) => call('todo:export-ics', todos)
});
exportIcs 只收一个 todos,单参数,稳。
教训:只要经过 contextBridge,就把调用约定收缩成"一个对象参数"。 需要两个值就 { a, b },需要十个也一样。这不是洁癖:过桥是一次序列化,序列化的边界上,“参数的形状"是最容易出问题的地方,而你拿到的现象是"值莫名变成 undefined”,不是报错。
这条教训的普适性比 .ics 大得多。我这个应用里 filesApi.dropImport(name, base64) 也是两个参数——它没炸,因为它内部立刻合成了 { name, base64 }。看签名不算数,要看真实过桥的那一层。
坑5:旧包的 preload 没有这个方法,直接调就是 TypeError。
这个坑是版本发布的现实问题,不是代码 bug。
我的应用是自更新的(其实不是,是我手动装新 HAP),所以用户设备上可能同时存在 1.0.11 和 1.0.12 的 preload。1.0.11 的 preload.js 里没有 exportIcs 这一行。而渲染层的 index.html 和 renderer.js 是跟着 HAP 一起换的——但在壳工程里,这两者的更新时机不一定同步。
如果渲染层是新的、preload 是旧的,todosApi.exportIcs 就是 undefined。直接调用:
Uncaught (in promise) TypeError: todosApi.exportIcs is not a function
at HTMLButtonElement.<anonymous> (renderer.js:1862)
用户看到的:点了按钮,什么都没发生,控制台里一串红字(他也看不到)。
所以渲染层加了这个探测:
// src/renderer.js - btnRcIcsEl 点击处理(1858-1861 行,原文)
if (!todosApi.exportIcs) {
toast('当前包不支持日历导出,请升级到 1.0.12+');
return;
}
注意它检查的是 todosApi.exportIcs 而不是 todosApi —— todosApi 一直都在(待办功能从 1.0.9 就有),变的是它上面的方法。 能力探测要探到"方法"这一级,探到"对象"这一级没有意义。
排查这个坑的时候,我干了一件蠢事:我在本地测怎么都不复现,因为我本地永远是最新包。后来我意识到"旧包"这个前提根本不在我的测试矩阵里,才想明白这是版本共存问题,不是代码问题。要复现很简单:把 preload.js 里 exportIcs 那一行注释掉,重启应用,点按钮。
教训:新增 IPC 方法时,渲染层的调用必须做存在性探测。 你没法保证 preload 和 renderer 永远同版本——尤其是壳工程把渲染资源放在 resfile 里、而 preload 可能被单独替换的情况下。探测的成本是三行,不探测的成本是用户看到"点了没反应"然后卸载。
这条还有一个延伸:探测到不存在之后,要给"怎么办",不是给"出错了"。 当前包不支持日历导出,请升级到 1.0.12+ 告诉用户"升级",而不是 功能不可用 让用户一脸问号。文案里的版本号 1.0.12 是硬编码的,这有点脏,但它准确地告诉了我自己"这个功能是哪一版加的",比 请升级到最新版 有用。
坑6:一天导两次,后一次把前一次覆盖了。
这个不是 bug,是我设计时没想清楚,后来明确接受的取舍。
文件名是 reminders- + UTC 日期 + .ics。同一天导出第二次,文件名一样,writeFileSync 直接覆盖。
我第一次发现是因为:上午导出了 3 条,中午把其中 2 条标了完成,下午再导出——文件里只剩 1 条。我以为导出坏了,cat 了一下文件,才发现是覆盖。
ls -l exports/
# -rw------- 1 u0_a123 512 2026-11-21 09:12 reminders-2026-11-21.ics
# -rw------- 1 u0_a123 218 2026-11-21 15:40 reminders-2026-11-21.ics ← 同一个文件
要不要改成带时间戳(reminders-2026-11-21T154000.ics)?我考虑过,最后没改。理由:
- 这个文件的定位是"当前待办的一个快照",不是"历史归档"。用户要的是"最新的那份",不是"每一份"。
- 带时间戳会让
exports目录一天堆十几个文件,用户还得挑哪个是最新的。 - 覆盖语义是"幂等的":同一天任何时候点,拿到的都是"此刻的完整状态",这对"导入日历"这个动作是对的。
但这是一个需要被写下来的决定,否则半年后的我会以为它是 bug。 所以我在这里写清楚:文件名按 UTC 日期,同一天覆盖,语义是"当日快照",不是"追加归档"。 如果你要归档,改文件名就行,一个 Date.now() 的事。
教训:凡是"命名规则"类的代码,都要问一句"重复执行会怎样"。 幂等、覆盖、追加,是三种完全不同的产品语义,选哪个都行,但你必须知道你在选哪个。
坑7:DESCRIPTION 写"已逾期",但它说的是"导出那一刻"。
最后一条是个语义坑,不是技术坑,但它让我在真机上困惑了一阵。
代码是:
// main.js - 431 行,原文
if (t.due < Date.now()) lines.push('DESCRIPTION:' + esc('(导出时已逾期)'));
我导出之后隔了两天才导入日历。结果那天看日历,一条三天前的待办,描述里写着"(导出时已逾期)"——读起来像是"导出那一刻就逾期了",但我导出的时候它还没到期。
问题不在代码,在我的理解:t.due < Date.now() 是生成文件那一刻求值的。快照嘛,本来就该这样。但我当初写文案的时候想的是"给用户一个提示",读的时候却变成了"给未来一个断言"。
后来我给文案加了"导出时"三个字(就是现在这个),因为它准确描述了求值时机。三个字解决了一个"看起来像 bug 的语义模糊"。
教训:写进文件、日志、数据库的每一句话,都有一个"求值时刻",而这个时刻不会跟着文件一起旅行。 时间敏感的描述必须把求值时刻写进文本本身,否则读的人(包括未来的你)一定会按"现在"去理解它。
7. 现在怎么用
构建与安装。
这个应用没有独立的构建脚本,它是壳工程的一部分,跟着 HAP 走。我在 DevEco Studio 里直接 Build → Build Hap(s),构建模式选 module、product 用 default:
# 工程根目录,构建单模块 HAP(hvigor 由 DevEco 托管,参数按本机 wrapper 为准)
hvigorw --mode module -p product=default assembleHap
产物在 entry/build/default/outputs/default/ 下,hdc install 装到设备。签名材料不要进仓库——在 DevEco 里勾 “Automatically generate signature”,口令留在本机。
版本门槛。
导出功能从 1.0.12(versionCode 1000012)开始有。低于这个版本,按钮会提示升级,不会崩。这条门槛是渲染层的能力探测实现的,不依赖 package.json 的版本号——因为 package.json 里写的还是 1.0.0(那是 Electron 应用自己的版本,和 HAP 版本是两套东西,别搞混)。
测试。
/tmp/rc.test.js 是一个纯 Node 的断言脚本,不启动 Electron,把 icsStamp 的逻辑抠出来跑。核心断言是这几条:
// /tmp/rc.test.js - icsStamp 格式与 UTC 换算断言(节选)
const local = new Date(2026, 10, 21, 21, 30, 0); // 本地 2026-11-21 21:30(UTC+8)
assert.strictEqual(icsStamp(local.getTime()), '20261121T133000Z');
assert.match(icsStamp(Date.now()), /^\d{8}T\d{6}Z$/);
assert.strictEqual(icsStamp(new Date(2026, 0, 1, 0, 0, 0).getTime()), '20251231T160000Z'); // 跨年
三条断言分别管三件事:UTC 换算对不对(21:30 本地 → 13:30Z)、格式对不对(八位日期 + T + 六位时间 + Z)、跨年边界对不对(本地 2026-01-01 00:00 → UTC 2025-12-31 16:00,年份要退一位)。
最后那条最有价值。我一开始只写了前两条,跑过了,觉得没事。后来加跨年那条,才发现如果 getUTCFullYear() 和 getUTCMonth() 的顺序写反,跨年测试会立刻红——而前两条在 11 月的数据上根本测不出来。
跑法:
node /tmp/rc.test.js
# icsStamp: 3 assertions passed
测试数量:3 条断言,覆盖 1 个函数。 听起来很少,但导出链路里值得单测的只有这一个——esc 是正则,fs 是 IO,forEach 是拼装,它们要么是确定性的,要么是框架保证的。把测试花在"有分支、有时间、有边界"的地方。
硬限制清单,免得读者踩到同一堵墙:
- 不能直接写系统日历。 没有 ArkTS 桥就没有
calendarManager,这条路在 JS 层是封死的。要直写,得在壳工程里加 module + 权限 + 签名,本文不做。 - 不支持时区。 全部 UTC 写死,没有
TZID。跨国用户的"晚上 9 点"会变成他所在时区的"晚上 9 点对应的那个绝对时刻",不是"他当地的晚上 9 点"。 - 不支持重复规则。 没有
RRULE。每周一开会这种待办,导出后只有一次。加RRULE:FREQ=WEEKLY是一行的事,但"从哪天开始算、算到哪天结束、跳过节假日吗"是三个产品问题,不是一个技术问题。 - 不做 75 字节折行。 长标题在宽容的解析器上没问题,在最严格的解析器上可能被截断。欠账,明确记着。
- 需要用户手动导入。 文件落在沙箱里,应用没有"分享到日历"的入口(那需要另一个系统能力)。用户得通过文件管理器找到它,或者我把路径显示出来让他自己想办法。
- 文件名按 UTC 日期,同一天覆盖。 语义是"当日快照",不是归档。
- 提醒时间固定在事件开始。
TRIGGER:-PT0M,没有"提前 15 分钟"的选项。
最后说一段我自己的认知变化。
写这个功能之前,我脑子里"系统能力"和"文件"是两种东西:前者高级、实时、双向;后者原始、静态、单向。所以我的第一反应是"想办法接桥"。
写完这个功能之后,我的排序反过来了。文件是唯一一种不需要对方配合就能交付的接口。 我不需要系统日历给我权限,不需要它暴露 API,不需要跟它的版本对齐,我只需要它"认识这个格式"——而这个格式是二十年前就定死的公开标准。这种"单向但普适"的能力,在跨端场景里比"双向但绑定"的能力值钱得多。
这也是我在这个 Electron-OH 项目里学到的最实用的一课:当一座桥的成本高于一条路的成本时,先看看有没有一条不需要桥的路。 .ics 就是那条路。
如果这篇文章只能留一句话,我会留这句:你要的不是一个能写日历的 API,而是一份别人愿意读的文件。
8. 快问快答
Q:为什么不用 TZID 而要手算 UTC?本地时间不是更好读吗?
好读是给人的,UTC 是给解析器的。TZID 要求解析器认识时区数据库,而不同平台裁剪程度不一样。UTC 是零依赖的。除非你要做"每天本地 9 点"这种跟时区绑定的重复日程,否则 UTC 永远是更稳的选择。
Q:DTEND 为什么是 15 分钟?能不要吗?
能给也可以不给。RFC 5545 里 DTEND 和 DURATION 二选一,都不给的话就是"零时长事件",很多日历会把它画成一个点,看起来像没导入成功。15 分钟是我试出来的"能看见又不占地方"的值。
Q:UID 里的 @ohos-notes 需要是真实域名吗?
不需要。规范只要求"全局唯一",@ 后面那部分是个命名空间约定,写什么都行。但别省掉 @ 和后面那段,有些解析器会按 local@domain 的形式校验。
Q:导出的文件在沙箱里,用户怎么拿到?
三条路:文件管理器进 Android/data 那种路径(鸿蒙上是 el2/base/haps/entry/files)、应用内做一个"分享"按钮(需要额外能力)、或者干脆让用户复制路径。我目前只做了第三条——toast 里显示完整路径。这是个明显的产品欠账,但技术上导出这条链路是通的。
Q:为什么不用 dialog.showSaveDialog 让用户选位置?
因为 Electron-OH 里 dialog 的能力是裁过的。main.js 里 files:pick 那段就写了:typeof dialog.showOpenDialog !== 'function' 时直接返回"当前壳工程不支持文件选择对话框"。保存对话框同理,我不赌它存在。落沙箱是唯一稳定可用的路径。
Q:标题 300 字够吗?
够。待办标题的合理长度是 20 字以内,300 是"再长也不会出问题"的上限。真到了 300 字,问题不在截断,在这个待办本身该拆成十条。
Q:为什么不用第三方库生成 ics?
因为整个格式我只需要 12 行属性。引一个库进来,要处理它的依赖、它的 Node 版本要求、它在 Electron-OH 里的兼容性——成本远高于手写。当需求小于库的体积时,不要引库。
Q:导入日历之后,应用里改了待办,日历会同步吗?
不会。这是一次快照导入,不是订阅(订阅要 .ics 放在一个 HTTP URL 上,日历定期拉取)。要同步,得重新导出、重新导入,日历那边会按 UID 覆盖旧的那条——这也是 UID 稳定的意义。
Q:这套代码能直接搬到 Flutter / RN 吗?
能,而且几乎是原样。整个逻辑就是"数组 → 字符串数组 → 文件",跟 UI 框架一点关系没有。你要换的只有两处:文件写到哪(Flutter 用 getApplicationDocumentsDirectory,RN 用 RNFS.DocumentDirectoryPath)、怎么把结果告诉界面(Flutter 用 MethodChannel 回 setState,RN 用 Promise)。ICS 拼装那 30 行,一个字都不用改。
Q:为什么不干脆做个 ArkTS 桥,直接写日历?
因为我要的是"提醒能被叫醒",不是"数据进日历"。桥的成本是权限申请 + 签名改动 + 每个设备形态的适配 + 用户拒绝授权的分支,收益是"少一步手动导入"。这笔账在我这个一人项目里算不过来。如果这个应用有一百万用户,答案可能反过来——但那不是现在。
更多推荐


所有评论(0)