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

各位开发者大家好！

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

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

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

文件/目录路径	核心职责	备注
`ohos/`	OH 平台专属实现目录	存放插件在 OpenHarmony 平台的核心代码（如原生能力调用、接口适配）
`example/ohos/`	平台测试样例目录	提供适配后的本地测试环境，验证插件功能是否正常运行
`README.OpenHarmony.md`	英文适配说明文档	面向海外开发者，说明插件在 OH 平台的安装、使用、兼容版本等
`README.OpenHarmony_CN.md`	中文适配说明文档	面向国内开发者，同步英文文档核心内容，降低使用门槛
`pubspec.yaml`	平台支持配置文件	原有配置基础上，新增 OH 平台声明，确保 Flutter 工程识别适配

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

二、基础结构快速搭建

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

1. 执行创建命令

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

bash 复制代码

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

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

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

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

bash 复制代码

# 方式 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 官方文档），避免执行后续命令时出错。

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

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

bash 复制代码

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

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

在 ohos/ 目录中编写 OpenHarmony 平台的插件实现代码（需对齐原插件功能）；
通过 example/ohos/ 工程进行真机测试，确保功能正常、无崩溃；

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

yaml 复制代码

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：提交代码并推送

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

bash 复制代码

# 添加核心适配文件（仅提交新增/修改的关键文件）
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 三方库适配训练营」，届时会详细讲解复杂场景适配、问题排查、性能优化等进阶内容，敬请期待！

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

欢迎大家加入跨平台开发者社区。