📦 device_calendar 用于读写设备日历。我在鸿蒙排期演示页中遇到了次日查不到日程、会议链接丢失的问题,于是补齐了社区实现中的重复频率映射、链接转换和周期实例查询。
完整代码已开源在 oh-flutter/device_calendar,修复分支与适用范围见第五节,欢迎提交 Issue 或前往 鸿蒙系统Flutter开源库社区 交流。

前言

📱 我用 device_calendar 做了一个“日程排期与会议同步”演示页,先后在 Mate X7 折叠屏模拟器与华为畅享 100 Pro Max 真机里写入连续七天的晨会。接口返回成功,页面却只查到当天一条,会议链接也成了空值。我从 Dart 模型查到通道参数,再对照系统日历日志,发现插件把两边含义不同的频率数值直接传了过去,链接转换和实例查询也各有遗漏。改完后,模拟器与真机上的同样窗口都能查到七条每日排期,周重复模板也从一条恢复为四条,写入的链接能够完整读回。

图 1 展示了页面如何调用插件写入并查询日程。这里验证的是周期排期和链接回读,系统日历详情、桌面卡片与提醒的使用范围放在第四节说明。

周期日程正向同步链路

图1 周期日程链路

一、页面操作与周期排期问题

1.1 页面里的两种排期

我把页面做成了两个可切换的模板,方便在同一台 Mate X7 展开态模拟器上复现。页面不需要用户逐条填写重复日程,只要选择模板、点击写入,就会查询对应时间段,让用户核对排期和链接。两种模板的参数如下:

  1. 每日晨会:选择「每日晨会同步」,时间为当天 09:30–10:00,使用 RecurrenceFrequency.Daily,共重复 7 次,附带测试用网页地址。应用写入后查询当天零点到第 7 天结束的记录,页面应列出每天的晨会时间。
  2. 每周研讨:切换到「每周课程研讨」,时间为当天下午 14:00–15:00,使用 RecurrenceFrequency.Weekly,连续 4 周共 4 次。应用附上研讨链接,再查询未来 28 天的排期。

以晨会为例,我关心的并不只是当天能不能看到一条记录。完整窗口应该有 7 条,从明天开始查则应该还有 6 条,而且各条记录都要保留写入的 URI。插件会把 URI 放入 EventService 的会议服务字段,页面负责检查回读字符串。两个 example.org 地址都是测试数据,没有对应的真实会议,也没有用它们执行跳转。

1.2 写入成功,后续排期却查不到

页面导入主包 package:device_calendar/device_calendar.dart,通过 DeviceCalendarPlugin 申请权限、创建测试日历,再调用 createOrUpdateEvent 写入日程,最后用 retrieveEvents 查询。应用只负责组织这些操作,重复规则和链接在鸿蒙端如何转换,由插件处理。

我使用的原版代码来自社区开发分支 br_v4.3.3_flutter3.27_ohos_dev,主包版本为 4.3.3,子包为 4.3.3-ohos-1.0.2,固定提交记在配套工程说明中。复现时,先完成授权,再选每日模板,写入后分别查完整窗口和次日起的窗口;换到每周模板后执行相同操作。接入过程中遇到的问题是:

  • 只依赖主包时,生成的注册器里没有鸿蒙插件类,日历调用抛出 MissingPluginException。在应用侧同时引入子包后,才能继续检查写入和查询。
  • 写入接口返回了数字编号,但每日模板的 7 天窗口只有当天一条,从次日查询则是 0 / 6 条。每周模板的 28 天窗口也只有首日 1 / 4 条,后三周为 0 / 3 条。两种模板读回的 Event.url 都是空值。

让我继续往原生层查的,是另一个不一致的结果:按编号读回刚写入的主日程,频率仍显示 RecurrenceFrequency.Daily,系统日志里的规则却是按年重复;Weekly 对应的记录则被写成按月重复。也就是说,模型上的频率看起来没变,实际排期已经变了。只比较写入前后的 Dart 属性,发现不了这处问题,还要看后续日期里有没有预期的实例。

1.3 我为什么沿用社区插件

选库时,我检查了 pub.dev 的发布页,也查了 oh-Flutter 和 CPF-Flutter 的公开仓库,先确认现有鸿蒙实现放在哪里、已经提供哪些日历操作。

device_calendar 的 pub.dev 包页面

图2 上游包页面

图 2 是 device_calendar 4.3.3 的发布页。这个包由 builttoroam.com 发布,上游源码在 builttoroam/device_calendar,使用 BSD-3-Clause 许可。它提供日历操作入口 DeviceCalendarPlugin,以及日程、重复规则和查询条件对应的 Event、RecurrenceRule、RetrieveEventsParams 模型。发布页列出 Android 和 iOS,上游仓库没有鸿蒙实现。

已有鸿蒙适配代码起初位于 CPF-Flutter/fluttertpc_device_calendar,仓库根包提供跨端入口,ohos 目录是 device_calendar_ohos 平台实现。其稳定分支 br_v4.3.3_flutter3.27_ohos、标签 4.3.3-ohos-1.0.1 和开发分支 br_v4.3.3_flutter3.27_ohos_dev 都已有 CalendarKit 的基础增删改查代码,我以开发分支作为排查起点,修好后再将完整适配归入独立社区仓库 oh-flutter/device_calendar。

oh-flutter/device_calendar 鸿蒙社区适配仓库主页

图3 鸿蒙社区适配仓

图 3 是完整适配与修复归入的社区仓库 oh-flutter/device_calendar 主页(采用 BSD-3-Clause 协议)。pub.dev 对应上游主包的发布信息,前面提到的 CPF-Flutter 排查基线仓承载了早期 CalendarKit 基础适配,而本次修复后的 ohos 平台实现与合规文档已归入该社区仓库的 ohos/device_calendar 分支。我接着检查了基线仓库的 README、变更记录和实现代码:原库已经提供周期日程模型,开发分支也修过日期筛选。因此,本文检查的是这些已有调用为什么在每日、每周模板中返回了错误结果,无需另造一套日历接口。

看完源码后,我把页面、插件和系统各自负责的事情理了一遍:

  • CalendarKit 提供年、月、周、日四种重复频率,EventService 可以保存会议等服务的链接,Calendar.queryEventInstances 按起止时间戳查询周期实例。使用这些能力仍需满足版本、权限和系统入口的要求。
  • device_calendar 与 device_calendar_ohos 负责让同一套 Dart 调用在鸿蒙端得到相应结果。根包注册声明、重复频率映射、链接读写和实例查询都在这一层,问题也出在这些位置。
  • Example 提供模板选择、写入按钮和结果列表,调用插件后显示实例数与链接,测试结束时清理自己创建的日历账户。页面不负责计算周期或修正插件发回的数据。

我保留了原有包名、公开类签名和 BSD-3-Clause 许可,在开发分支基线上修改这些位置并整理开源说明同步至 oh-flutter/device_calendar。业务仍从主包创建和查询日程;接入工程需要更新依赖、最低 API 版本和权限。用过旧式 data URI 读取方法的项目,还要调整链接读取方式,第四节会说明这点。

二、修复前后的画面与日志

2.1 两组应用的运行条件

我把原版插件和修复后的插件分别构建成两个应用,先在 HUAWEI Mate X7 折叠屏模拟器上对照,再连接到华为畅享 100 Pro Max 实体真机复测。两组设备使用相同页面、相同模板和日历读写权限,环境如下:

  • Flutter 框架版本:3.41.9+ohos-1.0.2(Dart 3.11.5)
  • 开发工具与 SDK:DevEco Studio 26.0.0,HarmonyOS SDK API 26
  • 模拟器镜像与分辨率:HUAWEI Mate X7 展开态(分辨率 2210 × 2416,镜像版本 7.0.0.107)
  • 实体真机与固件:华为畅享 100 Pro Max 直板手机(公开型号 YEW-AL80,分辨率 1128 × 2444,固件 YEW-AL80 7.0.0.100,OpenHarmony-7.0.0.105,arm64-v8a)
  • 对照应用包:模拟器组使用基线包 com.example.pgc29base 与修复包 com.example.pgc29fix;真机组在纯英文隔离目录注入本地调试签名构建最新对照包,两者运行完全一致的页面代码与最小日历读写权限配置。

下面的运行图和日志来自第五节固定源码中的那组采样。每日、每周模板各写入一次,再分别查询完整窗口和次日起的窗口;这些次数用于检查功能结果,没有统计性能指标。补充的查询失败与清理失败分支由 Example 测试覆盖。

两组应用都从干净桌面启动,取得相同的日历读写授权后,依次执行每日晨会的 7 天窗口和每周研讨的 28 天窗口。对照时既看列表条数,也看日程时间和读回链接,避免只凭顶部的成功提示判断结果。

2.2 页面实际查到了哪些排期

原版应用的画面见图 4。点击写入每日晨会后,顶部提示核验异常:7 天窗口只有 1/7 条,次日起为 0/6 条,链接为空。列表里留下的是首日周三 09:30–10:00 的主记录,右侧也标着链接缺失。接口确实写入了一条日程,但这个结果无法供页面查看后面几天的晨会。

修复前每日晨会核验异常界面

图4 修复前核验图

换成修复包,执行同样的操作,列表才显示出完整的一周(图 5)🎉。7 天窗口有 7/7 条,次日起有 6/6 条,从周三到次周周二,每天都是 09:30–10:00。Event.url 读回了输入的测试地址,各条记录都有链接保留标记;服务字段是否写入,我另外对照了原生日志。

修复后每日晨会完整展开界面

图5 修复后核验图

每周模板的 28 天窗口跨过了月底,我把它和每日模板放在同一段录制里。图 6 先展示原版应用的每日结果,再切换到每周研讨:查询仍只有首日 1/4 条,从次日开始查为 0/3 条,链接也为空。

修复前每日与每周排期动态复现

图6 修复前运行图

图 7 按相同顺序运行修复包。每日模板得到 7/7 条后,我切换到每周研讨再次写入,28 天内查到了连续四个周三 14:00–15:00 的记录,共 4/4 条,会议链接也保留下来。两个模板的区别是重复频率与查询窗口,页面的写入和查询流程相同。

修复后每日与每周排期动态验证

图7 修复后运行图

2.3 从日志核对系统规则

页面里的条数能帮助我核对排期是否齐全,但要判断系统收到了什么规则,还得看原生日志。我同时查看应用日志和 HarmonyOS 的 CalendarData 服务日志,把写入参数、存储规则和查询结果对应起来(图 8)。

修复前后系统日历服务日志对照

图8 系统日志对照

CalendarData 的 RecurringEventExpand 日志里能看到系统使用的重复规则:

  • 修复前,应用传入 Daily 的下标 0,通道链接为空,服务日志却写着 FREQ=YEARLY;COUNT=7,窗口内只有 1 条实例。传入 Weekly 的下标 1 时,规则变成了 FREQ=MONTHLY;COUNT=4。
  • 修复后,同样的 Daily 下标对应 FREQ=DAILY;COUNT=7,系统生成 7 条实例。插件日志记录 ohosFreq=3 serviceType=Meeting hasServiceUri=true,窗口查询得到 instances=7 masters=1。Weekly 则对应 FREQ=WEEKLY;COUNT=4,返回 4 条实例。

表 1 把注册配置、系统规则和页面查询结果放在一起,便于对照是哪一步发生了变化:

核验维度修复前基线表现修复后实测表现
根包联邦注册声明缺失 ohos 平台项自动注册 device_calendar_ohos
按天重复系统落库规则FREQ=YEARLY(错变每年)FREQ=DAILY(按天重复)
每日晨会 7 天展开数1 / 7 条(次日起 0 / 6)7 / 7 条 🟢↑(次日起 6 / 6)
按周重复系统落库规则FREQ=MONTHLY(错变每月)FREQ=WEEKLY(按周重复)
每周研讨 28 天展开数1 / 4 条(次日起 0 / 3)4 / 4 条 🟢↑(次日起 3 / 3)
标准网页链接通道值空值(序列化阶段丢失)原样保留完整链接字符串
回读 Event.url 与服务空值,EventService 未写入标准 Uri,绑定会议服务

表1 实测指标对照

2.4 华为畅享 100 Pro Max 真机排期复测

折叠屏模拟器完成对照后,我把补齐查询与清理错误处理及直板窄屏标题自适应的最新页面装到华为畅享 100 Pro Max 真机上,通过 USB 独立投屏窗口观察实体手机的排期写入与系统日历落库表现(窗口顶栏设备序列号已做像素马赛克脱敏)。

真机运行原版基线时(图 9),授予普通日历读写权限并写入「每日晨会同步」后,系统 com.huawei.hmos.calendardata 服务日志同样打印 FREQ=YEARLY;COUNT=7;INTERVAL=1;WKST=SU;BYMONTHDAY=12;BYMONTH=11,7 天窗口只返回当天 1 / 7 条,次日起为 0 / 6 条,通道 wireEventURL=null;切换到「每周课程研讨」后系统落库变为 FREQ=MONTHLY;COUNT=4,28 天窗口仅返回 1 / 4 条。

真机原版基线每日排期核验异常投屏窗口

图9 真机基线核验

换成修复包在畅享 100 Pro Max 真机上执行相同操作(图 10),每日晨会落库规则恢复为 FREQ=DAILY;COUNT=7;INTERVAL=1;WKST=SU,7 天窗口完整展开 7 / 7 条(次日起 6 / 6 条),每周课程落库为 FREQ=WEEKLY;COUNT=4 并展开 4 / 4 条(次日起 3 / 3 条),两条测试会议链接都原样读回。

真机修复后每日排期完整展开投屏窗口

图10 真机修复展开

图 11 记录了真机上的连续实操过程:先清理本地测试账户,写入「每日晨会同步」并滑动浏览连续 7 天的排期明细与有效入会链接标记,随后切到「每周课程研讨」完成 28 天窗口的 4 次周会核验;验证结束后再次点击右上角清理按钮即可移除测试日历账户。

真机每日与每周排期连续切换实操

图11 真机排期实操

三、重复规则、链接与实例查询的修复

我先让主包能够找到鸿蒙实现,再修正写入时的频率和链接,最后处理时间窗口查询。图 12 中,写入方向把 Dart 参数转成 CalendarKit 能识别的规则和服务字段;回读方向先取得周期实例,再补上主日程的信息,转回 Dart 模型。

写入与回读双向修复机制

图12 读写映射机制

3.1 同一个频率数值,两边含义不同

🔍 日志里 Daily 变成了 YEARLY,我先检查两边的枚举定义和通道里传的数值。

主包 4.3.3 的 lib/src/common/recurrence_frequency.dart 按 Daily、Weekly、Monthly、Yearly 排列,下标依次是 0、1、2、3。序列化直接发送 recurrenceFrequency.index,因此 Dart 传出的 0 表示“每天”。CalendarKit 的定义正好相反:YEARLY = 0、MONTHLY = 1、WEEKLY = 2、DAILY = 3。相同数字在两边代表不同的频率,需要明确转换。

接着看社区实现,子包 ohos/lib/src/common/recurrence_frequency.dart 把枚举按年到天排列,与主包不同。原生 parseRecurrenceRule 又直接把收到的整数赋给系统枚举,没有区分这个数字来自哪一套定义。回读时,CalendarUtils.convertFrequencyToNumber 把 YEARLY 转成 0、DAILY 转成 3,仍然沿用了系统侧的顺序。表 2 列出了这几处数值的对应关系:

业务语义主包 Dart 下标原版子包下标鸿蒙 CalendarKit 枚举值原版主包写入实际落库
每日重复Daily = 03DAILY = 3误传 0 落库为按年重复
每周重复Weekly = 12WEEKLY = 2误传 1 落库为按月重复
每月重复Monthly = 21MONTHLY = 1误传 2 落库为按周重复
每年重复Yearly = 30YEARLY = 0误传 3 落库为按天重复

表2 频率枚举映射

沿着 Daily 走一遍就容易看清了:主包发送 0,原生把它当作 YEARLY 写入;读回时,原生又把 YEARLY 转成 0,主包便把这个 0 解码成 Daily。写入和回读的属性相同,实际日程却不是每天重复。 这也解释了为什么单看主记录会以为没有问题,而次日起的窗口里找不到后续晨会。

注册配置是另一处需要先补齐的地方。根包 pubspec.yaml 只有 Android 和 iOS 平台项,没有指定鸿蒙默认实现包。我加入 ohos: default_package: device_calendar_ohos,让主包调用能找到鸿蒙插件;宿主 module.json5 只声明日历读写权限,配置见图 13。

联邦插件注册与最小日历权限配置

图13 插件权限配置

枚举部分,我先把子包的 RecurrenceFrequency 顺序改回与主包一致,再在 CalendarUtils.ets 中分别处理写入和回读的转换。构造重复规则时,parseRecurrenceRule 调用 CalendarUtils.parseFrequencyIndex(freqArg),不再直接使用收到的整数。这样主包和子包遵循同一套通道定义,鸿蒙枚举的差异由原生层处理:

  // 将鸿蒙 CalendarKit 重复频率枚举转换为跨端统一的 RecurrenceFrequency 下标:
  // Dart 侧定义为 Daily=0, Weekly=1, Monthly=2, Yearly=3;
  // CalendarKit 定义为 YEARLY=0, MONTHLY=1, WEEKLY=2, DAILY=3。
  static convertFrequencyToNumber(recurrenceFrequency: calendarManager.RecurrenceFrequency): number {
    switch (recurrenceFrequency) {
      case calendarManager.RecurrenceFrequency.DAILY:
        return 0;
      case calendarManager.RecurrenceFrequency.WEEKLY:
        return 1;
      case calendarManager.RecurrenceFrequency.MONTHLY:
        return 2;
      case calendarManager.RecurrenceFrequency.YEARLY:
        return 3;
      default:
        return 0;
    }
  }

  // 将 Dart 侧跨端统一的 RecurrenceFrequency 下标映射为鸿蒙 CalendarKit 枚举值
  static parseFrequencyIndex(freqIndex: number): calendarManager.RecurrenceFrequency {
    switch (freqIndex) {
      case 0:
        return calendarManager.RecurrenceFrequency.DAILY;
      case 1:
        return calendarManager.RecurrenceFrequency.WEEKLY;
      case 2:
        return calendarManager.RecurrenceFrequency.MONTHLY;
      case 3:
        return calendarManager.RecurrenceFrequency.YEARLY;
      default:
        return calendarManager.RecurrenceFrequency.DAILY;
    }
  }

3.2 链接在发给原生之前就丢了

链接问题出现在更早的位置:页面传入的是 Uri.parse('https://...'),可 Event 序列化出来的 eventURL 已经是空值,原生层没有收到网址。

我检查了主包和子包的 lib/src/models/event.dart。写入时,两者都用 data['eventURL'] = url?.data?.contentText; 取链接,读回时则调用 Uri.dataFromString(foundUrl)。这里的 Uri.data 只适用于 data URI,普通网页地址或应用深链的这个属性为空,所以网址在发出通道消息之前就丢了,鸿蒙端也就没有构造 EventService。

读取方向的问题类似:即使系统返回了网址,旧代码仍会用 data URI 包装它。读回对象的协议头因此不再是输入时的 https,业务也不能按普通网址的方式使用。排查这种问题时,要同时检查序列化字符串和读回对象,单看原始输入里有网址还不够。

我在主包和子包的日程模型中加入 parseEventUrl、serializeEventUrl 及配套的文本载荷提取辅助函数,分别负责读回和写入。新代码保留标准 URI,对畸形内联前缀或非严格 UTF-8 字节流安全回退而不抛异常,同时不误拆非文本媒体类型的 data URI。原生服务解析逻辑会去掉链接两端的空白;收到有效的 eventURL 且未指定其他服务类型时,默认绑定 ServiceType.MEETING。模型里的转换函数如下:

  static UriData? _tryExtractDataUri(Uri uri) {
    if (uri.scheme != 'data') {
      return null;
    }
    try {
      return uri.data;
    } on FormatException catch (_) {
      return null;
    }
  }

  static String? _extractTextFromDataUri(UriData data) {
    // 仅解包旧代码生成的 text/* data URI,保留其他媒体类型原始串
    if (!data.mimeType.toLowerCase().startsWith('text/')) {
      return null;
    }
    try {
      final decoded = data.contentAsString().trim();
      return decoded.isEmpty ? null : decoded;
    } catch (_) {
      try {
        // 对非严格 UTF-8 文本载荷启用宽松解码兜底,避免抛出编码异常
        final raw = data
            .contentAsString(encoding: const Utf8Codec(allowMalformed: true))
            .trim();
        return raw.isEmpty ? null : raw;
      } catch (_) {
        return null;
      }
    }
  }

  static Uri? parseEventUrl(Object? rawUrl) {
    final text = rawUrl?.toString().trim();
    if (text == null || text.isEmpty) {
      return null;
    }
    final parsed = Uri.tryParse(text);
    if (parsed != null && parsed.hasScheme) {
      // 兼容旧代码通过 Uri.dataFromString 包裹标准网址的历史写法
      final data = _tryExtractDataUri(parsed);
      if (data != null) {
        final inner = _extractTextFromDataUri(data);
        if (inner != null) {
          final innerUri = Uri.tryParse(inner);
          if (innerUri != null && innerUri.hasScheme) {
            return innerUri;
          }
        }
      }
      return parsed;
    }
    return Uri.dataFromString(text);
  }

  static String? serializeEventUrl(Uri? uri) {
    if (uri == null) {
      return null;
    }
    final data = _tryExtractDataUri(uri);
    if (data != null) {
      final content = _extractTextFromDataUri(data);
      if (content != null) {
        return content;
      }
      if (data.mimeType.toLowerCase().startsWith('text/')) {
        return null;
      }
      final serializedData = uri.toString().trim();
      return serializedData.isEmpty ? null : serializedData;
    }
    final serialized = uri.toString().trim();
    return serialized.isEmpty ? null : serialized;
  }

普通网页地址和应用深链会保留协议头与路径。旧代码传来的 data URI 则先取出内部字符串,空串按空值处理。读回没有协议头的纯文本时,函数仍回退到 data URI;这个兼容分支让旧数据继续有相应表示,不会把一段备注当成标准网页地址。

3.3 查询实例,再补上主日程信息

频率写对后,查询方式也要跟着检查。原版 retrieveEvents 收到时间范围时,调用的是 currentCalendar.getEvents(EventFilter.filterByTime(startDate, endDate))。这个调用查的是主日程记录,不能代替页面要展示的每次重复排期。

主日程保存重复规则,周期实例对应每一次发生的时间。在本例中,getEvents 只返回起始时间落在窗口内的那条主记录;从 API 18 起提供的 Calendar.queryEventInstances 才能按窗口取出后续实例。CalendarData 日志还显示,跨度较长的周期日程在写入时只预先展开近期的一部分,查询更远的窗口时,系统再补齐对应实例。

因此,Flutter 页面需要的是系统算出的实例时间。插件仍然返回 Event 列表,但列表中各项对应窗口里的每次排期,不能把主记录的首日时间复制到所有项目上。

我检查 SDK 声明时还看到,实例查询默认返回单次实例的起止时间(instanceStartTime、instanceEndTime)与关联服务字段,却不附带主记录上的重复规则(recurrenceRule)、参会者、提醒时间和日程类型。直接转换会让这些系列级属性缺失,所以还要按主日程编号补查一次。

我把这段处理放在 DeviceCalendarOhosPlugin.ets 的 queryExpandedEventsInRange 中:先查窗口里的实例,收集并去重主日程编号,再批量取主记录、合并字段,最后按实例开始时间排序。同一条周期日程会对应多个实例,先去重可以避免为每一条实例重复查询同一份信息。

retrieveEvents 的时间范围分支会调用这个私有方法。代码中的 calendarManager 来自 CalendarKit,Log 来自 Flutter 鸿蒙引擎;日志标签和主记录字段列表定义在同一文件,完整声明及调用位置可在配套工程查看。字段列表包含上面需要补回的规则、参会者和提醒信息:

  private async queryExpandedEventsInRange(
    currentCalendar: calendarManager.Calendar,
    startDate: number,
    endDate: number,
    eventIds?: string[] | null
  ): Promise<calendarManager.Event[]> {
    // Dart 未传编号时可能送来 null,只在有效数组存在时附加筛选。
    const filterIds: string[] | null =
      eventIds !== undefined && eventIds !== null && eventIds.length > 0 ? eventIds : null;
    if (deviceInfo.sdkApiVersion < 18) {
      return this.queryFallbackEventsInRange(currentCalendar, startDate, endDate, filterIds);
    }
    const numericIds: number[] | undefined =
      filterIds !== null ? filterIds.map((item: string) => Number(item)) : undefined;
    let rawInstances: calendarManager.Event[] | null = null;
    try {
      rawInstances = numericIds !== undefined
        ? await currentCalendar.queryEventInstances(startDate, endDate, numericIds)
        : await currentCalendar.queryEventInstances(startDate, endDate);
    } catch (_err) {
      return this.queryFallbackEventsInRange(currentCalendar, startDate, endDate, filterIds);
    }
    const instances: calendarManager.Event[] = rawInstances ?? [];
    if (instances.length === 0) {
      Log.i(LOG_TAG, `retrieveEvents range: calendarId=${currentCalendar.id} instances=0`);
      return [];
    }
    const idSet: Set<number> = new Set<number>();
    instances.forEach((inst: calendarManager.Event) => {
      if (inst.id !== undefined) {
        idSet.add(inst.id);
      }
    });
    const uniqueIds: number[] = Array.from(idSet);
    // 批量读取系列主记录,补齐实例查询默认不返回的重复规则和提醒字段。
    const seriesMap: Map<number, calendarManager.Event> = new Map<number, calendarManager.Event>();
    if (uniqueIds.length > 0) {
      const seriesEvents: calendarManager.Event[] = await currentCalendar.getEvents(
        calendarManager.EventFilter.filterById(uniqueIds),
        EVENT_QUERY_KEYS
      );
      seriesEvents.forEach((seriesEvent: calendarManager.Event) => {
        if (seriesEvent.id !== undefined) {
          seriesMap.set(seriesEvent.id, seriesEvent);
        }
      });
    }
    const merged: calendarManager.Event[] = instances.map((inst: calendarManager.Event) => {
      const seriesEvent: calendarManager.Event | undefined =
        inst.id !== undefined ? seriesMap.get(inst.id) : undefined;
      return this.mergeSeriesEventFields(inst, seriesEvent);
    });
    merged.sort((a: calendarManager.Event, b: calendarManager.Event) => {
      return (a.instanceStartTime ?? a.startTime) - (b.instanceStartTime ?? b.startTime);
    });
    Log.i(
      LOG_TAG,
      `retrieveEvents range: calendarId=${currentCalendar.id} ` +
        `instances=${merged.length} series=${seriesMap.size}`
    );
    return merged;
  }

合并后,模型转换优先使用 instanceStartTime ?? startTime 取得当前实例的开始时间,结束时间也按同样方式处理。页面因此能显示每次排期的时刻,重复日期由系统推算,主记录的信息只需批量查询一次。

四、空值、权限与兼容范围

4.1 通道空值与可选参数的契约

⚠️ 编号筛选还有一个容易漏掉的输入:调用方没有传 eventIds 时,通道里可能仍然有这个键,只是值为 null。单用 eventIds !== undefined && eventIds.length > 0 检查,会把这种情况放过去。

我检查了 RetrieveEventsParams 的载荷和编解码逻辑。未指定的编号字段会以 null 发出,StandardMessageCodec 解码后,ArkTS 通过 args.get('eventIds') 取得的也是 null。因为 null 不等于 undefined,接着读取长度就会出错。

时间参数用 startDate != null && endDate != null 检查;编号则先确认是数组,再检查长度,即 Array.isArray(eventIds) && eventIds.length > 0。这两处检查处理的是空值和容器类型,编号本身是否合法仍需要后续校验,不能混成一个判断。

没有编号筛选时,我调用 queryEventInstances(start, end);有编号时再传数组。官方接口也允许把 ids 传成空数组或 undefined,因此双参数写法只是这里选择的调用方式,不能把另一种合法写法说成系统错误。版本要求同样要留意:接口从 API 18 起提供,本文运行在 API 26 镜像上,最低兼容版本需按这一接口下限配置,不能据此说 API 18 已经实测。CalendarKit 接口说明列出了参数和版本要求。

4.2 选对权限,也检查只读账户

我查了 SDK 的权限定义,日历的普通读写权限和全量权限对应不同的申请条件:

  • ohos.permission.READ_CALENDAR 和 ohos.permission.WRITE_CALENDAR 为 normal 等级,需要用户动态授权。普通应用可在 module.json5 声明并请求,不需要为此申请受限签名。在本文 API 26 环境中,授权后可以管理本应用创建的日历账户与日程;其他账户的日程没有纳入验证。
  • ohos.permission.READ_WHOLE_CALENDAR 和 ohos.permission.WRITE_WHOLE_CALENDAR 为 system_basic 等级,供系统级高权限应用申请。普通应用把它们加入配置,会因权限等级不匹配在签名或安装环节受阻,对应错误码为 9568289。

账户是否只读也需要如实传给页面。原版解析账户列表时,把 isReadOnly 固定设为 false,但鸿蒙的生日日历和订阅日历不支持普通写入。我在 CalendarUtils 中补上这两类账户的识别,让业务可以在调用写入接口之前检查只读标记。

4.3 旧链接用法与未测试的操作

如果项目以前用 event.url?.data?.contentText 读取链接,升级时要一起检查这段代码。修复后,有协议头的网址会还原为标准 Uri,通过 event.url?.toString() 可以取得链接,通过 event.url?.scheme 可以取得协议头。写入侧继续接受 Uri.parse 和旧式 Uri.dataFromString,两种输入都会取出其中的链接字符串。

系统日历应用还有单独的使用流程。我在 Mate X7 模拟器与畅享 100 Pro Max 真机上拉起预装日历(com.huawei.hmos.calendar)时,界面都停在首次启动的独立隐私声明页,没有代点同意或继续操作详情和跳转。因此,文中的写入结果来自 CalendarKit 实例回读、应用内排期列表与 CalendarData 服务日志,实际网页访问、日历卡片入口和提醒触发都还没有验证。Android、iOS 原生目录保持上游代码,也没有在这次运行回归。

五、结论与可直接复用的建议

5.1 这次修复解决了什么

这份补丁让每日、每周排期能够按窗口查询:每日模板从 1 条恢复到 7 条,每周模板从 1 条恢复到 4 条,链接也从空值恢复为输入的字符串。接入时继续使用 DeviceCalendarPlugin,把排期时间和链接交给插件即可,应用不需要另写一套周期计算。

5.2 在自己的项目中使用

💡 社区仓库的 ohos/device_calendar 分支合入并发版前(精简核心补丁 PR 位于 Fork 分支 feat/ohos_device_calendar_4.3.3),可以在应用的 pubspec.yaml 中引用包含完整 ohos/example 与全量测试的公开完整复现分支 abaoge/device_calendar(feat/ohos_device_calendar_4.3.3_repro)对应的固定提交,固定主包与子包版本;合入后即可直接切换为社区仓库分支。中心仓同版本号的发布包没有这部分鸿蒙实现:

dependencies:
  device_calendar:
    git:
      url: https://atomgit.com/abaoge/device_calendar.git
      ref: cd9d3923f6021fe2c07a4fae11654d1e5d1367fa
  device_calendar_ohos:
    git:
      url: https://atomgit.com/abaoge/device_calendar.git
      ref: cd9d3923f6021fe2c07a4fae11654d1e5d1367fa
      path: ohos
  timezone: ^0.9.0

鸿蒙宿主 build-profile.json5 的目标 product 需要设置 "compatibleSdkVersion": "5.1.0(18)" 或更高版本。这个配置声明应用最低能运行在哪个系统版本;低于 API 18 时补丁会回退为按时间读取主记录,无法在原生侧展开后续周期实例,因此依赖周期实例展开的应用应将最低兼容版本对齐到 API 18。

接着检查宿主 ohos/entry/src/main/module.json5 的 deviceTypes,按目标设备填写 phone、tablet 或 2in1 等类型。requestPermissions 只加入普通日历读写权限,并在 base、zh_CN、en_US 的 string.json 中补上权限理由文案:

"requestPermissions": [
  {
    "name": "ohos.permission.READ_CALENDAR",
    "reason": "$string:read_calendar_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.WRITE_CALENDAR",
    "reason": "$string:write_calendar_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

Dart 代码仍导入主包。调用下面的函数前,先用 initializeTimeZones() 初始化时区,再通过 requestPermissions() 取得日历授权,并传入可写日历的编号。函数创建七次每日晨会,随后查询 7 天窗口;写入和查询任一步失败,都会把错误交给调用方处理:

import 'package:device_calendar/device_calendar.dart';

Future<List<Event>> createDailyStandup(
  DeviceCalendarPlugin plugin,
  String calendarId,
) async {
  final shanghai = timeZoneDatabase.locations['Asia/Shanghai'] ?? local;
  final now = TZDateTime.now(shanghai);
  final todayStart = TZDateTime(shanghai, now.year, now.month, now.day);
  final start = TZDateTime(shanghai, now.year, now.month, now.day, 9, 30);

  final event = Event(
    calendarId,
    title: '每日晨会同步',
    start: start,
    end: start.add(const Duration(minutes: 30)),
    url: Uri.parse('https://meeting.example.org/daily-sync'),
    recurrenceRule: RecurrenceRule(
      RecurrenceFrequency.Daily,
      interval: 1,
      totalOccurrences: 7,
    ),
    reminders: <Reminder>[Reminder(minutes: 10)],
  );

  final saved = await plugin.createOrUpdateEvent(event);
  if (saved == null || !saved.isSuccess) {
    final details = saved?.errors
        .map((error) => '${error.errorCode}: ${error.errorMessage}')
        .join('; ');
    throw StateError('写入周期日程失败:${details ?? "未返回结果"}');
  }
  final result = await plugin.retrieveEvents(
    calendarId,
    RetrieveEventsParams(
      startDate: todayStart,
      endDate: todayStart.add(const Duration(days: 7)),
    ),
  );
  // 查询失败与查询成功但没有日程,需要让调用方分别处理。
  if (!result.isSuccess) {
    final details = result.errors
        .map((error) => '${error.errorCode}: ${error.errorMessage}')
        .join('; ');
    throw StateError('查询周期日程失败:$details');
  }
  return result.data?.toList() ?? <Event>[];
}

5.3 使用时保留这几个判断

  1. 权限按操作需要申请。本例管理应用自己的日历,使用 READ_CALENDAR 和 WRITE_CALENDAR 即可,不要为查询失败随意加入系统级全量权限。
  2. 链接按标准 URI 读取,展示时用 event.url?.toString()。写入前先看 calendar.isReadOnly,避免把只读日历当作可写目标。
  3. 按实际范围判断是否适合自己的页面。每日、每周模板已在 API 26 的 Mate X7 折叠屏模拟器与华为畅享 100 Pro Max 真机上验证,主包 66 项、子包 71 项与示例工程 7 项共 144 项单测通过;单独修改周期中的某一天、跨设备云账户同步,以及 Android、iOS 真机运行均未覆盖。API 18 是接口下限,不是已测试的镜像。

中文适配说明整理了接口支持范围与宿主接入条件;页面实现位于 同款 Example 的 ohos/example,根目录 example 是上游其他平台示例,该固定提交中的运行说明记录了原始对照场景。接入自己的页面时,记得保留上面的版本配置与错误检查:查询成功但列表为空,可以显示“暂无日程”;查询失败则显示原因,否则用户无法分辨是没有排期,还是应用根本没查到结果。

小结

回头看这处问题,最容易漏掉的就是读回的 Daily:属性和写入时一样,后面六天却没有晨会。查到系统规则之后,我才把这个现象和两边相反的枚举顺序对应起来。现在页面能列出每日与每周的后续排期,链接也能读回;对这类跨端适配,我会把用户接下来要查询的记录一并检查,而不只停在写入成功的回执上。

参考资料

  1. device_calendar 上游包主页(pub.dev)
  2. oh-flutter/device_calendar 鸿蒙社区适配仓库
  3. CPF-Flutter/fluttertpc_device_calendar 排查基线仓库
  4. HarmonyOS CalendarKit(日历服务)官方 API 参考
  5. 鸿蒙系统Flutter开源库社区
Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐