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)
系统 APIHarmonyOS 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[]>;
}

三个细节立刻推翻了理解:

  1. 这套 API 只存在于 ArkTS 世界。 calendarManager 是 @kit.CalendarKit 的 ArkTS 模块,没有 NDK C 接口、没有给 Node.js 的 binding。Electron 主进程的 Node 再全能,也够不着它——中间隔着一条 JS → Node-API → ArkTS 的桥,这条桥要自己搭。
  2. 权限是 user_grant。 READ_CALENDAR / WRITE_CALENDAR 在 module.json5 里声明了不算数,必须运行时调 requestPermissionsFromUser,由用户在系统弹窗里点头。
  3. 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 → NAPICalendarBridgeImpl.callArkTS 侧实现已就绪,桥可以转发了
emitEvent(payloadJson)ArkTS → JS{kind, data, timestamp}变更通知:added/updated/removed/calendarChanged
requestPermissionsFromUser应用 → 系统权限名数组用户点没点允许(authResults[i] === 0)
EventFilter.filterByTime(start, end)应用 → 系统13 位毫秒时间戳区间区间内的事件列表

两个细节决定了后面所有的实现取舍:

  1. READ/WRITE_CALENDAR 是 user_grant 权限。 静态声明只是"申请资格",运行时必须走一次系统弹窗;已授权后再调 requestPermissionsFromUser 不弹框、直接返回 granted——所以"启动时探测 + 点击时申请"两步都要留。
  2. 事件 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 }

两个容易被忽略的窗口期:

  1. SetArkBridge 之前不能有 call 进来。 ArkTS 侧注册发生在宿主 UIAbility 就绪之后,而 Electron 主进程启动更早。桥的桌面对策是 fail fast:ArkTS 桥没注册,call 直接抛 “ark bridge not registered”,让问题在第一时间暴露,而不是把 undefined 悄悄传回业务层;
  2. 后端选择是惰性且一次性的。 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 数组而非权限对象;以及构建脚本工作目录、桥注册时序等稳定性问题。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐