React Native 鸿蒙日历打通实战:基于 CalendarKit 封装 TurboModule,六大业务场景写入系统日历,实现重复日程展开、批量写入、冲突空档计算
示例仓库:http://atomgit.com/dijun_520/react-native-ohos-calendar
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-RN/ohos_react_native/tree/0.84-main
CPF-RN 鸿蒙社区:https://atomgit.com/CPF-rn
0. 环境与实测设备
| 项目 | 版本 |
|---|---|
| 开发工具 | DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk) |
| 系统 API | HarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0) |
| React Native | 0.84.1 |
| RN 鸿蒙框架 | @react-native-oh/react-native-harmony 0.84.5(RNOH) |
| Node.js | ≥ 22.11.0 |
| 实测设备 | 华为(nova 14) |
1. “日历打通"不是"存到本地数据库”
我一开始也以为"日历打通"就是把日程往本地存一份:建张表,加几个字段,查询用 SQL,搞定。毕竟日历的本质不就是"标题 + 起止时间 + 提醒"吗?
结果第一批需求就把这个理解打穿了。产品要的六个场景里有两个很扎眼:一个是"农历生日,每年提前一天提醒",一个是"课程表 8 节课一次导入,还要告诉我跟已有日程冲不冲突"。自己存库意味着:农历换算自己写、重复规则自己展开、用户在系统日历 App 里改了日程自己感知不到、锁屏横幅提醒系统也不知道。这四件事,哪一件都不是一个小函数能兜住的。
打开华为的文档才看清全貌:系统里有一个所有应用共享的日历数据库(底层是 dataShare),@kit.CalendarKit 的 calendarManager 是三方应用能拿到的唯一入口。三方应用 getCalendar() 无参调用,拿到的永远是那一个系统默认日历——你不能自建日历账户,只能往系统那个账户里写。写进去的东西,系统日历 App 立刻可见;系统日历 App 改掉的,你也能读回来。
所以这个题目的边界很清楚:在 RN 里把 calendarManager 的读写能力封装成 TurboModule,写入系统默认日历而不是自己的数据库;重复日程的展开交给系统的 queryEventInstances(API 18+),农历换算完全交给系统;App 侧只做一层"实例 → 空档 → 冲突"的纯函数计算。
拆开来是三件事:
- 把权限、增删改查、批量写入、实例展开、账户信息封成一个 TS 层干净、ArkTS 层合规的 TurboModule;
- 用六个真实业务场景把 API 面全部压一遍(会议、站会、农历生日、出差、课程表、月度复盘),任何一个参数传错都能当场暴露;
- 把"冲突检测、空闲时段、重复展开"做成不依赖设备的纯函数,35 个断言在 Node 里跑过,再拿到模拟器上跟系统的展开结果对账。
开发过程中最典型的一条现场日志先埋在这里,第 6 节会回收它——它长得很无害,实际上是一次运行时翻车:
11-12 23:33:59.719 32107 32107 E A03D00/com.example.immersiveoverlays/JSAPP:
[RNCalendar] getEvents failed: 401, type error!
2. 效果展示

第一张图是 Demo 首页。这里每一行都不是装饰:「日历账户 Phone」来自 getAccountInfo(),它是 calendar.getAccount() 的返回——type=local 说明这就是系统本地默认日历,id=1 是日历数据库的自增主键;「可见日历 1 个」来自 getAllCalendars(),三方应用可见的确实只有这一个。下面六个场景就是压 API 面的六个"探针",每个都标了它覆盖的能力组合。


这两张图是同一个课程表的两种写法:逐条 8 次调用 56 ms(7.00 ms/条),批量 1 次调用 47 ms(5.88 ms/条)。

第四张图是智能排期:扫描未来 7 天,系统把重复规则展开成实例,纯函数算出每天被占多少分钟、还剩哪些 ≥60 分钟的空档。11-13 被农历生日(全天)占满 720 分钟,11-14/15 被出差占满,11-16 剩 10:00–14:00 这一段 240 分钟的空档——点"写入推荐空档",一场 90 分钟的"专注时间"就落进去,占用量当场从 180 变成 270 分钟。
坑的现场也留了底,因为它是这套功能里最典型的一类错误——算法没错,语义错了:

看 11-12 周四那一行:占 90 分 · 1 段,时间线的第一条是"专注时间 09:00–10:30"。这是深夜 23:13 点下按钮的结果——第一版推荐逻辑把"今天的空档"当成了可排期资源,写了一条已经过去的日程。这张截图跟修复后的第四张放在一起看:同一个算法,差两行代码,一个是功能,一个是事故。

第五张图是时间线:注意 11-16 周一,09:00 课程、09:30 站会、10:00 专注时间、14:00 课程按序排开,站会和每节课程都带 🔁——它们是同一条规则的多次出现,不是多条日程。
打通的另一端也要看:打开系统日历 App。

月视图上 13、14、16、17、18、19、20、23、24、25、26 都有红点,今天(12 号)没有——推荐空档被修到未来去了,这本身就是一次验证。

11-16 当天,四条日程全部在列,来源都是「RN日历Demo」。最有意思的是系统自己给三条日程标了橙色"冲突"徽标:课程 09:00–10:00 与站会 09:30–09:45 重叠、与专注时间 10:00–11:30 重叠。课程表是批量写入的,故意没做冲突预检——系统标出来的这三个"冲突",恰好和我们 planner.findConflicts 的算法互为印证。

11-13(农历十月初五):全天日程"妈妈生日(农历)"。写入时我只传了 isLunar: true 和一个公历时间戳,农历换算、"农历每年重复"的解释权全部在系统。这就是我说"农历不自己做"的底气。
3. 原理:三方应用的日历到底通向哪里
先给最重要的模型判断:三方应用没有"自己的日历",只有"系统默认日历的使用权"。
整个打通链路是这样的:
RN 应用 (JS/TS)
│ TurboModule(JSI/ArkTS 桥)
▼
RNCalendarModule(ArkTS,HAR 内)
│ @kit.CalendarKit / calendarManager
▼
系统日历数据库(dataShare,所有应用共享)
▲
│ 同一个默认日历账户
系统日历 App(月视图 / 日视图 / 锁屏提醒)
RN 写入的日程和系统日历 App 看到的是同一份数据。这不是"同步",是同一个账户下的同一行记录——所以第 2 节里系统日历的截图不需要任何同步动作,写入完成点开就有。
三方应用在这个模型下能干什么、不能干什么,用表格钉死:
| 能力 | 入口 | 三方应用的现实 |
|---|---|---|
| 拿日历对象 | getCalendarManager(context).getCalendar() | 无参调用,永远是系统默认日历 |
| 自建日历账户 | createCalendar(CalendarAccount) | 系统应用能力,三方不可用 |
| 写单条 | addEvent(Event): Promise<number> | 返回自增 ID |
| 写批量 | addEvents(Event[]): Promise<void> | 返回 void,没有 ID |
| 读(规则) | getEvents(filter?, keys?) | 只能读到自己写入的;三种 filter 一次只能用一种 |
| 读(实例) | queryEventInstances(start, end, ids?, keys?) | API 18+;重复规则由系统展开 |
| 改/删 | updateEvent / deleteEvent / deleteEvents | 静默完成,不拉系统页面 |
| 读全设备日程 | READ_WHOLE_CALENDAR | 系统应用权限,三方不可得 |
JS 侧的数据结构和 calendarManager.Event 的字段映射也值得摆出来——这是 spec(codegen 的输入)跟原生结构之间唯一的桥:
| JS(NativeRNCalendar.ts) | ArkTS / calendarManager | 说明 |
|---|---|---|
startTime / endTime | Event.startTime / endTime | 13 位毫秒时间戳;全天日程两端折算到当日 00:00 / 24:00 |
instanceStartTime / instanceEndTime | Event.instanceStartTime / instanceEndTime | 仅实例查询返回,API 18+ |
reminderMinutes: number[] | Event.reminderTime | 提前分钟数组,负数表示延后 |
recurrence | Event.recurrenceRule | 频率枚举在两侧都是 YEARLY/MONTHLY/WEEKLY/DAILY,JS 侧用字符串 |
isLunar | Event.isLunar | 农历换算完全由系统解释 |
location | Event.location | { location, longitude, latitude },JS 侧允许直接传字符串 |
id | Event.id | 数据库自增主键,只有 addEvent/updateEvent 场景有意义 |
权限这边同样有一张判定表——两道门各自怎么过:
| 阶段 | API | 判定依据 |
|---|---|---|
| 静默检查(进页面) | atManager.checkAccessToken(tokenId, permission) | 逐项等于 PERMISSION_GRANTED |
| 弹窗申请(用户点按钮) | atManager.requestPermissionsFromUser(context, permissions) | authResults 逐项为 0,且长度等于申请数 |
| module.json5 声明 | requestPermissions + usedScene | 没有 usedScene/reason,包都装不上 |
两个细节决定了后面所有的设计。
第一,规则和实例是两个东西。 一条"每周工作日 09:30 站会"在数据库里是一行,startTime/endTime 是整条规则的第一次;而用户和业务关心的"周三那天 09:30 有没有会",是规则被展开后的实例。系统给的答案是 queryEventInstances(start, end),展开后的每一次出现带独立的 instanceStartTime/instanceEndTime。这套东西 API 18 才有——这就是 compatibleSdkVersion 从 12 升到 18 的全部原因。18 以下的兜底是 JS 侧自己展开(planner.expandRecurrence),但有一个规则它展不了:农历。
第二,权限是两道门。 READ_CALENDAR / WRITE_CALENDAR 都是 user_grant:module.json5 里声明只是"报名",运行时还得 requestPermissionsFromUser 让用户点"允许"。而且不能只看弹窗结果数组叫什么——见 6.1 的坑。
4. 工程怎么搭
完整目录树(节选,带职责注释):
react-native-ohos-calendar/
├── package.json # harmony.codegenConfig 指向 spec,宿主 npm 安装后 codegen 能找到它
├── src/
│ ├── NativeRNCalendar.ts # TurboModule spec(codegen 的唯一输入)
│ ├── index.ts # 公共 API:Calendar 对象 + isSupported() 平台分支
│ ├── hooks/useCalendar.ts # 权限 → 查询 → 写入 → 自动刷新 的 React 封装
│ ├── planner.ts # 纯函数:冲突/空档/展开/汇总,不依赖 react-native
│ └── scenarios.ts # 六个业务场景的数据构造器,build(now) 产出待写日程
├── harmony/calendar/ # ArkTS HAR(三方库的原生侧)
│ ├── oh-package.json5 # name/version/main,dependencies 指向 RNOH har
│ ├── Index.ets # 导出 RNCalendarPackage
│ └── src/main/ets/
│ ├── RNCalendarPackage.ets # getUITurboModuleFactoryByNameMap 注册 'RNCalendar'
│ └── RNCalendarModule.ets # 全部原生实现(460 行)
├── test/planner.test.ts # 35 个断言,Node 里跑,不需要设备
└── example/
├── src/App.tsx # 全场景 Demo(五大卡片)
└── harmony/ # 完整鸿蒙壳工程(entry + 权限声明 + cpp 胶水 + 签名配置)
这次整理最关键的一条边界:planner.ts 一个 import react-native 都没有。它只定义自己的结构类型(CalendarEventLike / EventDraft),RN 侧的 RNCalendarEvent 传进来能直接结构匹配。
最小接入(三步,15 行):
import Calendar, { SCENARIOS, planner } from 'react-native-ohos-calendar';
// ① 探能力:非鸿蒙平台保持安全空态
if (!Calendar.isSupported()) return;
// ② 申请权限:声明在 module.json5 之外,还必须动态申请
const granted = await Calendar.requestCalendarPermissions();
// ③ 场景写入 + 实例读回
await Calendar.addEvents(SCENARIOS.find(s => s.key === 'courses')!.build(Date.now()));
const instances = await Calendar.queryInstances(from, to); // 系统展开后的每一次出现
通道协议这一侧没什么花活,0.84 的 C-API 架构下,方法表由 codegen 生成(example/harmony/entry/src/main/cpp/generated/RNCalendar.cpp):
// RNCalendar.cpp - RNCalendar()(codegen 生成,节选)
methodMap_ = {
ARK_ASYNC_METHOD_METADATA(requestCalendarPermissions, 0),
ARK_ASYNC_METHOD_METADATA(addEvent, 1),
ARK_ASYNC_METHOD_METADATA(addEvents, 1),
ARK_ASYNC_METHOD_METADATA(queryInstances, 3),
ARK_ASYNC_METHOD_METADATA(getAccountInfo, 0),
ARK_ASYNC_METHOD_METADATA(openSystemCalendar, 0),
// ... getEvents / findEventById / updateEvent / deleteEvent / deleteEvents
};
有一条协议上的细节值得单独说:spec 里 location?: string | RNCalendarLocation 这种联合类型,codegen 会把它降级成 location?: unknown(生成的 turboModules/RNCalendar.ts 里可以直接看到)。运行时不受影响——JS 侧传什么 ArkTS 收什么——但读取侧要把 unknown 当成 RNCalendarLocation | null 来窄化。
两个容易被忽略的窗口期:
权限未授时,所有读写都会 201。 Demo 的做法是挂载时先 checkCalendarPermissions(),未授权就把所有写入口灰掉,而不是让用户点完按钮再吃一个权限异常。
批量写入过程中页面刷新。 addEvents 是一次原生调用,JS 侧在 finally 里才刷新实例列表;中途的 loading 状态挡住重复点击。8 次逐条调用时这个窗口期被放大成 8 段,任何一段里用户再点一次都会重复导入——这也是"能批量就批量"的一个理由。
4.1 六个场景是怎么选出来的
场景不是拍脑袋凑的,每个都在 API 面上压一块别人压不到的地方:
| # | 场景 | 压的 API 面 | 预期暴露的问题 |
|---|---|---|---|
| 1 | 会议邀请入历 | 时区 timeZone + 经纬度 Location + 多段提醒 | 时区字段是否真的被系统解释;地点坐标回读 |
| 2 | 工作日站会 | WEEKLY + daysOfWeek[1..5] + count=20 | 重复规则展开、窗口边界截断(14 天窗口只展开 9 次) |
| 3 | 农历生日 | isLunar + YEARLY + isAllDay + reminder[1440] | 农历换算归属系统;全天 + 农历 + 每年的三重叠加 |
| 4 | 出差行程 | isAllDay 跨 3 天 | 全天日程的 23:59:59.999 边界折算 |
| 5 | 课程表批量导入 | addEvents 批量接口 8 条 | 无 ID 的代价;批量 vs 逐条的耗时结构 |
| 6 | 月度复盘 | MONTHLY + daysOfMonth[1] + count=12 | 月内无此日(如 2 月无 30 号)时系统的处理;窗口外日程的清理 |
场景数据全部产自 scenarios.ts 的纯函数,build(now) 传入"现在"返回待写日程。这一层不碰原生,所以"明天 10:00"“下周一”"每月 1 号"这些时间计算可以在 Node 里用固定时间戳回归:
// scenarios.ts - 场景 2:工作日站会(节选)
build(now: number) {
const start = atTime(addDays(startOfDay(now), 1), 9, 30); // 明天 09:30
return [{
title: STANDUP,
startTime: start,
endTime: start + 15 * 60 * 1000,
reminderMinutes: [5],
recurrence: {
recurrenceFrequency: 'WEEKLY',
daysOfWeek: [1, 2, 3, 4, 5], // 周一到周五
count: 20,
},
}];
}
4.2 useCalendar:把状态机收进一个 Hook
Demo 页面自己管状态,库给接入方的是 useCalendar——它内部维持五个状态(events / instances / account / loading / permission)和一条主循环:挂载时查权限,已授权就拉数据;写入或删除成功后自动 refresh;任何一次原生失败都会把 error 带出来、把权限状态重新校准。接入方要写的只剩业务事件本身。
一个刻意的设计:instances 不在 refresh 里自动拉。实例展开是重查询(窗口内规则越多、系统展开的次数越多),把它的触发权交给调用方(refreshInstances(from, to)),避免"改一条日程就全量展开"的浪费。
4.3 example 的鸿蒙壳工程
example/harmony 是一个能独立跑的完整工程,几个容易漏的文件:
AppScope/app.json5:bundleName必须跟签名 profile 一致,否则装不上;entry/src/main/module.json5:两条日历权限的声明 +reason字符串资源;entry/src/main/cpp/PackageProvider.cpp:注册RNOHGeneratedPackage——0.84 的 C-API 架构下 TurboModule 必须有 C++ 侧注册,漏掉的症状是 JS 侧getEnforcing直接抛"module not found";build-profile.json5:useNormalizedOHMUrl = false(0.84 实测,三方库源码 HAR 内部相对导入需要)。
5. 把代码讲透
5.1 权限:authResults 才是判决书
权限是所有调用的前置,也是第一个翻车的地方。第一版我按常见写法去取 result.granted,ArkTS 编译器直接报错——本机 SDK 的类型声明里 PermissionRequestResult 压根没有这个字段。翻文档才看清楚,可靠的判定字段是 authResults(number[],0 = PERMISSION_GRANTED):
// RNCalendarModule.ets - requestCalendarPermissions()(节选)
const result = await atManager.requestPermissionsFromUser(context, CALENDAR_PERMISSIONS);
// authResults: number[],0 = PERMISSION_GRANTED,全部为 0 才算授权完成
const authResults: number[] = result.authResults;
if (authResults.length !== CALENDAR_PERMISSIONS.length) {
return false;
}
for (const r of authResults) {
if (r !== 0) return false;
}
return true;
三个细节值得单独说:
第一,数组的长度也要验。 用户在弹窗上点了"仅允许一次"或者系统裁剪了权限,authResults 的长度可能跟申请数不一致,先比长度再逐项判 0。
第二,检查和申请是两条路。 已授权过的场景(二次进入)不该再弹窗,用 checkAccessToken(tokenId, permission) 逐项查状态;tokenId 从 getBundleInfoForSelf() 里拿。Demo 挂载时走的是"检查",只有用户点"申请权限"才走弹窗。
第三,权限失败要静默降级成 UI 状态。 原生层把所有异常吃掉返回 false,JS 侧把 permission 状态渲染成红色徽标,而不是让一个 201 报错炸穿整个页面。
5.2 批量写入:一次 IPC 和 47ms 的代价结构
课程表场景给了做对照实验的机会:同一份 8 条日程,两种写法各跑一次。
// App.tsx - runBatchCompare()(节选)
const t0 = Date.now();
if (mode === 'sequential') {
for (const draft of drafts) {
await Calendar.addEvent(draft); // 8 次 JS → 原生往返
}
} else {
await Calendar.addEvents(drafts); // 1 次 JS → 原生,内部走系统 addEvents
}
setBatchReport(`${mode === 'sequential' ? '逐条' : '批量'}:${drafts.length} 条 / ${Date.now() - t0} ms`);
模拟器实测:逐条 8 条 56 ms(7.00 ms/条),批量 47 ms(5.88 ms/条)。
先把测量方法说诚实:这是模拟器上的单轮采样,没做预热、没跑多轮取均值,13 ms 的差距里有一部分是抖动。但这个实验的结论本来就不依赖那 13 ms——两种写法调用的都是同一条系统接口,数据库该做的 8 次插入一次没少,量级判断(“桥开销每条 1 ms 左右”)在单轮数据上已经足够成立。要发表更严谨的数字,应该按 80 条 × 5 轮 × AB 交替再测一遍。
这里有一个很容易被误解的地方:差距不是"批量接口把 8 次插入合并成 1 次插入"——数据库该做的 8 次插入一次都没少。省下来的是 7 次 JS→原生的桥往返和 7 次 Promise 调度,摊到每条大约 1.1 ms。所以结论要诚实:8 条这个量级,批量省 16%,感知不大;但如果课程表是 80 条,桥开销线性放大。
5.3 实例展开:系统的 instanceStartTime 才是"那一次"
读日程有两个 API,对应两个完全不同的问题:
// RNCalendarModule.ets - queryInstances()(节选)
const events: calendarManager.Event[] =
await calendar.queryEventInstances(start, end, ids, INSTANCE_KEYS);
for (const event of events) {
const base: EventOutput = this.eventToJS(event);
const item: InstanceOutput = {
...base 的逐字段拷贝,
instanceStartTime: event.instanceStartTime ?? event.startTime,
instanceEndTime: event.instanceEndTime ?? event.endTime,
isRecurring: event.recurrenceRule !== undefined && event.recurrenceRule !== null,
};
}
getEvents 回答"我写过哪些规则",queryInstances 回答"这段时间里到底要忙几次"。一条 count: 20 的工作日站会规则,getEvents 永远只给你 1 条;queryInstances 在 14 天窗口里给你 9 次(周五起 9 个工作日)。
不能用 startTime 来判断"这一次是什么时候"——它是系列第一次的时间,一个每月 1 号的复盘,startTime 永远指向第一个月,哪怕现在是十个月以后。判断"那一次",只认 instanceStartTime。
JS 侧的兜底(planner.expandRecurrence)按"天"步进展开 DAILY/WEEKLY/MONTHLY/YEARLY,处理了 interval、count、expire、daysOfWeek/daysOfMonth/monthsOfYear 的组合:
// planner.ts - occurrenceStarts()(节选)
while (cursor.getTime() <= limit && guard < 4000) {
guard++; // 防御 count 缺失时的死循环
const dayTs = cursor.getTime();
const diffDays = Math.round((dayTs - seriesDay) / DAY_MS);
let hit = false;
switch (rule.recurrenceFrequency) {
case 'WEEKLY':
hit = Math.floor(diffDays / 7) % interval === 0
&& dows.indexOf(isoDayOfWeek(dayTs)) >= 0;
break;
// ... DAILY / MONTHLY / YEARLY
}
if (hit) {
matched++;
if (matched > maxCount) break; // count 从系列首日开始计
const occStart = dayTs + offset; // 保留首日的时分秒
if (occStart < to && occStart + duration > from) out.push(occStart);
}
cursor.setDate(cursor.getDate() + 1); // 按天步进,月末/闰年交给 Date 自己处理
}
两个实现细节:按"天"步进而不是按"规则周期"跳跃,是为了把月末、闰年这些边界交给 Date.setDate 自己消化,代价是 4000 次循环上限的防御;count 从系列首日起算——matched 在窗口起点之前就开始累计,否则 count=20 的规则在每个窗口里都会重新数 20 次。窗口是半开区间 [from, to),35 个断言里有 4 个专门钉这个边界(一个周四起的站会规则,7 天窗口里只有 4 个工作日,第 8 天不算)。
它的意义有两个:API 18 以下的设备兜底、以及单测里当对照组。
5.4 智能排期:先折算全天,再合并,再求差
空档推荐是纯函数,三步:
// planner.ts - planDays()(节选)
const dayInstances = instances.filter(x => x.start < windowEnd && x.end > windowStart);
const busy = dayInstances.map(x => ({
start: Math.max(x.start, windowStart),
end: Math.min(x.end, windowEnd),
}));
// mergeIntervals 合并重叠/相邻 → freeSlots 对 [windowStart, windowEnd] 求补集
三步里最值钱的是第一步之前的全天折算。全天日程在数据库里存的是"当日 00:00 ~ 当日 23:59:59.999",直接拿去求空档,会在 23:59:59.999 之后留出 1 毫秒的"空档"。eventInterval 把它折算成 [当日00:00, 次日00:00) 的半开区间——所以截图里 11-13、11-14、11-15 都显示"占 720 分 · 已排满",而不是"占 719 分 · 还剩 1 分钟空档"。
合并区间之后求补集,这个套路不新鲜,新鲜的是坑的位置。第一版推荐逻辑写完,深夜一测,"专注时间"被写到了今天 09:00——过去的空档也是空档。修法是两句:候选空档必须 end > now + 15min,起点必须 max(slot.start, now)。
冲突检测(findConflicts)跟空档共用同一套区间语言:
// planner.ts - findConflicts()(节选)
const cand: Interval = candidate.isAllDay
? { start: startOfDay(candidate.startTime), end: startOfDay(candidate.endTime) + DAY_MS }
: { start: candidate.startTime, end: candidate.endTime };
for (const event of events) {
const overlap = overlaps(eventInterval(event), cand); // min(end) - max(start)
if (overlap > 0) {
out.push({ existingId: event.id, ..., overlapMinutes: Math.round(overlap / MINUTE_MS) });
}
}
单测里专门压了"全天日程挡住中间某天的会议"这一条:出差是 14–16 号全天,12 号下午排个会不该报冲突,15 号排个会必须报——报出的重叠分钟数是 60。
5.5 拉起系统日历:打通闭环的最后一环
openSystemCalendar() 是最简单也最有说服力的一个方法:
// RNCalendarModule.ets - openSystemCalendar()(节选)
const want: Want = {
bundleName: SYSTEM_CALENDAR_BUNDLE, // com.huawei.hmos.calendar
abilityName: SYSTEM_CALENDAR_ABILITY, // MainAbility
};
await context.startAbility(want);
没有它,验证"写进去的东西系统看得见"只能靠开发者手动切 App;有了它,Demo 里一个按钮完成交叉验证。第 2 节那四张系统日历截图,就是这条链路的产物。它还顺便回答了一个产品问题:打通不是接管。三方应用能写、能读、能改、能删,但系统日历 App 的月视图、农历显示、冲突徽标、锁屏提醒。
6. 踩过的坑
坑一:ArkTS 不让 throw 任意类型,throw e 直接编译失败。 第一版错误处理写得很"TS":catch (err) { const e = err as BusinessError; throw e; }。hvigor 一跑,8 个错:
ERROR: 10605087 ArkTS Compiler Error
Error Message: "throw" statements cannot accept values of arbitrary types (arkts-limited-throw)
At File: RNCalendarModule.ets:419:7
COMPILE RESULT:FAIL {ERROR:8 WARN:157}
一开始以为是 BusinessError 类型不对,后来才反应过来:ArkTS 的 throw 只接受 Error 及其子类,as BusinessError 断言骗过了 TS 检查,骗不过 ArkTS 编译器。修复是把每个 throw e 改成 throw new Error(\addEvent failed: code=
e
.
c
o
d
e
,
m
e
s
s
a
g
e
=
{e.code}, message=
e.code,message={e.message}`)`,把错误码和消息塞进 message 里带给 JS。ArkTS 不是 TypeScript 加几个 lint,它是一 language mode,类型系统的规则更硬。
坑二:对象字面量必须"有所属",结构化类型赋值也被拦。 修完坑一又是 17 个错:
ERROR: 10605038 ArkTS Compiler Error
Error Message: Object literal must correspond to some explicitly declared class or interface
(arkts-no-untyped-obj-literals) At File: RNCalendarModule.ets:429:33
我给返回值单独定义了 RecurrenceOutput,字段跟 RecurrenceInput 一模一样,TS 里这是合法的(结构化类型),ArkTS 直接拒绝。最后的解法是删掉所有重复结构,让 EventOutput extends EventInput、返回值复用一套接口。在 ArkTS 里,“长得一样"不等于"是一个东西”,继承是唯一的桥。
坑三:getEvents() 不带过滤,运行时报 401。 这个坑藏得最深,编译期毫无症状。清空日程时调 Calendar.getEvents()(无参),hilog 里出现:
11-12 23:33:59.719 32107 32107 E .../JSAPP: [RNCalendar] getEvents failed: 401, type error!
d.ts 里明明写着 getEvents(eventFilter?: EventFilter, eventKey?)。排查了半小时才定位:显式传 calendar.getEvents(undefined, EVENT_KEYS),运行时的重载分派就乱了(第二个参数存在时,第一个 undefined 不被当作"省略")。修复是二元分支:没有 filter 就连第一个参数一起省掉,只调 calendar.getEvents()——代价是这种调用只返回系统默认字段(没有提醒、没有重复规则)。
坑四:queryEventInstances 要 API 18,compatibleSdkVersion 还停在 12。 给 spec 加实例展开前翻 d.ts,queryEventInstances 的注释里一行 @since 18 拦住了我——而 example 的 compatibleSdkVersion 是 5.0.0(12)。这个坑没有报错现场,因为它是被文档拦下的,但正因如此更值得写:编译器对 API 版本的检查有滞后性,等它报出来你已经浪费一轮构建。这次的解法干脆:example 的 compatibleSdkVersion 升到 5.1.0(18),同时把"低版本走 JS 展开"的兜底留给库的使用方。
坑五:推荐空档落在"今天 09:00",而现在是深夜。 纯函数算出的空档没有错——今天的 09:00–21:00 确实空着;错的是业务语义:过去时段不是可排期资源。真实现象是"专注时间"被写到了当天上午,日历上出现一条已经过去的日程。修复两句:s.end > now + 15 * MINUTE_MS 过滤掉已结束的时段,起点取 Math.max(slot.start, now)。
坑六:清空日程按"14 天窗口的实例"删,下个月的复盘删不掉。 月度复盘落在 12 月 1 号,永远在"未来 14 天"窗口外。第一版清空按钮按实例窗口收集 ID,点了之后月视图上红点全灭,但那条复盘还在。修复:清空走 getEvents() 全量拿 ID 再 deleteEvents(ids)。
坑七:codegen 把联合类型降级成 unknown。 spec 里 location?: string | RNCalendarLocation,生成文件里变成:
// generated/turboModules/RNCalendar.ts(codegen 产物,节选)
export type RNCalendarEventOptions = {
location?: unknown,
// ...
}
运行时没问题,但类型保护没了:读取侧拿到 location 得自己窄化成 RNCalendarLocation | null 再用。
坑八:模拟器对非重复日程也返回默认 recurrenceRule。 getEvents 读回的日程里,明明是单次的会议也带着 recurrenceFrequency: 'DAILY'。判断"是否真重复"不能只看读回来的字段,要以写入时是否传了 recurrence 为准,或者像本库一样,queryInstances 里用 isRecurring 显式带上系统侧的判断。
7. 现在怎么用:从 三方库 到 依赖
接入三步(宿主已接 RNOH 的前提下):
npm install react-native-ohos-calendar
// 根 oh-package.json5(harmony 侧)
{
"dependencies": {
"react-native-ohos-calendar": "file:../node_modules/react-native-ohos-calendar/harmony/calendar"
},
"overrides": {
"@rnoh/react-native-openharmony": "file:../node_modules/@react-native-oh/react-native-harmony/react_native_openharmony.har"
}
}
// entry/src/main/ets/RNPackagesFactory.ets
import { RNCalendarPackage } from 'react-native-ohos-calendar';
export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
return [new RNCalendarPackage(ctx)];
}
然后 npx react-native codegen-harmony 生成 C++ 胶水(PackageProvider.cpp 注册 RNOHGeneratedPackage),宿主 module.json5 声明两条权限,运行时调 requestCalendarPermissions()。完整步骤、含命令行构建与热加载,都在 example/RUN.md。
总结:
本文基于 RNOH 0.84 生态,封装了一套对接鸿蒙 CalendarKit 的 TurboModule 日历库,解决 RN 鸿蒙端系统日历打通的需求。方案没有自建本地日程表,而是直接接入系统共享的日历 DataShare 数据库,只能写入系统默认本地日历账户,依靠系统原生能力处理农历换算、重复日程规则、锁屏提醒与日程冲突标记,规避了自研日历逻辑的大量复杂度。
库对外提供权限管理、单条/批量写入、日程规则查询、重复实例展开、修改删除、拉起系统日历等完整能力,重点区分了 getEvents 查询原始规则和 queryEventInstances 展开实例这两个核心接口,实例展开依赖 API 18,低版本设备配套 JS 侧纯函数展开兜底。同时独立实现 planner 工具模块,在 Node 可单测的环境下完成日程冲突检测、空闲空档计算、时段合并,配套 35 条断言保障算法稳定,修复了空档推荐落入过去时间、全天日程边界计算异常等业务语义问题。
项目选用会议、工作日站会、农历生日、出差、课程表批量导入、月度复盘六大业务场景覆盖 API 能力,对比验证批量写入相比逐条调用可以减少 JS 与原生之间的桥往返开销,适合课程表这类批量导入场景。开发过程完整复盘 ArkTS 强类型限制、权限结果判定、getEvents 无参调用 401 报错、codegen 联合类型降级、模拟器返回异常重复字段等一系列典型坑点。
整套组件接入简单,支持在宿主 RNOH 工程中以 HAR 依赖方式引入,保留清晰的能力边界:不支持三方自建日历账户、无法读取其他应用写入的日程,适合业务在 RN 鸿蒙应用内把日程写入系统日历、做智能排期、冲突预判,为鸿蒙端 RN 日历类业务提供可直接复用的底层 TurboModule 方案。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐


所有评论(0)