日历读写不是"调一个 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)
系统 APIHarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0)
hvigor6.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 桥——桥的每一端都要自己造。把它翻译成要做的事,一共三件:

  1. Kotlin 侧的门面:CmpCalendar 把 8 个日历操作收成 8 个 suspend 函数,业务层不碰 napi;
  2. napi 桥本体:Kotlin 用 napi_call_function 调 ArkTS 注册进来的回调,ArkTS 干完活把 JSON 打回来,按 id 唤醒挂起的协程;
  3. 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日历

这一页是整篇文章的验收标准:“日历账户 ● 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请求requestPermissionsFromUserread/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 三条工程边界

把"能跑"变成"能复用",边界钉在三条上:

  1. lib 不依赖页面:cmp-calendar 里没有 example 的任何引用,UI(CmpCalendarScreen)只是库附赠的默认实现,宿主可以只用 CmpCalendar 门面自己写 UI;
  2. napi 实现独立成层:ohosMain sourceSet 里的 NapiCalendarBridge 实现 commonMain 的 expect 接口,将来适配其他平台只要给新的 actual;
  3. 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 桥实现,上层业务代码基本不用改动。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐