Flutter 鸿蒙插件适配实战：用 flutter_native_timezone_2025 1.0.1 读取当前时区与系统目录

适配仓库： https://atomgit.com/oh-flutter/flutter_native_timezone_2025

适配分支： feat/ohos_flutter_native_timezone_2025_1.0.1

受测提交： 831eaeb9ada7488c0576153b3f41636efec10e43

一、最终效果与适配目标

预约、日志和全球城市选择器既需要当前 IANA 时区，也可能需要系统可用时区目录。flutter_native_timezone_2025 1.0.1 的两个公开方法正好对应这两个需求。上游发布包没有 OHOS 实现，本次适配保持静态 API 和 flutter_native_timezone_2025 通道不变，用系统数据库返回真实结果。

图 1：CHZ-AL00 / HarmonyOS 7.0.0.105 上读取到当前 Asia/Shanghai，系统目录包含 473 个时区标识。

图 2：在真实返回的目录中搜索 Shanghai，命中当前时区条目。

验证点	实测结果	证据
当前时区	`getLocalTimezone()` 返回 `Asia/Shanghai`	图 1、图 7
可用目录	`getAvailableTimezones()` 返回 473 个非空标识	图 1、图 7
查询与展示	搜索 Shanghai 能命中 `Asia/Shanghai`	图 2
自动化与构建	4 Dart + 2 Widget + 6 ArkTS，共 12 项及 HAP 通过	图 5、图 6
验证边界	未穷举验证 473 个标识，也未修改系统时区	图 7

二、成果速览

项目	内容
上游基线	pub.dev 1.0.1 发布归档，导入提交 `925e344a7142ced74e44bb231b487faf5fea53e8`，MIT
归档校验	SHA-256 `6a4848d5d614e2bb1d773c7dd825f1b333abd3cb3046a9f29f1dc435e6dde3f1`
适配分支	`feat/ohos_flutter_native_timezone_2025_1.0.1`
适配提交	`831eaeb9ada7488c0576153b3f41636efec10e43`
新增 OHOS 能力	当前时区与系统可用 IANA 标识列表
真机结论	当前值和目录基本完整性通过；目录逐项有效性与时区切换未覆盖

三、实测环境与源码来源

组件	实测版本
Flutter OH	`3.41.10-ohos-1.0.1`
Dart	`3.11.5`
DevEco Studio	`26.0.0 Release`
HarmonyOS SDK	API 26；示例兼容 API 18
真机	CHZ-AL00，HarmonyOS `7.0.0.105`
插件	`flutter_native_timezone_2025 1.0.1`

环境搭建参考 Flutter OH 环境搭建指南。本文实测稳定版 3.41.10-ohos-1.0.1，不把预览标签 3.44.9+ohos-0.0.1-canary1 写成运行环境。

2026 年 9 月 11 日核对时，pub.dev 最新版是 1.0.1。上游代码仓库无法匿名克隆，所以没有编造 Git commit 来源，而是下载 pub.dev 官方发布归档并核对元数据 SHA-256。随后导入 AtomGit，保留发布包内容和 MIT 许可证。这种来源比"看起来像上游"的未知镜像更可复现。

四、创建适配分支与独立示例

shell 复制代码

git clone https://atomgit.com/oh-flutter/flutter_native_timezone_2025.git
cd flutter_native_timezone_2025
git switch -c feat/ohos_flutter_native_timezone_2025_1.0.1 925e344a7142ced74e44bb231b487faf5fea53e8
flutter create --template=plugin --platforms=ohos --no-pub .

发布包缺少可独立验证的完整示例，本次补上列表、刷新、loading 和错误状态。插件类为 FlutterNativeTimezonePlugin，Dart 和 ArkTS 都沿用 flutter_native_timezone_2025 通道。

图 3：AtomGit origin、适配分支、完整 HEAD 与工作区状态。

五、两个 API 对应两个系统来源

Dart 公共入口保持不变：

dart 复制代码

final String current = await FlutterNativeTimezone.getLocalTimezone();
final List<String> zones =
    await FlutterNativeTimezone.getAvailableTimezones();

OHOS 当前时区由 systemDateTime.getTimezoneSync() 返回；目录由 i18n.TimeZone.getAvailableIDs() 返回：

typescript 复制代码

if (call.method === 'getLocalTimezone') {
  const zone = systemDateTime.getTimezoneSync();
  if (zone.length === 0) throw new Error('The system returned an empty timezone.');
  result.success(zone);
} else {
  const zones = i18n.TimeZone.getAvailableIDs();
  if (zones.length === 0) throw new Error('The system returned no timezone identifiers.');
  result.success(zones);
}

这里不维护硬编码列表，也不根据 UTC 偏移猜时区。多个 IANA 区域可能共享偏移，猜测会丢失夏令时和地区语义。空当前值或空目录都作为 timezone_unavailable 错误返回；Engine 解绑为 plugin_detached，未知方法为 notImplemented。读取公开系统数据无需权限。

图 4：当前时区和系统时区目录的两条方法路由及空值校验。

六、自动化和 HAP 构建

shell 复制代码

flutter pub get
flutter analyze
flutter test
node --test ohos/test/timezone.test.cjs
cd example
flutter analyze
flutter test
flutter build hap --debug --no-codesign

4 项 Dart、2 项 Widget 和 6 项 ArkTS，共 12 项通过。测试覆盖通道名、列表类型、null 契约、系统错误、空结果、未知方法以及 Engine 解绑/重绑。原发布包测试中错误的旧通道名称也已修正。

图 5：静态检查、12 项测试和示例状态验证。

图 6：无签名 HAP 元数据、摘要和固定受测提交。

七、远程依赖和真机验证

yaml 复制代码

dependencies:
  flutter_native_timezone_2025:
    git:
      url: https://atomgit.com/oh-flutter/flutter_native_timezone_2025.git
      ref: 831eaeb9ada7488c0576153b3f41636efec10e43

隔离宿主通过 pubspec.lock 固定到同一 SHA，完成分析、签名 HAP 构建和覆盖安装。真机返回当前时区 Asia/Shanghai 和 473 个非空标识；页面搜索能够在系统结果中找到 Asia/Shanghai。这证明返回值来自可用目录，但没有逐项验证 473 个 ID 的别名、历史规则或业务数据库兼容性。

图 7：当前时区、目录数量、非空检查和未覆盖边界。

应用内真实截图：搜索其他 IANA 标识

图 8：在真实系统目录中搜索 Tokyo，命中 Asia/Tokyo，说明页面使用的是目录数据而不是固定单条结果。

八、FAQ

Q1：为什么不用 UTC+8 代替 Asia/Shanghai

现象： 两者当前偏移看起来相同。
原因： 偏移只描述某一时刻，IANA 标识还包含地区规则和历史变化。
解决方法： 直接使用系统 IANA 标识，在展示层再做友好名称映射。
验证结果： 真机公共 API 返回 Asia/Shanghai，未经过偏移反推。

Q2：为什么目录不能硬编码

现象： 内置常量实现简单，却可能与设备系统数据库不一致。
原因： 时区数据库会更新，系统可用 ID 也可能包含平台版本差异。
解决方法： 每次刷新时调用系统 getAvailableIDs()，业务需要固定集合时自行做版本化缓存。
验证结果： 真机实际返回 473 项，搜索页直接使用该结果。

Q3：上游 commit 为什么不是 GitHub SHA

现象： 文章基线记录为 pub.dev 归档和导入提交。
原因： 核对时上游仓库无法匿名克隆，不能声称验证了不可获取的 Git commit。
解决方法： 使用官方发布归档并验证 SHA-256，再完整导入 AtomGit。
验证结果： 来源摘要、导入提交、12 项测试和 HAP 均可复核。

九、总结

flutter_native_timezone_2025 1.0.1 已在 OHOS 上接入当前 IANA 时区和系统可用目录，保留两个静态 Dart API 与原错误契约。12 项自动化、HAP 构建和 API 26 真机读取通过。

当前结论不包含时区切换、目录逐项语义和其他设备。项目应锁定适配提交，并把系统目录与业务支持清单分开管理。

十、参考链接

欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter