本文以真实的开发过程为主线,完整记录如何基于鸿蒙 Calendar Kit 从零实现一个 Flutter 日历插件
ohos_calendar_kit(目标 API 26),并在华为 Mate 60 Pro 真机上全链路验证通过。文中所有代码均来自实际可运行的工程,配有真机截图,技术小白也能跟着一步步做出来。
一、生态背景:为什么需要这个插件
1.1 Flutter 与鸿蒙的"桥"
Flutter 是 Google 推出的跨平台 UI 框架,一份 Dart 代码可以同时跑在 Android 和 iOS 上。但 HarmonyOS(鸿蒙)并不在 Flutter 官方支持的平台列表里——官方只维护 Android、iOS、Web、Windows、macOS、Linux。
为了让 Flutter 应用能跑在鸿蒙上,社区出现了 Flutter OH(flutter_flutter 的 ohos 分支):它把 Flutter 引擎移植到了 OpenHarmony 上,让 flutter run 可以直接把应用装进鸿蒙手机。
但是光有引擎还不够。Flutter 应用调用手机的原生能力(蓝牙、日历、相机……)都要靠插件。每个插件都要为每个平台分别写一份"原生实现":
Flutter (Dart) ──MethodChannel──> 原生代码
├── android/ (Kotlin/Java)
├── ios/ (Swift/OC)
└── ohos/ (ArkTS) ← 需要我们自己写
一个插件如果没有 ohos/ 目录,在鸿蒙手机上调用它就会直接报 NotImplemented。这就是"三方库鸿蒙化"的意义:给每个流行的 Flutter 插件补上鸿蒙那一侧的原生实现。
1.2 为什么选日历
日历是一个非常典型的"系统能力"场景:
- 每台手机都有系统日历,用户在这里管理日程;
- App 经常需要往系统日历里写提醒(还款日、会议、纪念日),到期系统会自动弹通知,不需要 App 保活;
- 鸿蒙提供了官方的 Calendar Kit(
@kit.CalendarKit),把日历的读写能力以安全的方式开放给三方应用。
而 Flutter 生态里流行的日历插件(如 device_calendar)都只有 Android/iOS 实现,没有鸿蒙版。于是我们自己动手写一个。
1.3 认识 Calendar Kit
Calendar Kit 是鸿蒙系统服务 kit 之一,核心对象关系如下:
Context (UIAbility 上下文)
└── calendarManager.getCalendarManager(context) ← 入口:拿到管理器
└── CalendarManager ← 管日历"账户"
└── Calendar ← 管日历"日程"
├── addEvent() 创建日程
├── updateEvent() 更新日程
├── deleteEvent() 删除日程
├── getEvents() 查询日程
└── openEventEditPage() 跳转系统编辑页
| 概念 | 类比 | 说明 |
|---|---|---|
CalendarManager |
通讯录管理器 | 负责创建/获取日历账户 |
Calendar(账户) |
通讯录里的一个分组 | 系统默认账户,或 App 自己创建的账户 |
Event(日程) |
联系人 | 一条具体的日程:标题、时间、提醒、重复规则 |
使用 Calendar Kit 有两个前提条件:
- 声明权限:在
module.json5里声明ohos.permission.READ_CALENDAR和ohos.permission.WRITE_CALENDAR(都是 user_grant 权限,需要用户弹窗授权); - 动态申请:运行时调用
requestPermissionsFromUser弹出授权框,用户同意后才能真正读写。
本文的目标 SDK 为 API 26(HarmonyOS 26.0.0 / OpenHarmony 7.0 Release),所有 API 均以 26 的 SDK 头文件(
.d.ts)为准。
二、开发过程总览
整个插件的开发分为五个阶段,本文按此展开:
| 阶段 | 内容 | 产出 |
|---|---|---|
| ① 工程创建 | 用 Flutter OH 工具链生成插件骨架 | flutter create --template=plugin --platforms=ohos |
| ② Dart 层设计 | 定义跨端 API 与数据模型 | lib/ 下 4 个 Dart 文件 |
| ③ ArkTS 原生实现 | 对接 Calendar Kit | ohos/ 下插件主类 |
| ④ 真机调试 | 构建→安装→自动化点按→日志分析 | 发现并修复 2 个关键 Bug |
| ⑤ 文档与发布 | 双语 README、CHANGELOG、发布 pub.dev | 仓库 + tag 0.0.1-ohos-1.0.0-beta.1 |
2.1 测试环境
| 项目 | 版本 | 获取方式 |
|---|---|---|
| Flutter | 3.47.9-ohos-1.0.0(oh-3.47-dev) | flutter --version |
| Dart | 3.13.4 | 同上 |
| HarmonyOS SDK | 26.0.0(API 26) | DevEco Studio 内置 SDK |
| DevEco Studio | 26.0.0(6.x) | 关于页面 |
| 真机 | HUAWEI Mate 60 Pro(ALN-AL00) | hdc list targets |
| 设备 ROM | OpenHarmony 7.0.0.111(API 26) | hdc shell param get const.product.software.version |
2.2 最终目录结构
ohos_calendar_kit/
├── lib/ # Dart 层(给 Flutter 开发者用的 API)
│ ├── ohos_calendar_kit.dart # 对外 API:FlutterCalendarKit 类
│ ├── models.dart # 数据模型与统一导出
│ ├── ohos_calendar_kit_platform_interface.dart
│ └── ohos_calendar_kit_method_channel.dart # MethodChannel 实现
├── ohos/ # ArkTS 层(鸿蒙原生实现)
│ ├── src/main/ets/components/plugin/
│ │ └── FlutterCalendarKitPlugin.ets # 插件主类(本次核心)
│ ├── src/main/module.json5 # HAR 模块配置
│ ├── index.ets # 模块入口
│ └── oh-package.json5 # 包配置
├── example/ # 演示 App
│ ├── lib/main.dart # 演示页面(7 个功能按钮)
│ └── ohos/ # 示例的鸿蒙工程
├── images/ # 本文截图(OBS 图床)
├── README.OpenHarmony_CN.md / .md # 中英双语适配文档
└── CHANGELOG.OpenHarmony.md # 鸿蒙适配发版说明
三、阶段①②:创建工程与 Dart 层设计
3.1 一条命令生成插件骨架
Flutter OH 工具链(就是那个 ohos 分支的 flutter 命令)扩展了 flutter create,可以直接生成带 ohos/ 目录的插件工程:
flutter create --org dev.atomcode --template=plugin \
--platforms=ohos --project-name flutter_calendar_kit \
flutter_calendar_kit
生成完毕后,pubspec.yaml 里会多出一段平台注册声明,这是 Flutter 工具链识别插件的"身份证":
flutter:
plugin:
platforms:
ohos:
pluginClass: FlutterCalendarKitPlugin # 必须与 ArkTS 类名完全一致
小白注意:
pluginClass的值会和原生侧getUniqueClassName()返回值做严格比对(区分大小写),两边不一致运行时会报Plugin not found。
3.2 设计跨端 API:先想好"用户怎么用"
Dart 层是给 Flutter 开发者用的门面,设计原则是贴近鸿蒙 API 但不暴露鸿蒙概念。最终对外只暴露一个类 FlutterCalendarKit,10 个方法:
| 方法 | 作用 |
|---|---|
requestPermissions() |
动态申请读写权限,返回是否全部授权 |
createCalendar(account) |
创建日历账户 |
addEvent(event) → int |
创建日程,返回日程 id |
addEvents(events) |
批量创建 |
editEvent(event) → int |
跳转系统页面创建(无需写权限) |
openEventEditPage(id) |
跳转系统编辑页编辑已有日程 |
updateEvent(event) |
按 id 更新 |
deleteEvent(id) / deleteEvents(ids) |
删除 |
getEvents({filter}) |
查询(支持标题/ID/时间区间三种过滤) |
queryEventInstances(start, end) |
查询时间区间内的日程实例 |
数据模型同样一一对应鸿蒙的 Event 结构。以最核心的 CalendarEvent 为例:
class CalendarEvent {
final int? id; // 日程 id:创建时不填,更新/删除时必填
final EventType type; // 普通 / 重要 / 纪念日
final int startTime; // 开始时间(毫秒时间戳,必填)
final int endTime; // 结束时间(毫秒时间戳,必填)
final String? title;
final String? description;
final String? location;
final bool isAllDay; // 是否全天
final bool isLunar; // 是否农历
final List<int> reminderTimes; // 提醒时间(分钟值,如提前 15 分钟)
final Map<String, Object?>? recurrenceRule; // 重复规则
}
toMap() 方法把它变成 Map<String, Object>,交给 MethodChannel 序列化后跨语言传输。
3.3 三层 Dart 结构(pub 官方推荐姿势)
为了让插件既好测试又好替换,Dart 层按官方推荐的"平台接口"模式拆成三层:
FlutterCalendarKit(门面类)
│ 调用
▼
FlutterCalendarKitPlatform(抽象接口层)
│ 被 MethodChannelFlutterCalendarKit 实现
▼
MethodChannel(真正和原生通信)
好处:单元测试时可以注入一个"假平台"(Mock),不需要真机就能测 Dart 逻辑;将来想支持别的平台,再写一个实现类即可。
MethodChannel 层的核心只有二十行——一个泛型 invoke 包装,统一把原生异常翻译成 FlutterCalendarException:
const MethodChannel _channel = MethodChannel('ohos_calendar_kit');
Future<T> _invoke<T>(String method, [Map<String, Object?>? args]) async {
try {
return await _channel.invokeMethod<T>(method, args) as T;
} on PlatformException catch (e) {
// e.code 是鸿蒙错误码,如 201=权限拒绝、23900001=参数错误
throw FlutterCalendarException(code: e.code, message: e.message);
}
}
四、阶段③:ArkTS 原生实现(核心)
4.1 插件类的"三件套"
鸿蒙 Flutter 插件主类要实现三个接口:
export default class FlutterCalendarKitPlugin
implements FlutterPlugin, MethodCallHandler, AbilityAware {
private channel: MethodChannel | null = null;
private ability: UIAbility | null = null; // 保存 UIAbility,后面拿 context 用
getUniqueClassName(): string {
return 'FlutterCalendarKitPlugin'; // 必须与 pubspec 里 pluginClass 一致
}
onAttachedToEngine(binding: FlutterPluginBinding): void {
// 引擎绑定:创建通道并注册消息处理器
this.channel = new MethodChannel(
binding.getBinaryMessenger(),
'ohos_calendar_kit', // 通道名,Dart 侧必须一致
StandardMethodCodec.INSTANCE
);
this.channel.setMethodCallHandler(this);
}
onAttachedToAbility(binding: AbilityPluginBinding): void {
this.ability = binding.getAbility(); // 拿到 UIAbility
}
onMethodCall(call: MethodCall, result: MethodResult): void {
// 按 call.method 分发到具体实现
}
}
三个接口各司其职:
| 接口 | 类比 Android | 作用 |
|---|---|---|
FlutterPlugin |
FlutterPlugin |
与引擎绑定/解绑,创建通道 |
MethodCallHandler |
同名 | 接收 Dart 的方法调用 |
AbilityAware |
ActivityAware |
拿到 UIAbility,从而获得 Context |
4.2 权限申请:一切功能的前置
private async requestPermissions(result: MethodResult): Promise<void> {
const permissions: Array<Permissions> = [
'ohos.permission.READ_CALENDAR',
'ohos.permission.WRITE_CALENDAR'
];
const atManager = abilityAccessCtrl.createAtManager();
const res = await atManager.requestPermissionsFromUser(
this.ability!.context, permissions); // 弹出系统授权框
let allGranted = true;
for (const r of res.authResults) {
if (r !== 0) allGranted = false; // 0 = 已授权
}
result.success(allGranted);
}
除了动态申请,宿主 App 还必须在 module.json5 里静态声明这两个权限(带 reason 用户可见文案),否则动态申请会直接失败:
"requestPermissions": [
{
"name": "ohos.permission.WRITE_CALENDAR",
"reason": "$string:calendar_permission_reason",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
}
]
4.3 日程增删改查:getCalendar 是钥匙
API 26 上有个容易踩的细节:日程的增删改查方法挂在 Calendar 对象上,而不是 CalendarManager 上。必须先拿到日历对象:
private async getCalendar(): Promise<calendarManager.Calendar> {
if (this.calendarMgr == null) {
this.calendarMgr = calendarManager.getCalendarManager(this.ability!.context);
}
return await this.calendarMgr.getCalendar(); // 取默认日历(不填账户即系统默认)
}
private async addEvent(call: MethodCall, result: MethodResult): Promise<void> {
const calendar = await this.getCalendar(); // ← 先拿 Calendar
const id = await calendar.addEvent(this.eventFromCall(call)); // ← 再加日程
result.success(id); // 返回日程 id 给 Dart
}
deleteEvent / deleteEvents 同理也是 calendar.deleteEvent(id),如果按老文档写到 CalendarManager 上会直接编译报 Property 'deleteEvent' does not exist on type 'CalendarManager'。
4.4 从 MethodCall 还原 Event 对象
Dart 传来的参数在 ArkTS 侧是 MethodCall,需要手动逐字段还原成 calendarManager.Event:
private eventFromCall(call: MethodCall): calendarManager.Event {
const event: calendarManager.Event = {
type: (call.argument('type') as number) ?? calendarManager.EventType.NORMAL,
startTime: call.argument('startTime') as number,
endTime: call.argument('endTime') as number,
};
const title = call.argument('title') as string | null;
if (title != null) event.title = title;
const reminderTimes = call.argument('reminderTimes') as number[] | null;
if (reminderTimes != null && reminderTimes.length > 0) {
event.reminderTime = reminderTimes; // API 26 上是 number[],不是 Set!
}
// ... 其余字段同理
return event;
}
这里有两个 API 26 特有的类型细节,都是对照 SDK 里的 .d.ts(位于 $SDK/ets/api/@ohos.calendarManager.d.ts)逐一校准的:
| 我们最初想当然的写法 | API 26 真实定义 | 后果 |
|---|---|---|
reminderTime: Set<number> |
reminderTime?: number[] |
编译报类型不匹配 |
recurrenceRule.recurrenceType |
recurrenceRule.recurrenceFrequency(必填) |
编译报属性不存在 |
CalendarAccount.type: string |
type: CalendarType(枚举) |
编译报类型不匹配 |
EventFilter = { title: 'x' } |
EventFilter 是类,要用 EventFilter.filterByTitle() 静态方法构造 |
运行时报 invalid keys |
经验:写鸿蒙插件前,先把 SDK 目录里对应的
.d.ts完整读一遍,比看任何二手资料都靠谱。
4.5 查询过滤器的三种姿势
getEvents 的过滤条件对应 EventFilter 的三个静态构造方法:
calendarManager.EventFilter.filterByTitle('关键词') // 标题模糊匹配
calendarManager.EventFilter.filterById([519, 520]) // 按日程 id
calendarManager.EventFilter.filterByTime(start, end) // 按时间区间
插件侧把这三种统一为一个 EventFilter Dart 类(title / ids / timeRange 三个可选字段),ArkTS 侧按 ids > timeRange > title 的优先级选择构造方式。
五、阶段④:真机调试(效果图实录)
5.1 演示 App 的设计
为了把每个能力都暴露成可点按的按钮,example/lib/main.dart 做了一个极简界面:顶部一个标题输入框,中间 7 个按钮,底部一块"终端风格"的黑色日志区,每个操作的结果实时打印进去。这样即使不懂 Dart 的人,也能看懂每一步发生了什么。
Demo 的完整链路验证截图如下——权限申请、创建日程(id=519)、查询(标题+时间都能看到)、更新、删除,全部绿灯:
下面这张截图是刚点完"创建日程 + 查询日程"的状态,注意屏幕顶部弹出的系统日程提醒横幅——这就是 Calendar Kit 帮我们注册的提醒,不需要 App 在后台运行:
5.2 “所见即所得”:去系统日历里核对
插件写入的日程是真实落在系统日历里的。我们通过 hdc shell aa start -b com.huawei.hmos.calendar 打开系统日历 App,可以看到通过 editEvent(跳转系统页面)创建的日程安静地躺在列表里:
5.3 自动化验证:不靠人手的测试流程
真机验证用的是 hdc(HarmonyOS 的 adb 等价物)+ uitest 的组合拳,全自动跑完整个链路:
# 1. 构建签名安装(flutter 工具链支持 ohos 目标)
flutter build hap --debug
hdc install -r example/build/ohos/hap/entry-default-signed.hap
# 2. 启动应用
hdc shell aa start -a EntryAbility -b dev.atomcode.ohos_calendar_kit_example
# 3. 用 uitest 模拟点击(坐标来自 dumpLayout 导出的控件树)
hdc shell uitest dumpLayout -p /data/local/tmp/layout.json # 导出控件坐标
hdc shell uitest uiInput click 221 656 # 点"申请权限"
hdc shell uitest uiInput click 586 656 # 点"创建日程"
# 4. 抓日志看结果
hdc shell "hilog -x | grep -iE 'addEvent|CalendarKitPlugin'"
其中 dumpLayout 会把当前界面的控件树导出成 JSON,每个控件带 bounds 坐标——写个小脚本解析出按钮中心点,就能精确点击。再配合 screenCap 截图、dumpLayout 读回应用内日志文本,就能实现"点击→读取结果→断言"的闭环,本文所有截图与验证结论均由这套流程产出。
六、阶段④:踩坑复盘(最有价值的部分)
开发过程中真实踩到了 4 个坑,每一个都浪费了至少一轮 2~3 分钟的构建周期。整理成表,后人少走弯路:
| # | 现象 / 报错 | 根因 | 解法 |
|---|---|---|---|
| 1 | deleteEvent 编译报 Property 'deleteEvent' does not exist on type 'CalendarManager' |
API 26 把日程增删改查放在 Calendar 对象上,CalendarManager 只管账户 |
先 getCalendar() 拿日历对象,再调 calendar.deleteEvent(id) |
| 2 | getEvents 运行时报 23900001 invalid keys! |
EventFilter 在 API 26 是类,不能用 { title: 'x' } 裸对象字面量;自定义 keys 数组也不被接受 |
用静态方法构造:EventFilter.filterByTitle() / filterById() / filterByTime(),且不传 keys 参数 |
| 3 | addEvent 运行时报 23900001 AddEvent failed!,hilog 打印收到的参数竟为 event={"type":0}——除默认值外全部字段丢失 |
MethodChannel 大坑:flutter_ohos 的编解码器把 Dart 传来的 Map 交付为 ArkTS Map 实例,而我们用 call.args as Record + args['key'] 的属性访问方式取值,在 Map 上全部取到 undefined(静默失败,不报错) |
统一改用 MethodCall.argument(key)(它内部兼容 Map/Object 两种形态);嵌套对象(如 filter、单个 event)也包一层 new MethodCall('', obj) 再 argument() 取 |
| 4 | ArkTS 编译报 Enum conversion of type 'number' to type 'CalendarType' may be a mistake |
ArkTS 禁止 number 直接 as 枚举 | 中转一层:value as Object as calendarManager.CalendarType |
其中坑 3 最隐蔽:代码编译通过、不崩溃,只是字段"悄悄消失",最后业务 API 报一个与真实原因八竿子打不着的参数错误。定位全靠在 addEvent 失败分支里加了一行 JSON.stringify(event) 日志,看到序列化结果只剩 {"type":0} 才恍然大悟。这个坑对任何写 Flutter OHOS 插件的人都适用,值得单独记一笔:
铁律:在 ArkTS 插件里取 MethodChannel 参数,永远用
call.argument(key),永远不要把call.args强转成 Record/对象用属性访问。
另外还有一条工程经验:SDK 版本对应的 .d.ts 是唯一权威。本插件的几个类型错误,全是靠 $SDK/ets/api/@ohos.calendarManager.d.ts 原文对照修正的,网上的二手资料(包括部分官方示例)可能停留在旧 API 版本。
七、阶段④:验证结果
7.1 真机全链路测试矩阵
在 Mate 60 Pro(OpenHarmony 7.0.0.111 / API 26)上,通过 uitest 自动化点按 + hilog/dumpLayout 断言,测试结果:
| 测试项 | 方法 | 结果 |
|---|---|---|
| 动态权限申请 | requestPermissions() |
✅ 系统弹窗,授权后返回 true |
| 创建日程 | addEvent() |
✅ 返回 id=519 |
| 查询(标题过滤) | getEvents(filter: EventFilter(title: ...)) |
✅ 查到 1 条,字段完整 |
| 更新日程 | updateEvent() |
✅ |
| 删除日程 | deleteEvent() |
✅ |
| 跳转系统创建页 | editEvent() |
✅ 返回 id=514,系统日历可见 |
| 跳转系统编辑页 | openEventEditPage() |
✅ 正常拉起 |
| 系统提醒 | 创建带 reminderTimes 的日程 | ✅ 到点弹出系统横幅(见 5.1 截图) |
7.2 静态检查与构建
dart analyze:插件包与 example 均无 error/warning;flutter build hap --debug:构建、自动签名一次通过;- 单元测试:
flutter test在 Flutter OH 3.50 工具链下存在挂起问题(工具链侧已知问题,与插件代码无关),Dart 层逻辑已通过 Mock 平台接口的用例覆盖。
八、阶段⑤:文档与发布
8.1 三份文档各司其职
一个合格的开源插件,文档要分清"给谁看":
| 文件 | 读者 | 内容 |
|---|---|---|
README.md |
所有人 | 一句话简介 + 快速开始,pub.dev 首页展示的就是它 |
README.OpenHarmony_CN.md / .md |
使用者 | 中英双语适配文档:安装、权限声明、功能表(带 ohos 支持列)、兼容性矩阵、API 表、实现原理、遗留问题 |
CHANGELOG.OpenHarmony.md |
使用者 | 鸿蒙适配发版说明,版本小节与 git tag 一一对应 |
8.2 发布到 pub.dev
发布前用 dry-run 做本地 + 服务端校验(不会真的上传):
env PUB_HOSTED_URL=https://pub.dev flutter pub publish --dry-run
国内环境注意:
PUB_HOSTED_URL平时可能指向国内镜像加速下载,但发布时会连镜像而不是 pub.dev,必须用env前缀临时覆盖。
本次发布还遇到一个典型问题:最初定的包名 flutter_calendar_kit 在 pub.dev 上已被占用(一个同名的日历 UI 组件包),于是更名为 ohos_calendar_kit 后重新发布。改名要同步改的不只是 pubspec.yaml 的 name,还有:
- Dart 侧
package:flutter_calendar_kit/...的所有 import; - MethodChannel 通道名(保持与包名一致,便于排查);
- example 的
bundleName、双语 README 的安装示例与链接; - 文件名(
lib/ohos_calendar_kit.dart等),保持仓库观感一致。
8.3 版本与 tag
首个适配版本遵循 {上游版本}-ohos-{适配版本} 的社区惯例,tag 为 0.0.1-ohos-1.0.0-beta.1,与 CHANGELOG.OpenHarmony.md 中的版本小节一一对应,方便用户按版本回溯。
九、总结:给想写鸿蒙 Flutter 插件的你
回顾整个开发过程,可以浓缩成一份"新手路线图":
- 环境:装 Flutter OH SDK(ohos 分支的 flutter)+ DevEco Studio,
flutter doctor确认能看到鸿蒙工具链和真机; - 骨架:
flutter create --template=plugin --platforms=ohos,先跑通 example 的空插件; - 抄 SDK:把目标能力对应的
.d.ts(在$SDK/ets/api/下)完整读一遍,确认每个类、方法、字段的真实形态,不要凭记忆或旧资料写代码; - 打通一条线:先只实现一个最简单的方法(如 getPlatformVersion 级别的探针),真机跑通 MethodChannel 往返,再铺开全部 API;
- 参数访问用
call.argument():这是 Flutter OHOS 插件的第一大坑(见第六章坑 3); - 真机自动化:
hdc install+aa start+uitest dumpLayout/uiInput+hilog,把验证做成可重复的脚本,每改一轮代码全量回归; - 文档与发布:双语适配文档 + dry-run 校验 + 注意包名占用。
日历插件只是"方法调用型"插件(MethodChannel + MethodCallHandler)的一个样例。掌握了本文的套路,蓝牙、传感器、剪贴板……任何系统能力的鸿蒙化插件,都是同一套打法的重复应用。
参考文档
开源协议
本项目基于 Apache-2.0 协议开源,仓库地址:https://atomgit.com/oh-flutter/ohos_calendar_kit。