CMP 鸿蒙日历读写实战:Compose 月历跨 Kotlin/C/ArkTS 桥接 CalendarKit,自建独立日历账户
日历读写不是"调一个 API 把事件存进去",是一次跨过三种语言的接力——Kotlin 侧的 Compose 月历、C API 头文件、ArkTS 侧的 CalendarKit,中间只有两条字符串通道。怎么把 CalendarKit 封装成一个 CMP(Compose Multiplatform)三方库、Kotlin 怎么调进 ArkTS 再等它回包、写入的日程怎么落到自己建的日历账户而不是别人的日历里、没有权限时数据又落到哪。
示例仓库:https://atomgit.com/dijun_520/cmp-calendar-ohos
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-KMP-CMP/kotlin/tree/main-2.2.21-OH
CMP 鸿蒙社区:https://atomgit.com/CPF-KMP-CMP
0. 环境与实测设备
| 项目 | 版本 |
|---|---|
| 开发工具 | DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk) |
| 系统 API | HarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0) |
| hvigor | 6.26.8(@ohos/hvigor-ohos-plugin) |
| KMP/CMP 工具链 | kotlin 2.2.21-1.2.0 / CMP 1.9.2-1.2.0 / skiko 0.9.22.2-1.2.0(CPF-KMP-CMP 社区发布版,ohosArm64 + ohosX64 双目标) |
| Node.js | ≥ 22.11.0 |
| 实测设备 | 华为(nova 14) |
1. “CMP 也有插件机制吧”
RN 有 TurboModule,Flutter 有 MethodChannel,那 CMP 做日历读写,无非也是"注册一个原生模块,JS/Kotlin 两边握手"。之前用 RN 做过一遍鸿蒙空间音频三方库,流程我都背得出来:TurboModuleManager 注册、JS 侧 NativeModules.XXX、ArkTS 侧继承 TurboModule。
我一开始也以为 CMP 是同一套逻辑——找个 registerPlugin 之类的口子,把 ArkTS 的实现挂进去就完事了。
// example/build.gradle.kts(节选)
kotlin {
listOf(ohosArm64(), ohosX64()).forEach { ohosTarget ->
ohosTarget.binaries.sharedLib {
baseName = "kn" // 整个 Compose 应用被编成一个 libkn.so
export(libs.compose.multiplatform.export)
linkerOpts("-lace_napi.z", "-lhilog_ndk.z", ...)
}
}
}
整个 Compose 应用被 Kotlin/Native 编译成一个 so 文件,DevEco 壳工程通过 CMake 把它链进来,ArkTS 侧 import { MainArkUIViewController } from 'libentry.so'——不是运行时注册,是编译期链接。Kotlin 和 ArkTS 之间没有现成的"模块系统",能走的路只有一条:Kotlin/Native 生成 C API 头文件(libkn_api.h),ArkTS 的 napi C++ 层调这些 C 符号。
"那我在库模块里写个 @CName 函数,头文件里不就有了?"结果:
$ grep -c CmpCalendarAttach example/build/bin/ohosArm64/debugShared/libkn_api.h
0
零。库模块里明明写了 @CName("CmpCalendarAttach"),头文件里就是没有。翻文档、翻示例、翻 CPF 社区的 issue,最后才在 Kotlin/Native 的行为里找到答案:@CName 的导出只覆盖"正在链接的那个模块",库模块作为 klib 依赖不参与头文件生成。
所以这个题目的边界很清楚:CMP 的"插件"不是一个运行时模块,而是一条把 libkn.so 和 ArkTS 缝起来的 napi 桥——桥的每一端都要自己造。把它翻译成要做的事,一共三件:
- Kotlin 侧的门面:
CmpCalendar把 8 个日历操作收成 8 个 suspend 函数,业务层不碰 napi; - napi 桥本体:Kotlin 用
napi_call_function调 ArkTS 注册进来的回调,ArkTS 干完活把 JSON 打回来,按 id 唤醒挂起的协程; - ArkTS 宿主:把
(id, op, argsJson)翻译成calendarManager调用,权限不够时降级到应用内存储。
2. 效果展示
2.1 模拟器:从"本地后端"到"系统后端"的完整降级链
应用启动,第一屏没有授权。注意顶部那颗状态芯片:

“本地日历 · 未授权 · 应用内日历 1 个”——这三行不是装饰:capability 探测发现没有日历权限,宿主把后端切成 local,数据落进 @kit.ArkData 的 preferences 里,月历上那颗红点是应用内存储里的日程。
点"申请权限",系统弹窗:

允许之后 UI 自动刷新,芯片直接变成:

“系统日历 · 读写均已授权”。这次 capability 重新探测,backendOf 按权限把后端切成了 system,后面的所有读写都走 CalendarKit。点"写入演示日程":

日志区给出完整链路:ensureCalendar → id=6(库专属日历"CMP日历")、addEvent → id=285 @ 2026-11-14 18:35。14 日那格的红点就是刚写进去的日程。
2.2 真机:日程真的落进了系统日历
真机上同样的流程,授权弹窗在真机上被别的应用抢过一次前台,最终授权成功:

“系统日历 · 读写均已授权 · 日历 4 个”——真机上系统里已经躺着 4 个日历账户,这是模拟器上看不到的场景。写入:

addEvent → id=288 @ 2026-11-14 18:35。同一屏日志里还能看到上一条 deleteEvent → id=287 已删除——287 是修复前写入的、落错了日历的那条(5.4 节的主角),删掉重写之后路由正确。
打开系统自带的日历 App,月视图里:

11 月 14 日下面,“CMP 日程演示 18:35 · 深圳 · 会议中心"出现在"Qt 跨端周会”"架构评审会"中间——CMP 应用写的日程和系统原生日程、别的应用的日程排在同一天的同一份列表里。

这一页是整篇文章的验收标准:“日历账户 ● CMP日历”(红色圆点,库建账户时指定的 #E53935)、“由 cmp-calendar-ohos 写入”。日程不是"存在某个私有角落",而是以一个独立日历账户的身份加入了系统日历的账户体系。
2.3 桥调用日志:一次写入背后的完整接力
把日志区放大看:

capability → 系统日历 · 读写均已授权
ensureCalendar → id=6(CMP日历)
addEvent → id=285 @ 2026-11-14 18:35
reloadMonth → 本月 1 条
每一次 UI 状态变化都对应一次桥往返:Kotlin 发出请求 → ArkTS 调 CalendarKit → JSON 回包 → 协程恢复 → Compose 状态更新。
3. 原理:一条请求、一条回包,日历能力是怎么跨过语言的
3.1 通道只有两条,协议只有一种
整个桥的物理形态简单得有点反直觉:两条单向通道,一种数据格式。
Kotlin (Compose) ArkTS (CalendarKit)
│ │
│ ① napi_call_function │
│ callback(id, op, argsJson) ──────► │ dispatch → calendarManager
│ │
│ ◄────── CmpCalendarResult(json) ── │ ② 回包(C 入口)
│ parseReply → resume 协程 │
▼ ▼
Compose 状态更新 Promise 完成
请求方向:Kotlin 拼好 {"title":..., "startTime":...} 这样的 JSON,和 id、op 一起作为三个字符串参数调 ArkTS 注册进来的 JS 函数。回包方向:ArkTS 把结果压成一行 JSON,调宿主导出的 C 入口 CmpCalendarResult,Kotlin 按 id 找到挂起的协程恢复它。
op 清单与 CalendarKit 的映射关系:
| op | 方向 | CalendarKit 对应调用 | 应用要回答什么 |
|---|---|---|---|
capability | 探测 | checkAccessTokenSync + getAllCalendars | 可用性 + 后端类型 + 权限位 |
requestPermissions | 请求 | requestPermissionsFromUser | read/write 两个布尔值 |
calendars | 读 | getAllCalendars | 日历账户列表 |
createCalendar | 写 | createCalendar(CalendarAccount) | 新日历的 id |
events | 读 | getEvents(EventFilter.filterByTime) | 事件数组 |
addEvent | 写 | calendar.addEvent(Event) | 事件 id |
updateEvent | 写 | calendar.updateEvent(Event) | 更新后的事件 |
deleteEvent | 写 | calendar.deleteEvent(id) | 空(异常即失败) |
表格后面说一段表格没写的东西:为什么全程只认字符串、不让 Kotlin 直接摸 napi 对象?因为 napi 的 JS 值生命周期管理(handle scope、reference、GC 时序)在 C 语义层就够复杂了,如果 Kotlin 还要按类型解析 napi_value,桥的每一行都会变成踩雷区。字符串协议把"语言边界"压缩成一个点:C++ 侧 napi_get_value_string_utf8 只取一次,Kotlin 侧 CmpJson.parse 只解一次。类型安全全部收在两端的模型层(Kotlin 的 CmpEvent.fromJson / ArkTS 的 eventFromNative)。
3.2 两个决定后续所有设计的细节
第一,CalendarKit 的日历实例是账号维度的,事件 id 是全局维度的。getAllCalendars() 返回的是账户列表,addEvent 要落在"某一个账户"上;但 deleteEvent(id) 删除时事件 id 全局唯一,Kotlin 侧拿着 id 不知道它在哪个账户,宿主只能遍历全部日历逐个找。
第二,READ/WRITE_CALENDAR 是 user_grant 权限。module.json5 里声明只是取得"可以弹窗"的资格,真正拿到权限要靠运行时 requestPermissionsFromUser,且 authResults[i] === 0 才算授权。权限状态变化不会推送通知,库只能在自己每次 capability 时重新探测——所以 UI 芯片上"本地日历→系统日历"的切换永远发生在授权回来之后的下一次刷新,不存在"权限变了 UI 还没变"的窗口,也不存在"权限没变 UI 自己变了"的窗口。
4. 工程怎么搭
4.1 目录树
cmp-calendar-ohos/
├── cmp-calendar/ # 三方库本体(KMP 库 + ArkTS HAR 源码)
│ ├── build.gradle.kts # ohosArm64/ohosX64 目标,仅产 KLIB
│ ├── src/commonMain/kotlin/com/cmp/calendar/
│ │ ├── CmpCalendar.kt # 门面:8 个 suspend 函数
│ │ ├── bridge/CmpCalendarBridge.kt # expect 接口 + parseReply
│ │ ├── json/CmpJson.kt # 迷你 JSON 编解码(~150 行)
│ │ ├── model/Models.kt # CmpEvent/Draft/Capability 等
│ │ ├── ui/CmpCalendarState.kt # Compose 状态持有者
│ │ ├── ui/CmpCalendarScreen.kt # Material3 月历 UI
│ │ └── util/CmpCalendarDate.kt # 纯 Kotlin 日期算法
│ ├── src/ohosMain/kotlin/com/cmp/calendar/
│ │ ├── bridge/NapiCalendarBridge.kt# napi 桥 actual 实现(核心)
│ │ └── util/Platform.ohos.kt # localtime_r / time
│ └── ohos/ # ArkTS 半边(源码 HAR)
│ └── src/main/ets/
│ ├── core/CmpCalendarHost.ets # op 分发 + CalendarKit 读写
│ ├── core/LocalCalendarStore.ets # preferences 降级存储
│ └── model/CmpEventModel.ets # Event ↔ JSON 翻译层
├── example/
│ ├── src/ohosMain/kotlin/com/cmp/calendar/example/
│ │ ├── CalendarBridgeEntry.kt # 宿主 @CName wrapper(8 行)
│ │ ├── MainArkUIViewController.kt # Compose 控制器入口
│ │ └── ExampleApp.kt # commonMain 示例 UI
│ ├── build.gradle.kts # 双 ABI publish 任务
│ └── harmonyApp/ # DevEco 壳工程
│ ├── entry/src/main/ets/pages/Index.ets # 三步接线
│ ├── entry/src/main/cpp/napi_init.cpp # C++ napi wrapper
│ ├── entry/src/main/cpp/types/libentry/Index.d.ts
│ └── cmp_calendar/ # rsync 自 cmp-calendar/ohos
├── scripts-sync-har.sh # 同步 ArkTS 半边到壳工程
├── scripts-build-hap.sh # 三步一条龙构建
└── README.md
4.2 三条工程边界
把"能跑"变成"能复用",边界钉在三条上:
- lib 不依赖页面:
cmp-calendar里没有 example 的任何引用,UI(CmpCalendarScreen)只是库附赠的默认实现,宿主可以只用CmpCalendar门面自己写 UI; - napi 实现独立成层:
ohosMainsourceSet 里的NapiCalendarBridge实现commonMain的expect接口,将来适配其他平台只要给新的actual; - example 只走公共 API:宿主壳工程只 import
CmpCalendarAttach/CmpCalendarResult两个 C 符号和CmpCalendarHost一个类,不碰库内部。
4.3 宿主接入的最小代码
ArkTS 侧接入一共三步,写在 Index.ets 里:
// example/harmonyApp/entry/src/main/ets/pages/Index.ets - aboutToAppear()
aboutToAppear(): void {
const context = getContext(this) as common.UIAbilityContext;
const host = new CmpCalendarHost(context); // 1. 建宿主(CalendarKit + 降级存储)
host.setReplySink((json: string): void => { // 2a. 回包通道指向 C 入口
CmpCalendarResult(json);
});
CmpCalendarAttach(host.handle); // 2b. 请求通道:把 JS 回调塞给 Kotlin
this.controller = MainArkUIViewController(); // 3. 创建 Compose 控制器
}
CmpCalendarAttach / CmpCalendarResult 是 libentry.so 的 C 符号(声明在 Index.d.ts),MainArkUIViewController 是 CPF 工具链的标准入口。顺序有讲究:attach 必须发生在创建控制器之前——Compose 首帧的 LaunchedEffect 会立刻发 capability,如果这时桥还没 attach,第一批请求会全部拿到 ENOBRIDGE 异常。
4.4 通道协议
一次"写入日程"的完整报文(有删节):
// 请求(Kotlin → ArkTS,三个字符串参数)
id = "3"
op = "addEvent"
args = {"title":"CMP 日程演示","startTime":1763104500000,"endTime":1763108100000,
"location":"深圳 · 会议中心","description":"由 cmp-calendar-ohos 写入",
"reminders":[15],"calendarId":6}
// 回包(ArkTS → Kotlin,一个字符串参数)
{"id":"3","ok":true,"data":{"id":288}}
// 失败回包
{"id":"4","ok":false,"error":{"code":"ENOCALENDAR","message":"calendar not found: 999"}}
两个容易被忽略的窗口期,库的处理方式:
- 回包先于 pending 登记?不可能——
pending[id]在send()之前登记,而send()是同步的napi_call_function,JS 回调只会在这之后触发; - 回包找不到 id?
deliverCalendarResult里pending.remove(id) ?: return,直接丢弃,不崩桥——比如宿主重建后旧请求的回包(reply sink missing时宿主侧也会打 warn 丢弃)。
5. 把代码讲透
5.1 attach:napi_ref 才是活回调
桥最容易被想当然的地方是"存个函数引用"。JS 函数不能裸存——napi 的 JS 值在 handle scope 出了作用域就可能被 GC 收走,跨作用域持有的只有 napi_ref:
// cmp-calendar/src/ohosMain/kotlin/com/cmp/calendar/bridge/NapiCalendarBridge.kt - attachCalendarBridge()
@OptIn(ExperimentalForeignApi::class)
fun attachCalendarBridge(env: napi_env?, callback: napi_value?) {
if (env == null || callback == null) return
memScoped {
val ref = alloc<napi_refVar>()
val status: napi_status = napi_create_reference(env, callback, 1u, ref.ptr)
if (status == 0u) {
NapiBridgeState.env = env
NapiBridgeState.callback = ref.value
NapiBridgeState.attached = true
}
}
}
三个细节值得单独说:
第一,napi_status 在这个 klib 里是 UInt,不是枚举。我下意识写了 status == napi_status.napi_ok,编译器直接打脸——napi_ok 不存在,正确的判断是 status == 0u。cinterop 生成的类型和 C 头文件里的枚举不一定长成文档里那样。
第二,引用计数传 1。napi_create_reference 的第三个参数是初始引用计数,传 1 意味着这个回调在整个应用生命周期内不会被回收——桥是单例的,回调也该是单例的。
第三,Kotlin String 直接喂 napi_create_string_utf8。按 C 的直觉应该先转 cstr.ptr,实际上这个 klib 的签名接受 Kotlin String,传了反而多拷一次。
5.2 call:suspendCancellableCoroutine 把 JS 回调变 suspend
门面的 8 个方法全是 suspend,异步怎么回来?答案是挂起在 suspendCancellableCoroutine 上,等回包按 id 唤醒:
// NapiCalendarBridge.kt - NapiCalendarBridge.call()(节选)
override suspend fun call(op: String, args: Map<String, Any?>): Map<String, Any?> {
val reply = suspendCancellableCoroutine<String> { continuation ->
if (!attached) {
continuation.resumeWithException(
CmpCalendarException("ENOBRIDGE", "宿主还没调用 CmpCalendarAttach,桥未就绪"))
return@suspendCancellableCoroutine
}
val id = (NapiBridgeState.nextRequestId++).toString()
NapiBridgeState.pending[id] = { json -> continuation.resume(json) }
val sent = send(id, op, CmpJson.stringify(args))
if (!sent) { // napi 调用失败要立刻摘除登记
NapiBridgeState.pending.remove(id)
continuation.resumeWithException(
CmpCalendarException("ENAPI", "napi_call_function 调用宿主回调失败(op=$op)"))
}
}
return parseReply(reply) // {"ok":true,"data"} / {"ok":false,"error"}
}
send() 本体是教科书式的 napi 五步:开 handle scope → 取 reference 值 → 取 undefined 作 this → allocArrayOf 三个字符串参数 → napi_call_function:
// NapiCalendarBridge.kt - send()(节选)
val argv = allocArrayOf(
stringValue(env, id),
stringValue(env, op),
stringValue(env, payload),
)
val status: napi_status = napi_call_function(env, undefined.value, function.value, 3uL, argv, result.ptr)
napi_close_handle_scope(env, scope.value)
status == 0u
一个反直觉陷阱:“send 成功"不等于"请求送达业务”。napi_call_function 返回 0 只说明 JS 函数被调到了,宿主 handle 里 JSON.parse 失败照样回 EBADJSON。所以桥不做二次确认,成败全部由回包的 ok 字段裁决——失败路径统一走 CmpCalendarException(code, message),UI 层拿到的永远是一个可显示的错误对象。
5.3 dispatch:一条 JSON 协议翻译成 CalendarKit
ArkTS 半边的核心是 60 行的分发器。它不认识 Compose、不认识 napi,只认识 (id, op, argsJson):
// cmp-calendar/ohos/src/main/ets/core/CmpCalendarHost.ets - handle / reply(节选)
handle = (id: string, op: string, argsJson: string): void => {
let args: Record<string, Object> = {};
try {
args = argsJson.length > 0 ? JSON.parse(argsJson) as Record<string, Object> : {};
} catch (err) {
this.reply(id, false, 'EBADJSON', `参数不是合法 JSON: ${argsJson}`);
return;
}
this.dispatch(op, args)
.then((data: Record<string, Object>) => this.reply(id, true, '', data))
.catch((err: Error) => {
// 约定:错误消息形如 "CODE: detail",拆开还原成结构化错误
const index = err.message.indexOf(':');
const code = index > 0 ? err.message.substring(0, index) : 'EUNKNOWN';
this.reply(id, false, code, err.message.substring(index + 1).trim());
});
};
SDK 的真实形状只在一个文件里处理——CmpEventModel.ets 翻译层:
// CmpEventModel.ets - eventToNative()(节选)
export function eventToNative(args: Record<string, Object>): calendarManager.Event {
const event: calendarManager.Event = {
type: calendarManager.EventType.NORMAL, // 必填!缺了直接抛参数错误
title: (args.title as string) ?? '',
startTime: args.startTime as number,
endTime: args.endTime as number,
isAllDay: (args.isAllDay as boolean) ?? false,
description: (args.description as string) ?? ''
};
const location = args.location as string | undefined;
if (location !== undefined && location.length > 0) {
const loc: calendarManager.Location = { 'location': location }; // location 是对象,不是字符串
event.location = loc;
}
...
}
三个 SDK 的"暗坑"全在这一屏:Event.type 必填且只能是 NORMAL(意图是留类型扩展位,实际是给三方库挖的第一个坑);location 不是 string 而是 Location 对象;提醒不是 reminders 而是 reminderTime: number[]。协议层用扁平 JSON,SDK 形状全部关在翻译层里——这一层决定三方库能不能在 CalendarKit 升级时只改一个文件。
5.4 日历路由:不指定 calendarId 会落进别人的日历
这是整篇文章最值钱的一段。真机上第一次写入成功后,我打开系统日历一看:日程在,但"日历账户"显示的是别人的账户,系统还贴心地标注"由 label 创建"。看 hilog 才反应过来——宿主 addEvent 里没给 calendarId 时走的是兜底逻辑:
// 修复前的坑:calendarId 缺省时取 getAllCalendars()[0]
const calendars = await this.resolveCalendars(undefined); // 遍历全部日历
const id = await calendars[0].addEvent(event); // 落进第一个——可能是别人的
模拟器上只有一个日历账户,[0] 恰好就是它,怎么写都对;真机上有 4 个账户,[0] 是遍历顺序里的第一个,日程就写进了别的应用的日历。
修复分两侧。Kotlin 侧,CmpEventDraft 增加 calendarId 字段,写入前先确保库专属日历存在:
// cmp-calendar/src/commonMain/kotlin/com/cmp/calendar/ui/CmpCalendarState.kt - ensureCalendar()
suspend fun ensureCalendar(): Int? {
val known = capability.calendars.firstOrNull { it.name == CmpCalendar.DEFAULT_CALENDAR_NAME }
if (known != null) return known.id // 已存在直接复用
if (capability.backend != CmpBackend.SYSTEM) return null // 本地后端无 id 概念
val calendar = client.createCalendar(CmpCalendar.DEFAULT_CALENDAR_NAME)
return calendar.id // 建完立刻拿 id
}
ArkTS 侧,resolveCalendars 尊重显式 id:
// CmpCalendarHost.ets - resolveCalendars()(节选)
private async resolveCalendars(calendarId: number | undefined): Promise<calendarManager.Calendar[]> {
const all = await mgr.getAllCalendars();
if (calendarId !== undefined && Number.isFinite(calendarId)) {
const target = all.find((c: calendarManager.Calendar) => c.id === calendarId);
if (target === undefined) {
this.fail('ENOCALENDAR', `calendar not found: ${calendarId}`);
}
return [target as calendarManager.Calendar]; // 显式路由:只写进指定账户
}
return all; // 仅查询/删除时才遍历
}
修复后的链路:ensureCalendar → id=6(复用已存在的"CMP日历")→ addEvent(calendarId=6) → 详情页"日历账户 ● CMP日历"。
5.5 双后端降级:没有权限时数据落在哪
backendOf 一行决定后端:有 calendarManager 且任一权限到位 → system;否则 → local。local 后端是 @kit.ArkData preferences 上的一个薄实现:
// cmp-calendar/ohos/src/main/ets/core/LocalCalendarStore.ets(节选,行为描述)
// - 应用内日历 id 从 1001 起,避免和系统日历 id 空间混淆
// - listCalendars / createCalendar / query / add / update / remove
// 与系统后端同形,返回的都是 CmpCalendarRecord / CmpEventRecord
这套降级的意义在第 2.1 节的截图里已经演示过了:未授权状态下应用照样能完整演示增删改查,权限到位后数据源无缝切换到系统日历。有一个诚实的边界要说清楚:local 存的日程不会迁移到 system 后端——授权之后 preferences 里的旧数据还在应用内,系统日历里是空的,两种后端的数据不做合并。这是刻意为之:跨后端迁移涉及 id 冲突和去重,收益撑不起复杂度,库在 capability 的 note 字段里把这件事明说给 UI 层。
还有一处纯 Kotlin 的题外功夫:日期算法。月历要算"这个月几天"“某日是星期几”“本地时区偏移”,这些在 commonMain 里不能依赖 java.time 也不能依赖平台 API,库里手写了 Hinnant 的 civil-from-days 算法(纯整数运算,无舍入误差),时区偏移走 ohosMain 的 localtime_r 的 tm_gmtoff。
6. 踩坑与经验
坑 1:库模块的 @CName 不会出现在宿主头文件里。 这是第 1 节埋下的那个"零"。我把 attachCalendarBridge 写进库模块并加了 @CName("CmpCalendarAttach"),构建一切正常,宿主链接却在 C++ 层报符号找不到:
// CMake 链接阶段
ld.lld: error: undefined symbol: CmpCalendarAttach(void*, void*)
>>> referenced by napi_init.cpp:88
回去 grep 生成的 libkn_api.h:
$ grep -c CmpCalendarAttach build/bin/ohosArm64/debugShared/libkn_api.h
0
排查过程:先怀疑 export(project(":cmp-calendar")) 没生效,改了两天 Gradle;后来才反应过来问题不在构建配置——@CName 的 C 导出只覆盖"正在链接的那个模块",库模块作为 klib 依赖不参与头文件生成。修复:库里的入口改成普通 Kotlin 函数,宿主用 8 行 @CName wrapper 导出:
// example/src/ohosMain/kotlin/com/cmp/calendar/example/CalendarBridgeEntry.kt
@OptIn(ExperimentalForeignApi::class, ExperimentalNativeApi::class)
@CName("CmpCalendarAttach")
fun hostCalendarAttach(env: napi_env?, callback: napi_value?) {
attachCalendarBridge(env, callback)
}
这 8 行是接入新宿主时要复制的最小代码,不是可以省掉的胶水。
坑 2:cinterop 类型别名不是 C 原味的。 写 send() 时我按 C 头文件的印象用 napi_value__、napi_ref__、napi_handle_scope__,编译器连环报 unresolved:
error: unresolved reference: napi_value__
error: unresolved reference: napi_handle_scope__
翻开 ArkTS_Napi_NativeModule 的 klib 才看到,cinterop 给这些裸指针结构准备了类型别名:napi_valueVar / napi_refVar / napi_handle_scopeVar,配合 alloc<napi_valueVar>() + out.value 使用。klib 里的类型名以 Var 结尾做可空指针盒子,C 头文件里的记忆全部作废。
坑 3:localtime_r 的 time_t 不能直接 alloc 赋值。 取时区偏移时写了 alloc<time_tVar>(value),报错:
error: none of the following functions is applicable:
inline fun <reified T : CPointed> MemScope.alloc(): T
alloc 不带参,time_t 在 64 位目标上是 Long 的别名但类型系统里不是一回事。正确写法是 alloc<LongVar>() 后给 .value 赋值再传 .ptr。Kotlin/Native 的 cinterop 类型不能按 Kotlin 基本类型的直觉初始化。
坑 4:C++ 侧 napi_get_value_string_utf8 的 const 限定符。 宿主 napi_init.cpp 里收请求参数:
// 编译报错(CMake/ninja 输出)
error: no matching function ... argument of type 'char*' is incompatible
with parameter of type 'const char*' (buffer.data())
std::string::data() 返回 const 指针,写进去要用 &buffer[0](保证非空时合法)。napi 的 C++ wrapper 对 const 比手写 C 严格,data() 只能读。
坑 5:ArkTS 严格模式的对象字面量。 capability() 返回值里塞权限对象,hvigor 直接拦截:
Error Code:00305010 ...
ArkTS:ERROR File: .../core/CmpCalendarHost.ets:168
[arkts-no-untyped-obj-literals] Object literals must correspond to some explicitly
declared class or interface (arkts-no-untyped-obj-literals)
ArkTS 不允许无类型的对象字面量,修复是显式转型:'permissions': perms as Object,接收侧 as Record<string, Object>。ArkTS 的结构化写法比 TS 严格一个量级,lint 报错在 stacktrace 里,不在第一屏。
坑 6:模拟器装不上——签名信息不一致。 改完代码重装:
install bundle failed: {'result':9568332}
install sign info inconsistent with installed
设备上已经装过一个用不同签名材料签的同 bundleName 包。hdc uninstall com.example.myapplication 后重装即好。同一 bundleName 换签名必卸载重装,这不是构建问题,是设备状态问题。
坑 7:真机权限弹窗被抢前台,授权"悄悄失败"。 真机点了"允许",hilog 里却是:
I A0CA1E/com.example.myapplication/CmpCalendar: permission result read=false write=false
排查发现设备上有个 demo 应用反复抢前台,弹窗刚弹出就被取消。最后绕过 UI 直接用 accessTokenId 授权验证链路:
# token 从 bm dump -n 的 accessTokenId 字段取
hdc shell atm perm -g -i 537735846 -p ohos.permission.READ_CALENDAR
hdc shell atm perm -g -i 537735846 -p ohos.permission.WRITE_CALENDAR
弹窗结果以 hilog 的 authResults 为准,UI 上看到"允许"被点击不代表授权成功。
7. 现在怎么用:从 三方库 到依赖
7.1 接入
仓库目前以源码形式发布(与 CPF 系列三方库一致),宿主工程三步接入:
# 1. 拷贝 cmp-calendar/ 到你的工程根目录,settings.gradle.kts 里 include ":cmp-calendar"
# 2. ArkTS 半边:把 cmp-calendar/ohos/ 同步进壳工程(或直接复制目录)
./scripts-sync-har.sh # rsync cmp-calendar/ohos → example/harmonyApp/cmp_calendar
# 3. 一条龙构建:KMP 双 ABI → so/头文件同步 → hvigor 打 hap
./scripts-build-hap.sh
oh-package.json5 里引用 ArkTS 半边:
// entry/oh-package.json5
"dependencies": {
"cmp_calendar": "file:../cmp_calendar"
}
签名材料不该进仓库:DevEco 里勾 Automatically generate signature,或像本仓库一样指向 ~/.ohos/config/ 下的本地材料(绑定 bundleName com.example.myapplication,换 bundleName 必须换材料)。
总结:
本文完整落地了一套面向鸿蒙 API26 的 CMP(Compose Multiplatform)系统日历读写三方库
cmp-calendar-ohos,打破了很多开发者默认的认知:CMP 在鸿蒙侧并不具备 RN TurboModule、Flutter MethodChannel 那种开箱即用的原生插件注册机制,整个跨语言调用链路需要自行搭建 napi 桥。CMP 工程会把 Compose 业务编译为单一libkn.so,依靠编译期链接而非运行时模块注册,Kotlin、C/C++、ArkTS 之间没有原生的对象互通能力,只能依靠JSON字符串作为唯一的传输协议,用id匹配请求和回包,结合协程挂起恢复机制,把底层同步的 napi 调用封装成上层友好的 suspend 异步接口,给 Compose 业务层屏蔽所有 napi 句柄、GC、生命周期、句柄域的复杂管理。
整套方案设计上做了分层解耦:KMP 公共层提供平台无关的日历模型、JSON 编解码、月历日期计算逻辑,以及统一的 CmpCalendar 门面,对外暴露增删改查、权限探测、日历账户管理 8 个能力;鸿蒙平台层分为两部分,一边是 Kotlin/Native 实现的 napi 桥,负责组装请求、发起调用、接收回包、唤醒协程,另一边是 ArkTS HAR 宿主,封装 CalendarKit 系统能力,承担参数翻译、系统日历账户操作、权限判断,同时实现一套基于 @kit.ArkData Preferences 的本地降级存储。权限未授予时,库自动切到本地后端,保持月历增删改查能力可用;拿到读写权限后无缝切换到系统日历后端,两套后端接口对齐,但数据相互独立,不会自动迁移,规避了跨数据源合并带来的 id 冲突、去重等复杂问题。
在系统日历账户的核心逻辑上,文章重点解决了模拟器和真机行为不一致的经典坑点:模拟器通常只有单个日历账户,不指定 calendarId 写入时看起来一切正常,但真机往往存在多个应用创建的日历账户,直接取列表第一项写入,会把日程误写入其他应用的日历账户。最终方案强制写入流程显式绑定目标日历 ID,在写入前先探测并创建属于本库的独立专属日历账户,让日程归属清晰,在系统日历 App 里可以独立区分、展示自定义名称与颜色,真正做到业务日程属于自己的日历账户,而不是依附系统默认或第三方应用账户。
开发过程中踩了大量 Kotlin/Native cinterop、napi、ArkTS 严格语法、鸿蒙系统权限体系独有的陷阱:@CName 符号仅在当前链接模块导出,klib 依赖里的导出函数不会进入宿主头文件,必须额外写一层宿主侧的包装函数;cinterop 自动生成的类型和原生 C 头命名有差异,napi_refVar、napi_valueVar 这类带 Var 后缀的盒子类型容易混淆;localtime_r、napi 字符串接口、ArkTS 无类型对象字面量校验、签名冲突重装、权限弹窗被前台抢占导致静默授权失败等问题,都属于模拟器无法复现、真机才会暴露的隐性问题。
这套桥接模板不止服务于日历场景,具备通用性:固定的 id + op + argsJson 字符串协议、挂起协程的请求管理、napi_ref 持久化回调、前后端降级切换的思路,可以复用在其他需要 CMP 调用鸿蒙系统 Kit 的场景,比如相册、通知、联系人等系统能力封装。同时库本身保持了良好的可复用边界,UI 组件是可选附赠,业务方可以只依赖核心门面,自行实现 Compose 月历界面;平台层使用 expect/actual 隔离,未来如果 CMP 拓展到其他平台,只需要新增对应平台的 actual 桥实现,上层业务代码基本不用改动。
更多推荐


所有评论(0)