从零开发一个鸿蒙 Flutter 日历插件:ohos_calendar_kit 全过程实录

Source

本文以真实的开发过程为主线,完整记录如何基于鸿蒙 Calendar Kit 从零实现一个 Flutter 日历插件 ohos_calendar_kit(目标 API 26),并在华为 Mate 60 Pro 真机上全链路验证通过。文中所有代码均来自实际可运行的工程,配有真机截图,技术小白也能跟着一步步做出来。

Demo 应用全链路运行效果


一、生态背景:为什么需要这个插件

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 有两个前提条件:

  1. 声明权限:在 module.json5 里声明 ohos.permission.READ_CALENDAR 和 ohos.permission.WRITE_CALENDAR(都是 user_grant 权限,需要用户弹窗授权);
  2. 动态申请:运行时调用 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)、查询(标题+时间都能看到)、更新、删除,全部绿灯:

Demo 应用全链路运行效果

下面这张截图是刚点完"创建日程 + 查询日程"的状态,注意屏幕顶部弹出的系统日程提醒横幅——这就是 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 插件的你

回顾整个开发过程,可以浓缩成一份"新手路线图":

  1. 环境:装 Flutter OH SDK(ohos 分支的 flutter)+ DevEco Studio,flutter doctor 确认能看到鸿蒙工具链和真机;
  2. 骨架:flutter create --template=plugin --platforms=ohos,先跑通 example 的空插件;
  3. 抄 SDK:把目标能力对应的 .d.ts(在 $SDK/ets/api/ 下)完整读一遍,确认每个类、方法、字段的真实形态,不要凭记忆或旧资料写代码;
  4. 打通一条线:先只实现一个最简单的方法(如 getPlatformVersion 级别的探针),真机跑通 MethodChannel 往返,再铺开全部 API;
  5. 参数访问用 call.argument():这是 Flutter OHOS 插件的第一大坑(见第六章坑 3);
  6. 真机自动化:hdc install + aa start + uitest dumpLayout/uiInput + hilog,把验证做成可重复的脚本,每改一轮代码全量回归;
  7. 文档与发布:双语适配文档 + dry-run 校验 + 注意包名占用。

日历插件只是"方法调用型"插件(MethodChannel + MethodCallHandler)的一个样例。掌握了本文的套路,蓝牙、传感器、剪贴板……任何系统能力的鸿蒙化插件,都是同一套打法的重复应用。


参考文档

开源协议

本项目基于 Apache-2.0 协议开源,仓库地址:https://atomgit.com/oh-flutter/ohos_calendar_kit。