Flutter-OH 三方库适配：5 个文件就够了

Flutter-OH 三方库适配指南：核心文件+实操步骤

各位开发者大家好！

适配 Flutter-OH 三方库无需复杂操作，核心只需聚焦 5 个关键文件/目录，即可高效完成大部分库的适配工作。本文将详细拆解核心文件职责、基础结构搭建，以及完整实操示例，帮你快速上手适配流程。

一、适配核心：5 个关键文件/目录

这 5 个文件/目录是 Flutter-OH 适配的核心，覆盖平台实现、测试验证、文档说明和环境配置，缺一不可：

参考案例：已完成适配的 flutter_native_timezone[1]，可直接查看核心文件的配置规范。

二、基础结构快速搭建

无需手动创建复杂目录，通过一条命令即可生成适配所需的基础结构，再补充少量手动文件即可：

1. 执行创建命令

在 Flutter 插件项目根目录下，运行以下命令：

flutter create . --template=plugin --platforms=ohos

2. 自动/手动文件区分

• 自动生成（无需修改目录结构）：
  • ohos/ 核心实现目录
  • example/ohos/ 测试样例目录
• 手动创建（必需）：
  • README.OpenHarmony.md（英文说明文档）
  • README.OpenHarmony_CN.md（中文说明文档）
  • pubspec.yaml 添加 ohos 平台配置（需补充细节适配）

三、实操示例：完整适配流程

以下以 flutter_native_timezone 为例，带你走通从项目导入到提交代码的全流程，新手也能快速复刻：

步骤 1：导入原项目到 AtomGit

1. 访问 AtomGit[2]，点击「导入项目」；
2. 填写导入信息（参考下图）：
   • 原仓库地址：https://github.com/JeanmartinPV/flutter_native_timezone
   • 目标仓库名称：建议与原仓库一致（如 flutter_native_timezone）
   • 仓库描述：补充「Flutter-OH 适配版本」相关说明
   • 其他配置：默认公开/私有（按需求选择）
3. 点击「确认导入」，完成项目迁移。

导入项目页面

填写导入信息

步骤 2：克隆适配仓库到本地

选择以下任一方式克隆已导入的 AtomGit 仓库：

# 方式 1：SSH 克隆（需配置 SSH 密钥）
git clone git@atomgit.com:oh-flutter/flutter_native_timezone.git

# 方式 2：HTTPS 克隆（直接输入账号密码即可）
git clone https://atomgit.com/oh-flutter/flutter_native_timezone.git

步骤 3：配置 Flutter-OH 开发环境

确保本地已完成 Flutter-OH 环境搭建（需安装对应 SDK、工具链，具体参考 Flutter-OH 官方文档[3]），避免执行后续命令时出错。

步骤 4：生成 OH 平台基础结构

进入项目根目录，执行以下命令生成 ohos/ 和 example/ohos/ 目录：

cd flutter_native_timezone
flutter create . --template=plugin --platforms=ohos

步骤 5：开发适配与本地测试

在 ohos/ 目录中编写 OpenHarmony 平台的插件实现代码（需对齐原插件功能）；

通过 example/ohos/ 工程进行真机测试，确保功能正常、无崩溃；

编辑 pubspec.yaml，补充 OH 平台支持配置（示例如下）：

flutter:
  plugin:
    platforms:
      ohos:
        package: com.example.flutter_native_timezone
        pluginClass: FlutterNativeTimezonePlugin
        fileName: flutter_native_timezone_plugin.ohos.dart

编写中英文说明文档：

• README.OpenHarmony_CN.md：说明适配版本、安装方式、使用示例、兼容范围；
• README.OpenHarmony.md：同步中文文档核心内容，采用英文表述。

步骤 6：提交代码并推送

适配完成后，按以下步骤提交代码（路径简化为相对路径，通用适配所有环境）：

# 添加核心适配文件（仅提交新增/修改的关键文件）
git add ohos/ example/ohos/ pubspec.yaml README.OpenHarmony.md README.OpenHarmony_CN.md

# 提交代码（-s 签署贡献者声明，commit 信息规范：适配+库名+Flutter-OH 版本）
git commit -s -m "适配 flutter_native_timezone 至 Flutter-OH 3.35.7"

# 推送至远程仓库
git push

至此，整个 Flutter-OH 三方库适配就完成了！

四、适配优势：低冲突合并上游

本次适配方案的核心优势的是：新增文件不侵入原代码——ohos/、example/ohos/、README.OpenHarmony* 均为新增文件，pubspec.yaml 仅新增平台配置。后续同步原仓库（上游）的更新时，几乎不会出现代码冲突，维护成本极低。

后续支持

为了帮助大家更深入掌握适配技巧，我们将推出 「Flutter-OH 三方库适配训练营」，届时会详细讲解复杂场景适配、问题排查、性能优化等进阶内容，敬请期待！

如果在适配过程中遇到问题，可参考 示例仓库[4] 或在评论区交流～

参考资料

[1]

flutter_native_timezone: https://atomgit.com/oh-flutter/flutter_native_timezone

[2]

AtomGit: https://atomgit.com/

[3]

Flutter-OH 官方文档: https://docs.openharmony.cn/pages/v3.2/zh-cn/application-dev/flutter/flutter-overview.md

[4]

示例仓库: https://atomgit.com/oh-flutter/flutter_native_timezone