Electron 接入鸿蒙系统日历实战:Node-API 透传对接 CalendarKit,拆解授权、模型差异、跨日历检索问题
Electron 应用跑上鸿蒙之后,最大的落差不是 UI,而是系统能力:日历这东西在鸿蒙上只归 ArkTS 管,Electron 主进程的 Node.js 既没有权限也没有通道直达它。怎么把
@kit.CalendarKit封装成一个 Electron 可用的三方库、怎么用 Node-API 加 JSON 透传打通"JS → 原生"这条链、为什么增删改在真机上全成功而查询却返回 0 条——这篇文章用一个跑在鸿蒙真机上的 Electron 三方库,把这三个问题一次讲透。
示例仓库:https://atomgit.com/dijun_520/electron-ohos-calendar
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-Electron/Electron/tree/v40.1.0-openharmony
CPF-Electron 鸿蒙社区:https://atomgit.com/CPF-Electron
0. 环境与实测设备
| 项目 | 版本 |
|---|---|
| 开发工具 | DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk) |
| 系统 API | HarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0) |
| Electron | 桌面示例 electron 40.1.0(Chromium 144 / Node 24);鸿蒙端为 CPF-Electron v40 运行时(libelectron.so) |
| Node.js | ≥ 22.11.0 |
| 实测设备 | HarmonyOS 7 PC(MateBook Pro) |
1. “装个 npm 日历库不就行了”
接到这个题的时候,我第一反应是:日历嘛,Electron 有完整的 Node.js,npm 上日历库一抓一把,装一个就完了。
我一开始也以为它只是"主进程里 require 一个日历模块,增删改查走本地存储或者系统 API"。这个理解撑了我大概半小时——直到我把鸿蒙 SDK 里的 @ohos.calendarManager.d.ts 翻开,看到的是另一番景象:
// @ohos.calendarManager.d.ts(HarmonyOS SDK 26,去注释后的关键形状)
function getCalendarManager(context: Context): CalendarManager;
interface CalendarManager {
createCalendar(calendarAccount: CalendarAccount): Promise<Calendar>;
deleteCalendar(calendar: Calendar): Promise<void>;
getCalendar(calendarAccount?: CalendarAccount): Promise<Calendar>;
getAllCalendars(): Promise<Calendar[]>;
}
interface Calendar {
readonly id: number;
addEvent(event: Event): Promise<number>;
updateEvent(event: Event): Promise<void>;
deleteEvent(id: number): Promise<void>;
getEvents(eventFilter?: EventFilter, eventKey?: (keyof Event)[]): Promise<Event[]>;
}
三个细节立刻推翻了理解:
- 这套 API 只存在于 ArkTS 世界。
calendarManager是@kit.CalendarKit的 ArkTS 模块,没有 NDK C 接口、没有给 Node.js 的 binding。Electron 主进程的 Node 再全能,也够不着它——中间隔着一条 JS → Node-API → ArkTS 的桥,这条桥要自己搭。 - 权限是 user_grant。
READ_CALENDAR/WRITE_CALENDAR在module.json5里声明了不算数,必须运行时调requestPermissionsFromUser,由用户在系统弹窗里点头。 - d.ts 的形状和网上教程对不上。 教程里的
CalendarMetadata、editEvent、reminders: ReminderInfo[]在 SDK 26 的声明文件里要么不存在、要么换了形状。
所以这个题目的边界很清楚:把鸿蒙日历读写封装成 electron-ohos-calendar 三方库——JS 门面定契约,Node-API 做 JSON 透传桥,ArkTS HAR 用 calendarManager 干真活;桌面端自动降级 Mock 保证双端 API 一致,鸿蒙端把日程真正写进系统日历。
拆下来是三件事:
- 把 JS 侧的日历操作(建日历、事件增删改查、权限申请、变更订阅)翻译成 ArkTS 侧的
calendarManager调用; - 把原生结果与错误用统一协议回传给 Electron 主进程,再用 IPC 透给渲染进程;
- 在没有鸿蒙运行时的桌面环境提供 Mock 后端,让业务代码一行不改就能在两套世界之间切换。
2. 效果展示

这是首次运行验证工程的截图。这里每一处都不是装饰:
- 弹窗标题"允许’日历真机验证’读取和修改此应用的日程?“来自系统的权限申请框,而弹窗里的那行说明文字"用于读写系统日历,验证三方库的日程增删改查能力”,来自
module.json5里requestPermissions的reason字符串; - 弹窗出现的时机是点击"开始验证"之后,不是应用启动时——
requestPermissionsFromUser必须有 UIAbility 上下文; - 顶部的"验证中…"置灰按钮对应
running状态位:验证没跑完之前,二次点击会被这个位拦住。

这是点完"允许"之后的验证结果页。列表可滚动,首屏能看到前 10 步,第 11 步(清理测试日历)在首屏之外。这里每一行都不是装饰:
requestPermissions | read=true write=true来自requestPermissionsFromUser的authResults——刚才那一下"允许"的数字化结果;getCalendars | 共 1 个日历: Phone(id=1)是getAllCalendars()的返回——上一轮验证结束时会清理测试日历,所以此刻系统里只剩系统自带的 Phone 日历;createCalendar | id=4 name=EOC测试日历是createCalendar(CalendarAccount)创建的本地日历,打开系统"日历"应用能在账号列表里看到它;addEvent | eventId=4是calendar.addEvent(Event)写进系统日历的事件,带 15 分钟提醒、地点、备注;getEvents(区间查询) | 命中 1 条、getEvent | title=... location=深圳 · 会议中心、updateEvent | 新标题=...、deleteEvent、复核删除——增删改查加复核;- 每一步的 PASS/FAIL 同时写入 hilog(tag=
EocDeviceTest),UI 和日志互为备份。
验证工程跑完,日程是真的进了系统日历——不是写进自家沙盒自己看。另外跑了一轮演示模式(验证流程不变,只是不执行删除,再多写两条日程),然后打开系统"日历"应用逐个截图核对。
先看月视图:11 月 13、14、15 三天的日期下方各多了一个小红点,正好对应写入的三条日程;底部"今天"卡片把首条日程展开——18:35-19:35,标题、来源(日历真机验证)、地点(深圳 · 会议中心)一字不差:

点开这条日程看详情。这里最有说服力的是中间那两行:

- “日历账户 | ● EOC测试日历”——红点就是
createCalendar时传的#E53935,说明日历颜色一路从 JS 侧的 JSON 传到了系统日历数据库; - “由 electron-ohos-calendar 写入”——系统日历把这条日程的创建者标记为三方库的日历账号,而不是系统自带的 Phone 日历;底下一行小字"该日程由’日历真机验证’创建,可在’日历设置’>'来自其他应用’管理此类数据"。
切到日视图,今天的日程块落在 18:35 的时刻线上,颜色与日历一致:

周视图能看到跨天的写入效果——周五(13 日)的"EOC真机验证日程"和周六(14 日)的"架构评审会(EOC demo)"分列两天,颜色相同,因为它们同属 EOC测试日历:

最后打开日历 App 左上角的侧边栏,"日历账户"分组下多了一个"应用日程"分组,EOC测试日历挂在里面,前面的勾选框也是那个红色——用户不勾选它,它的日程就整组隐藏。

主动交代边界:截图里的步骤列表验证的是三方库的鸿蒙原生核心实现(ArkTS HAR ↔ calendarManager ↔ 系统日历),这也是三方库的能力本体。Electron 壳(Node-API 桥 + Electron 运行时)的打包验证需要在 Electron-OHOS 宿主工程里完成,流程相同,本文第 4 节给接线方式。桌面端走的是 Mock 后端——数据落在本地 JSON 文件,API 与鸿蒙端完全一致,node test/smoke.js 的 14 项断言全部通过。
UI 之外还有一条日志线,和截图互为备份。每一步的 PASS/FAIL 都写进 hilog(tag=EocDeviceTest),这一轮真机验证的完整记录:
11-13 17:22:06.156 ... [PASS] requestPermissions | read=true write=true
11-13 17:22:06.156 ... [PASS] isManagerAvailable | available=true
11-13 17:22:06.209 ... [PASS] getCalendars | 共 1 个日历: Phone(id=1)
11-13 17:22:06.276 ... [PASS] createCalendar | id=4 name=EOC测试日历
11-13 17:22:06.398 ... [PASS] addEvent | eventId=4 (11/13/2026, 6:22:06 PM)
11-13 17:22:06.427 ... [PASS] getEvents(区间查询) | 命中 1 条,首条: EOC真机验证日程
11-13 17:22:06.460 ... [PASS] getEvent | title=EOC真机验证日程 location=深圳 · 会议中心
11-13 17:22:06.526 ... [PASS] updateEvent | 新标题=EOC真机验证日程(已更新)
11-13 17:22:06.569 ... [PASS] deleteEvent | 已删除 eventId=4
11-13 17:22:06.600 ... [PASS] 复核删除 | 确认已删除
11-13 17:22:06.666 ... [PASS] 清理测试日历 | 已删除测试日历 id=4
这份日志比截图多交代了两件事:最后的"清理测试日历"保证了验证工程跑完不留垃圾——每轮验证的日历 id 递增(2、3、4),因为日历数据库的自增 id 不会回收,但跑完即清理,系统日历不会变脏;requestPermissions 在已授权后直接返回 granted、不弹框。

3. 原理:日历到底归谁管
先给全文最重要的模型判断:在鸿蒙上,日历不是 Electron 的能力,是 HAP 的能力。 Electron 应用在鸿蒙上是以 HAP 形态运行的——Chromium 和 Node.js 跑在一个由 ArkTS 壳承载的运行时里。calendarManager 的句柄挂在 ArkTS 世界的 UIAbility 上下文上,权限授给的是 bundle,不是 Node 进程。Electron 主进程想摸日历,必须穿过运行时边界,把调用递给 ArkTS 侧的代码。
第二个判断:Node-API 是唯一的桥,JSON 是唯一的语言。 Electron 主进程加载一个 Node-API 插件,插件把"方法名 + JSON 参数"透传给 ArkTS 侧注册进来的实现函数;ArkTS 干完活,把结果序列化成 JSON 字符串沿原路返回。我不在桥上做任何逐方法的强类型绑定——ArkTS 与 JS 的对象模型差异全部收敛在 JSON 这一层,桥保持三行协议不变。
把整条链路的接口和事件整理成表:
| 接口/事件 | 方向 | 参数 | 应用要回答什么 |
|---|---|---|---|
call(method, argsJson) | Electron JS → NAPI → ArkTS | 方法名 + JSON 参数 | getCalendars/addEvent 等 10 个 method 之一的 JSON 结果 |
SetArkBridge(fn) | ArkTS → NAPI | CalendarBridgeImpl.call | ArkTS 侧实现已就绪,桥可以转发了 |
emitEvent(payloadJson) | ArkTS → JS | {kind, data, timestamp} | 变更通知:added/updated/removed/calendarChanged |
requestPermissionsFromUser | 应用 → 系统 | 权限名数组 | 用户点没点允许(authResults[i] === 0) |
EventFilter.filterByTime(start, end) | 应用 → 系统 | 13 位毫秒时间戳区间 | 区间内的事件列表 |
两个细节决定了后面所有的实现取舍:
- READ/WRITE_CALENDAR 是 user_grant 权限。 静态声明只是"申请资格",运行时必须走一次系统弹窗;已授权后再调
requestPermissionsFromUser不弹框、直接返回 granted——所以"启动时探测 + 点击时申请"两步都要留。 - 事件 id 全局唯一,日历实例不是。 id 是日历数据库维度的,而
Calendar实例是账号维度的——默认日历不一定是事件所在日历。
还有一个背景判断值得单独交代:Electron-OHOS 的运行形态决定了这条桥非搭不可。 按官方指导仓(openharmony-sig/electron)的方案,Electron 应用在鸿蒙上以 HAP 形态分发——Chromium 渲染、Node.js 主进程跑在原生运行时里,外面套一层 ArkTS 壳(UIAbility + 资源)。这个壳不是可有可无的包装:UIAbility 上下文、权限身份、系统能力句柄全在它手里。
4. 工程怎么搭
这次整理最关键的变化,是把"能跑"变成"能复用":JS 接口、原生实现、示例工程三件事拆进三个目录,互相只通过公共边界说话。
electron-ohos-calendar/
├── index.js / index.d.ts # npm 包入口:单例门面 + 类型契约
├── src/
│ ├── calendar.js # API 门面:detect/权限/日历/事件/onChange
│ ├── events.js # 统一事件通道(kind 区分,单事件名多负载)
│ └── bridge/
│ ├── index.js # 后端选择器:鸿蒙优先,桌面自动 Mock
│ ├── ohos-bridge.js # 鸿蒙后端:call(method, argsJson) → NAPI
│ └── mock-bridge.js # 桌面后端:本地 JSON 存储,同契约
├── native/
│ ├── binding.gyp # OS=='ohos' 时定义 __OHOS__
│ └── calendar_napi.cpp # Node-API 桥:JSON 透传 + SetArkBridge
├── harmony/calendar_har/ # ArkTS HAR(源码方式参与宿主编译)
│ ├── Index.ets # 导出 CalendarBridgeImpl / registerCalendarBridge
│ └── src/main/ets/
│ ├── CalendarBridgeImpl.ets # @kit.CalendarKit 真实读写
│ ├── Register.ets # 宿主接线:把 call 注册进 NAPI 桥
│ └── model/CalendarModel.ets # ArkTS Event ↔ JSON 模型互转
├── example/ # Electron 日程管理示例(main/preload/renderer)
├── device-calendar-test/ # ArkUI 真机验证工程(本文截图来源)
└── test/smoke.js # 桌面冒烟:14 项断言
三条边界:src/ 不带任何 UI,只出 API 与事件;harmony/ 不感知 Electron 组件,只认 call 协议与 JSON;example/ 只走公共 API,不绕过封装直接摸原生。
JS 侧最小接入(15 行):
// 业务主进程 - 三步:探能力 → 申请权限 → 增删改查
import ohosCalendar from 'electron-ohos-calendar';
// 探能力:一次跨端往返拿全快照
const cap = await ohosCalendar.detect();
// { backend: 'ohos' | 'mock', managerAvailable, permissions, calendarsCount }
// 申请权限(鸿蒙端弹系统授权框;Mock 端直接通过)
const perms = await ohosCalendar.requestPermissions();
// 写日程:写进系统日历(Mock 端写进本地 JSON)
const { id } = await ohosCalendar.addEvent({
title: '架构评审会议', location: 'B2 会议室',
startTime: Date.now() + 3600e3, endTime: Date.now() + 7200e3,
isAllDay: false, reminders: [15], recurrence: 'none',
});
通道协议只有一条:call(method, argsJson) → Promise<resultJson>。method 的清单是三方对齐的硬契约(JS 门面、C++ 桥、ArkTS 实现三处同名):
isManagerAvailable / getPermissions / requestPermissions /
getCalendars / createCalendar / addEvent / updateEvent /
deleteEvent / deleteCalendar / getEvent / getEvents
ArkTS → JS 的变更事件走同一个事件名,kind 字段区分类型:
{ "kind": "added", "data": { "id": 3 }, "timestamp": 1763017200000 }
两个容易被忽略的窗口期:
SetArkBridge之前不能有call进来。 ArkTS 侧注册发生在宿主 UIAbility 就绪之后,而 Electron 主进程启动更早。桥的桌面对策是 fail fast:ArkTS 桥没注册,call直接抛 “ark bridge not registered”,让问题在第一时间暴露,而不是把 undefined 悄悄传回业务层;- 后端选择是惰性且一次性的。
selectBackend()在第一次 API 调用时执行并缓存,事件 sink 在此刻接线——这保证了订阅者不会错过后端初始化期间发出的第一波变更事件。
5. 把代码讲透
5.1 后端选择:一次探测,两条链路
Electron 三方库和 RN 三方库最大的不同:它必须同时活在两个世界里。桌面上没有 calendarManager,硬试原生只会把主进程搞崩。
// src/bridge/index.js - selectBackend()(节选)
function tryLoadOhosNative() {
const isOhosEnv = process.env.OHOS_ARCH || process.env.OHOS_API_VERSION ||
(typeof process.ohos === 'object' && process.ohos !== null);
if (!isOhosEnv) return null;
for (const rel of ['../native/build/Release/calendar_napi.node',
'../native/build/Debug/calendar_napi.node']) {
try { return require(rel); } catch (err) { /* 尝试下一个候选 */ }
}
console.warn('[electron-ohos-calendar] OHOS env detected but native addon not found, fallback to mock');
return null;
}
二个细节值得单独说:
第一,环境探测看的是运行时注入,不是 process.platform。 Electron-OHOS 运行时会在环境变量里注入 OHOS 标识(OHOS_ARCH/OHOS_API_VERSION)。
第二,Mock 不是调试开关,是正式后端。 它实现与鸿蒙端完全相同的方法清单,数据落地本地 JSON——业务代码在桌面上跑的每一行,到了鸿蒙上一行不改。
5.2 Node-API 桥:三行协议打天下
// native/calendar_napi.cpp - Call()(节选)
#ifdef __OHOS__
if (g_arkBridge == nullptr || g_arkEnv == nullptr) {
Napi::Error::New(env, "[electron-ohos-calendar] ark bridge not registered; "
"call SetArkBridge from HAP shell").ThrowAsJavaScriptException();
return env.Null();
}
napi_value promise = nullptr, argv[2];
napi_create_string_utf8(g_arkEnv, method.c_str(), method.size(), &argv[0]);
napi_create_string_utf8(g_arkEnv, argsJson.c_str(), argsJson.size(), &argv[1]);
napi_call_function(g_arkEnv, g_arkBridge, g_arkBridge, 2, argv, &promise);
#else
// 桌面编译分支:直接抛错,触发 JS 层 Mock 降级
#endif
三个细节值得单独说:
第一,桥不认识任何一个具体方法。 call(method, argsJson) 里的 method 是字符串,C++ 层零分支——所有方法语义都在 ArkTS 侧的 switch 里。代价是丢掉了编译期方法校验,收益是加方法不用重编桥,且 ArkTS/JS 的模型差异不会渗进 C++。
第二,SetArkBridge 是注册点,也是时序点。 宿主壳在 UIAbility 就绪后把 CalendarBridgeImpl.call 注册进插件(Register.ets 干的事)。注册前任何 call 都会抛错——这不是防御性编程,是把"接线没做"这个事实第一时间喊出来。
第三,事件回推走的是同一条通道的反方向。 ArkTS 侧 emitToJs(payloadJson) → 宿主注册的 sink → napi.emitEvent(payloadJson) → JS 的 onEvent 回调 → 门面的统一事件名。四跳,每跳都只传字符串,任何一跳都不需要知道 kind 的语义。
5.3 权限:user_grant 的两段式
// harmony/calendar_har/src/main/ets/CalendarBridgeImpl.ets - requestPermissions()(节选)
const result = await atManager.requestPermissionsFromUser(this.context, perms);
let read = false;
let write = false;
// permissions 是权限名数组,authResults 是对应的授权结果(0=授权)
for (let i = 0; i < result.permissions.length; i++) {
if (result.authResults[i] !== 0) continue;
if (result.permissions[i] === 'ohos.permission.READ_CALENDAR') read = true;
if (result.permissions[i] === 'ohos.permission.WRITE_CALENDAR') write = true;
}
三个细节值得单独说:
第一,静态声明只是资格赛。 module.json5 里写了 requestPermissions,权限框也不会自己弹——必须运行时调 requestPermissionsFromUser。库里把它封装成 requestPermissions(),业务侧一行调用。
第二,授权结果在 authResults,不在 permissions。 result.permissions 是权限名字符串数组,authResults[i] === 0 才是"用户点了允许"。
第三,已授权后重复申请不弹框。 第二轮验证时授权框直接没出现、read=true write=true 秒回——所以"detect 时查状态、点击时申请"的两段式不会造成重复打扰,业务侧可以放心每次操作前都调。
权限的"查"这一半是同步 API,同样和教程写法不同:
// harmony/calendar_har/src/main/ets/CalendarBridgeImpl.ets - getPermissions()(节选)
const bundleInfo = bundleManager.getBundleInfoForSelfSync(
bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION);
const tokenID = bundleInfo.appInfo.accessTokenId;
const atManager = abilityAccessCtrl.createAtManager();
const read = atManager.checkAccessTokenSync(tokenID, 'ohos.permission.READ_CALENDAR');
result['read'] = read === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
这里有两个版本差异要钉住:取自身 tokenID 用的是 getBundleInfoForSelfSync(同步版,教程里的 getBundleInfoForSelf 是 Promise 版);查授权状态用的是 checkAccessTokenSync(旧名 verifyAccessToken 已标废弃)。同步版在这里不是偷懒——getPermissions 会在 detect() 里被并发调用,少一层 Promise 包装,事件回调里随时重算能力快照的成本就低。
5.4 事件模型:把 SDK 26 的真实形状翻译成扁平 JSON
// harmony/calendar_har/src/main/ets/model/CalendarModel.ets - toNative()(节选)
const event: calendarManager.Event = {
id: model.id,
type: calendarManager.EventType.NORMAL, // ← SDK 26 必填
title: (patch.title as string) ?? model.title,
startTime: (patch.startTime as number) ?? model.startTime,
endTime: (patch.endTime as number) ?? model.endTime,
isAllDay: (patch.isAllDay as boolean) ?? model.isAllDay,
description: (patch.description as string) ?? model.description, // ← 纯 string
};
if (reminders !== undefined && reminders.length > 0) {
event.reminderTime = reminders.slice(); // ← number[],不是对象数组
}
const rule: calendarManager.RecurrenceRule = { 'recurrenceFrequency': freq };
event.recurrenceRule = rule;
三个细节值得单独说:
第一,Event.type 必填。 教程里没有这一项,SDK 26 的 d.ts 里它没有 ?。漏了它,buildNativeEvent 构造出来的事件过不了编译。NORMAL 是三方应用的唯一合理取值,IMPORTANT 明说了不推荐三方用。
第二,提醒和描述都是"朴素形状"。 description 是纯 string,不是教程里的 {value};提醒是 reminderTime: number[](提前分钟数数组),不是 ReminderInfo 对象数组。这些差异全部被 CalendarModel 收敛。
第三,重复规则是枚举不是字符串。 JS 侧传 'daily'/'weekly'/'monthly'/'yearly',ArkTS 侧映射成 RecurrenceFrequency(YEARLY=0/MONTHLY=1/WEEKLY=2/DAILY=3)。映射表写在模型文件顶部,'none' 不映射——传了等于没传。
5.5 跨日历检索:事件 id 全局唯一,日历实例不是
// harmony/calendar_har/src/main/ets/CalendarBridgeImpl.ets - resolveCalendars()(节选)
private async resolveCalendars(calendarId: number | undefined): Promise<calendarManager.Calendar[]> {
const calMgr = this.checkManager();
if (calendarId !== undefined && Number.isFinite(calendarId)) {
const all = await calMgr.getAllCalendars();
const target = all.find(c => c.id === calendarId);
if (!target) this.fail('ENOCALENDAR', `calendar not found: ${calendarId}`);
return [target as calendarManager.Calendar];
}
return calMgr.getAllCalendars(); // ← 未指定就遍历全部日历
}
三个细节值得单独说:
第一,getCalendar() 的缺省返回不一定是事件的家。 不带参数的 getCalendar() 返回默认日历,而 addEvent 可以写进任何一个日历。事件 id 是数据库维度的,Calendar 实例是账号维度的——拿默认日历的实例去 getEvents()。
第二,读和改都必须跨日历。 getEvent/getEvents 遍历所有日历合并结果;updateEvent/deleteEvent 先遍历找到事件所在的日历实例,再在那个实例上执行——deleteEvent(id) 虽然实测跨实例也能删。
第三,区间过滤用静态方法。 SDK 26 的 getEvents 收的是 EventFilter 类的实例,构造方式是 EventFilter.filterByTime(start, end) 静态方法——不存在教程里 {start, end} 字面量过滤器。
跨日历合并排序和去重的责任都在这一层:
// harmony/calendar_har/src/main/ets/CalendarBridgeImpl.ets - getEvents()(节选)
const calendars = await this.resolveCalendars(args.calendarId as number | undefined);
const useRange = start !== undefined && end !== undefined && Number.isFinite(start) && Number.isFinite(end);
const models: CalEvent[] = [];
for (const calendar of calendars) {
const events = useRange
? await calendar.getEvents(calendarManager.EventFilter.filterByTime(start as number, end as number))
: await calendar.getEvents();
for (const e of events) {
models.push(CalEvent.fromNative(e, calendar.id));
}
}
注意这里没有用 Promise.all 并发拉所有日历——calendarManager 的接口没有给出并发安全的承诺,串行 for-of 是稳的选择;区间过滤交给系统(filterByTime 在数据库层执行)。
6. 踩坑与经验
坑一:照着教程写 CalendarManager,SDK 26 上全对不上。 我一开始按网上教程写 createCalendar({ name, displayName, color, accountType, identifier }),又给 Calendar 找 editEvent、给 Event 塞 reminders: ReminderInfo[]——DevEco 满屏飘红。把 SDK 的 d.ts 从头翻到尾才发现:CalendarAccount 是 {name, type: CalendarType, displayName?},没有 accountType;editEvent 不在 Calendar 上,更新是 updateEvent;提醒字段叫 reminderTime,是 number[]。先 grep d.ts 再动手,是这一课的正确姿势:
// 在 SDK 目录 grep 教程 API
grep -n "CalendarMetadata\|editEvent\|ReminderInfo" \
/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/ets/api/@ohos.calendarManager.d.ts
# 结果:CalendarMetadata 零命中;editEvent 不在 Calendar 接口里;ReminderInfo 不存在
教程会过期,d.ts 不会。
坑二:源码 HAR 缺 module.json5,hvigor 直接罢工。 我以为 HAR 有 oh-package.json5 就够了,构建时报了一个非常笼统的错:
> hvigor ERROR: 00303195 Configuration Error
Error Message: Unable to obtain the module information at file:
.../device-calendar-test/harmony/calendar_har/src/main/module.json5
一开始还以为是 build-profile.json5 的 modules 注册写错了,翻来翻去才发现:HAR 模块也需要一个正经的 module.json5,至少要有 module.name 和 "type": "har"。补上之后这个错立刻消失。报错说"无法获取模块信息"的时候,先检查这个模块的 module.json5 是否存在且成形。
坑三:ArkTS 严格模式不认 JS 的"随手写"。 两个报错一起教育了我:
ERROR: 10605038 ArkTS Compiler Error
Object literal must correspond to some explicitly declared class or interface
(arkts-no-untyped-obj-literals) At File: .../CalendarBridgeImpl.ets:257:61
ERROR: 10505001 ArkTS Compiler Error
Conversion of type 'Record<string, string>' to type 'Error' may be a mistake
because neither type sufficiently overlaps with the other.
At File: .../CalendarBridgeImpl.ets:51:11
第一处是 JSON.stringify({ 'kind': 'added', 'data': { 'id': id } })——JS 里天经地义的字面量,ArkTS 要求先声明 Record<string, Object> 再塞;第二处是想抛一个带 code 的错误对象,Record 强转 Error 不行,老老实实 throw new Error(\${code}: ${message}`)`。从 JS 跨到 ArkTS,对象字面量的"自由"是要还的。
坑四:requestPermissionsFromUser 的返回形状和想象的不一样。 我按直觉写了 result.permissions.forEach(p => { if (p.granted) ... }),编译报错:
ERROR: 10505001 ArkTS Compiler Error
Property 'granted' does not exist on type 'string'.
At File: .../CalendarBridgeImpl.ets:122:15
报错把真相说得很直白:permissions 是权限名字符串数组,granted 这个字段根本不存在——真正的授权结果在平行的 authResults 数组里,authResults[i] === 0 才是用户点了允许。权限结果看 authResults,权限名看 permissions,两个数组按下标对齐。
坑五:增删改真机全成功,查询却返回 0 条。 这是全文最值钱的一个坑。第一轮真机验证的 hilog:
11-13 16:51:55.673 ... [PASS] addEvent | eventId=1 (11/13/2026, 5:51:55 PM)
11-13 16:51:55.685 ... [PASS] getEvents(区间查询) | 命中 0 条,首条: -
11-13 16:51:55.702 ... [FAIL] getEvent | code=undefined msg=ENOTFOUND: event not found: 1
写事件明明成功(addEvent 返回了 id),紧接着区间查询 0 条、单条查询 ENOTFOUND。一开始以为是 EventFilter.filterByTime 的区间参数有坑,后来才反应过来:事件写进了新建的"EOC测试日历"(id=2),而查询走的是缺省 getCalendar() 拿到的默认日历(Phone,id=1)——事件 id 全局唯一,日历实例不是。修复是把所有读改删操作统一改成 resolveCalendars():未指定日历就 getAllCalendars() 遍历合并。修复后第二轮真机 11 步全 PASS。
坑六:构建脚本不 cd 到工程根,hvigor 连配置都找不到。 用脚本跑构建时,工作目录停在 workspace 根:
> hvigor ERROR: 00304004 Not Found
Error Message: Hvigor config file
/Users/dijun/WorkBuddy/2026-11-13-16-14-02/hvigor/hvigor-config.json5 does not exist.
hvigor 以当前工作目录为工程根定位 hvigor/hvigor-config.json5。脚本里显式 cd <工程根> 后恢复正常。能手动跑通的构建,不等于脚本能跑通——CI 里每一级目录都要钉死。
7. 现在怎么用:从 三方库 到依赖
业务侧接入三步走:
# 1. 安装三方库(发布后)
npm install electron-ohos-calendar
# 2. 主进程直接用
# const ohosCalendar = require('electron-ohos-calendar')
# 3. 桌面开发调试
cd example && npm install && npm start # Mock 后端,UI 徽标显示"桌面降级"
鸿蒙端在 Electron-OHOS 宿主工程里补三件事:把 harmony/calendar_har 拷进壳工程并在根 build-profile.json5 的 modules 注册;壳工程 module.json5 声明 READ_CALENDAR/WRITE_CALENDAR(带 reason);承载 Electron 运行时的 UIAbility 里一行接线 registerCalendarBridge(this.context)。
真机验证工程的完整构建运行链(本仓库 device-calendar-test/):
# 构建(在工程根目录)
ohpm install
node $DEVECO/tools/hvigor/bin/hvigorw.js --mode module \
-p module=entry@default -p product=default assembleHap --no-daemon
# 安装启动(真机:显式指定设备)
hdc -t <序列号> install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc -t <序列号> shell aa start -a EntryAbility -b com.example.myapplication
总结:
这篇文章围绕 CPF-Electron 鸿蒙环境 对接
CalendarKit系统日历展开,核心痛点是鸿蒙日历能力归 ArkTS 管控,Electron 的 Node.js 本身没有直接访问入口,没有现成 NDK 绑定,需要自建桥接方案。
方案采用 Node-API + JSON 透传 的思路实现三方库 electron-ohos-calendar,JS 层统一 API 契约,鸿蒙端通过 NAPI 把调用转发给 ArkTS HAR,由 calendarManager 完成真实的系统日历读写;桌面端内置 Mock 实现,接口完全对齐,业务代码无需区分平台。库封装了权限探测、运行时弹窗授权、日历账号管理、日程增删改查、变更事件推送能力,同时适配 API 26 的 SDK 模型差异,对字段、枚举、过滤器做模型转换。
工程上做了分层解耦:JS 门面、NAPI 桥、ArkTS HAR、示例工程相互隔离,桥层只做 JSON 转发,不耦合业务逻辑,新增接口不用重新编译原生插件。权限采用两段式设计,先探测授权状态,再在用户交互时触发 requestPermissionsFromUser,遵循鸿蒙 user_grant 权限规范。同时整理了大量真机踩坑:线上教程的日历字段、接口签名在 API 26 已经失效,必须以 d.ts 为准;HAR 构建缺少 module.json5、ArkTS 严格类型不允许无约束字面量;权限结果存在 authResults 数组而非权限对象;以及构建脚本工作目录、桥注册时序等稳定性问题。
更多推荐

所有评论(0)