{"id":22941769,"url":"https://github.com/zacksleo/flutter-ohos-demo","last_synced_at":"2026-05-01T15:31:43.785Z","repository":{"id":266772104,"uuid":"897674916","full_name":"zacksleo/flutter-ohos-demo","owner":"zacksleo","description":"Flutter ohos demo project","archived":false,"fork":false,"pushed_at":"2025-07-01T06:10:31.000Z","size":1029,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-01T07:23:59.548Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zacksleo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-03T03:21:54.000Z","updated_at":"2025-07-01T06:10:35.000Z","dependencies_parsed_at":"2025-04-22T10:56:24.624Z","dependency_job_id":"434c71b7-bca8-4655-8349-964f1dae98b0","html_url":"https://github.com/zacksleo/flutter-ohos-demo","commit_stats":null,"previous_names":["zacksleo/flutter-ohos-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zacksleo/flutter-ohos-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacksleo%2Fflutter-ohos-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacksleo%2Fflutter-ohos-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacksleo%2Fflutter-ohos-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacksleo%2Fflutter-ohos-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zacksleo","download_url":"https://codeload.github.com/zacksleo/flutter-ohos-demo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zacksleo%2Fflutter-ohos-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32502980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-14T13:44:58.150Z","updated_at":"2026-05-01T15:31:43.775Z","avatar_url":"https://github.com/zacksleo.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 鸿蒙 Flutter 实战：现有 Flutter 项目支持鸿蒙 II\n\n## 引言\n\n在之前的文章[鸿蒙Flutter实战：09-现有Flutter项目支持鸿蒙](https://gitee.com/zacks/awesome-harmonyos-flutter/blob/master/%E9%B8%BF%E8%92%99%20Flutter%20%E5%AE%9E%E6%88%98/%E9%B8%BF%E8%92%99Flutter%E5%AE%9E%E6%88%98%EF%BC%9A09-%E7%8E%B0%E6%9C%89Flutter%E9%A1%B9%E7%9B%AE%E6%94%AF%E6%8C%81%E9%B8%BF%E8%92%99.md)中，介绍了如何改造项目，适配鸿蒙平台。\n\n文中讲述了整体的理念和思路，本文更进一步，结合可实操的项目代码，详细说明如何实施。\n\n通过模块化、鸿蒙壳工程，结合 FVM 管理多版本 Flutter SDK，最终，保持原 Flutter 代码纯净，最小化修改，完成了鸿蒙化的适配示例。\n\n本项目代码地址: https://gitee.com/zacks/flutter-ohos-demo\n\n## 准备工作\n\n### 1.安装 FVM 和 melos\n\n安装 [FVM](https://fvm.app/)，更多安装方式参考 fvm 官方文档\n\n```bash\ncurl -fsSL https://fvm.app/install.sh | bash\n```\n\n安装[melos](https://melos.invertase.dev/)\n\n```bash\ndart pub global activate melos\n```\n\n### 2.使用 FVM 安装 Flutter SDK\n\n分别安装官方的3.22版本，以及[鸿蒙社区的 3.22.0](https://gitcode.com/openharmony-tpc/flutter_flutter) 版本\n\n### 3.搭建 Flutter鸿蒙开发环境\n\n参考文章《鸿蒙Flutter实战：01-搭建开发环境》\n\n\n## 搭建项目架构\n\n### 创建目录\n\n```bash\n# 创建项目目录\nmkdir flutter-ohos-demo\n```\n\n\u003e 设置使用的 Flutter SDK 版本\n\u003e 推荐在 VsCode 的命令行中执行以下命令，这将创建 .fvm 目录, .vscode/setting.json 文件, 和.fvmrc 文件\n\n```bash\nfvm use 3.22.0\n```\n### 初始化工作区间\n\n创建目录，项目结构如下所示：\n\n```bash\n.\n├──  packages\n│   ├── apps  #该目录用于存放各端应用壳工程\n│   ├── common #该目录用于存放公共库，均为纯 dart 代码，不依赖于 ios/android 等原生实现\n│   │   ├── domains #领域对象，存放各类实体文件，如枚举/模型/vo/事件等\n│   │   ├── extensions #存放扩展类文件，对于类的扩展方法/属性\n│   │   ├── services #服务类：如请求服务/授权服务/缓存服务/平台调用服务/路由服务/工具类等\n│   │   └── widgets #通用小型 widgets, 纯dart编写的 Flutter UI 组件\n│   ├── components #封装组件库，可以依赖于第三方库/第三方插件，或依赖于 plugins中的插件\n│   │   ├── image_uploader\n│   │   └── player\n│   ├── modules\n│   │   ├── address\n│   │   ├── home\n│   │   ├── me\n│   │   ├── message\n│   │   ├── order\n│   │   ├── shop\n│   │   └── support\n│   └── plugins #插件库，自行封装的插件库，依赖于原生平台(ios/android)的代码\n│       └── printer\n├── README.md\n├── melos.yaml\n└── pubspec.yaml\n```\n\n### 运行 melos bootstrap\n\n```\nmelos bootstrap\n```\n\n### 开始编写代码\n\n在各个 package 初始化代码，如在 `packages/common/domains` 目录运行\n\n```bash\nfvm flutter create --template package .\n```\n\n## 创建壳工程\n\n新建两个壳工程，一个为 app，另外一个为 ohos_app\n\n### App 壳工程\n\n进入 `package/apps/app` 目录, 创建 app 项目，该项目为一个 App 项目，用于各平台（ios/android/mac 等， 不包含鸿蒙）打包\n\n```bash\nfvm flutter create --template app --org com.shaohushuo.flutter app\n```\n\n#### 增加依赖项\n\n修改 pubspec.yaml，添加以下内容\n\n ```yaml\n  services:\n    path: '../../common/services'\n  domains:\n    path:  '../../common/domains'\n  widgets:\n    path: '../../common/widgets'\n\n  home:\n    path: '../../modules/home'\n  me:\n    path: '../../modules/me'\n  support:\n    path: '../../modules/support'\n ```\n\n#### 安装依赖\n\n运行以下命令，安装依赖\n\n ```bash\nfvm flutter pub get\n ```\n\n### 鸿蒙壳工程\n\n#### 切换鸿蒙 Flutter SDK\n\n首先在 flutter-ohos-demo 项目根目录，将 Flutter 版本切换到鸿蒙化的版本\n\n```\nfvm use custom_3.22.0\n```\n\u003e SDK 变更以后，需要重启 IDE (或者 Dart：Restart Analysis Server)，以便让 Flutter 插件重启\n\n#### 创建 ohos_app 项目\n\n进入 packages/apps 目录，创建 ohos_app 项目\n\n```bash\nfvm flutter create --template app --platforms ohos --org com.shaohushuo.flutter ohos_app\n```\n\n#### 增加依赖项\n\n进入 packages/apps/ohos_app 目录中的 pubspec.yaml, 同样增加依赖项\n\n ```yaml\n  services:\n    path: '../../common/services'\n  domains:\n    path:  '../../common/domains'\n  widgets:\n    path: '../../common/widgets'\n\n  home:\n    path: '../../modules/home'\n  me:\n    path: '../../modules/me'\n  support:\n    path: '../../modules/support'\n ```\n\n#### 三方库鸿蒙化适配\n\n1. 如果使用了 FVM，则编辑 [pubspec.yaml](./packages/apps/ohos_app/pubspec.yaml) 文件，增加以下配置，通过 dependency_overrides 来替换鸿蒙化的三方库，注意鸿蒙化的库与原库，保持版本统一\n\n```yaml\n# 鸿蒙适配\ndependency_overrides:\n  flutter_inappwebview:\n    git:\n      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git\n      path: \"flutter_inappwebview\"\n```\n\n编辑完运行 `melos bootstrap`, 这些更新 pubspec_overrides.yaml, 在里面添加相同的 dependency_overrides 内容。\n\n\n2. 如果没有使用 FVM，则直接编辑 [pubspec_overrides.yaml](./packages/apps/ohos_app/pubspec_overrides.yaml) 文件，没有则手动创建，添加以下内容：\n\n```yaml\n# 鸿蒙适配\ndependency_overrides:\n  flutter_inappwebview:\n    git:\n      url: https://gitcode.com/openharmony-sig/flutter_inappwebview.git\n      path: \"flutter_inappwebview\"\n```\n\n编辑完运行 `flutter pub get` 安装依赖。\n\n以上两种方式执行成功后，观察 pubspec.lock 文件，可以发现，增加了类似 xxx_ohos 的插件依赖，本文中的例子为 `flutter_inappwebview_ios`\n\n3. 联合插件方式\n\n除了上面使用 dependency_overrides 来配置鸿蒙适配库的两种方式以外，如果三方插件本身使用了联合插件的形式，也可以通过下面这种方式来添加鸿蒙平台的实现：\n\n```yaml\ndependencies:\n\n  image_picker: ^1.1.2\n  image_picker_ohos:\n    git:\n      url: \"https://gitcode.com/openharmony-sig/flutter_packages.git\"\n      path: \"packages/image_picker/image_picker_ohos\"\n```\n\n这种方式称作 [\"未整合的联合插件\"](https://docs.flutter.cn/packages-and-plugins/developing-packages#non-endorsed-federated-plugin), 在上面的配置中，\nimage_picker 是一个联合插件, 这里直接使用官方社区的最新版本，观察该插件的 pubspec.yaml 的文件，通过其结构可以发现联合插件的特点, 该插件的依赖项为：\n\n```bash\ndependencies:\n  image_picker_platform_interface: ^2.10.0\n  ...\n  image_picker_android: ^0.8.7\n  image_picker_ios: ^0.8.8\n```\n\n`image_picker_platform_interface` 是一个抽象层，它定义了平台相关的接口，下面是各个平台的实现，通过拆分成包，以依赖的方式加载，那同样的原理，就可以再添加一条鸿蒙平台的实现包，就可以完成鸿蒙化适配, 也就是上面案例中的 `image_picker_ohos`：\n\n```yaml\n  image_picker_ohos:\n    git:\n      url: \"https://gitcode.com/openharmony-sig/flutter_packages.git\"\n      path: \"packages/image_picker/image_picker_ohos\"\n```\n\n\n#### 运行调试\n\n用 Deveco 打开apps/ohos_app/ohos 目录。\n\n在 Deveco 左上角 打开 File -\u003e Project Structure..., 点击 Siging Configs, 勾选 Automatically generate signature, 对鸿蒙项目签名。\n\n在 ohos_app 目录下，使用 fvm flutter run，或者点击运行按钮，运行flutter项目。\n\n## 注意事项\n\n1. melos.yaml 文件中的 `sdkPath: .fvm/flutter_sdk` 配置了 melos 使用的 flutter SDK 版本，即由FVM 配置的当前项目版本\n\n2. 每次切换 Flutter SDK 时，都会修改文件 .fvm/, vscode/settings.json 文件\n\n3. ohos_app/pubsec.yaml 中的 dependency_overrides, 仅添加需要鸿蒙化的三方库\n\n4. ohos-3.22 在 build 时，有的 har 包可能确实，建议保持 ohos-Flutter 版本最新，如果还是不行，可以考虑手动复制 har 包（使用 3.7 构建出来）\n\n如何判断三方库是否需要鸿蒙化，简而言之，如果三方库由纯 Dart 实现，则不需要单独适配，直接使用；如果三方库依赖系统底层实现，则需要鸿蒙化适配。\n\n三方库的适配情况，可以查询 Gitee/Github，或者查阅表格 [Flutter三方库适配计划](https://docs.qq.com/sheet/DVVJDWWt1V09zUFN2)\n\n5. 已知插件删除问题，如果删除插件，可能需要在ohos里面手动修改代码，移除相关依赖\n\n`ohos/oh-package.json5`\n\n## 应用截图\n\n| 首页 | 我的 | 帮助 | 播放器 |\n| ----------- | ----------- | ----------- | ----------- |\n| \u003cimg src=\"./.screenshot/image.jpeg\" width=\"200\"\u003e | \u003cimg src=\"./.screenshot/image-1.jpeg\" width=\"200\"\u003e | \u003cimg src=\"./.screenshot/image-2.jpeg\" width=\"200\"\u003e | \u003cimg src=\"./.screenshot/image-3.jpeg\" width=\"200\"\u003e |\n\n\n## 插件使用示例\n\n| 插件名 | 截图 | 使用示例 |\n| ----------- | ----------- | ----------- |\n| flutter_inappwebview | \u003cimg src=\"./.screenshot/image.jpeg\" width=\"200\"\u003e |[查看代码](./packages/modules/plugins/README.md#flutter_inappwebview) |\n| video_player |  \u003cimg src=\"./.screenshot/image-3.jpeg\" width=\"200\"\u003e |[查看代码](./packages/modules/plugins/README.md#video_player) |\n| cached_network_image |  \u003cimg src=\"./.screenshot/image-4.png\" width=\"200\"\u003e |[查看代码](./packages/modules/plugins/README.md#cached_network_image) |\n|image_picker| \u003cimg src=\"./.screenshot/image-5.jpg\" width=\"200\"\u003e  | [查看代码](./packages/modules/plugins/README.md#image_picker) |\n\n\n## 总结\n\n1. 通过 FVM 管理多个 Flutter SDK 版本，仅在鸿蒙调测打包时，切换到 ohos-flutter SDK\n2. 通过 apps 壳工程，将鸿蒙化适配的代码，尽量在 ohos_app 项目中完成。通过 pub 包管理的 `dependency_overrides` 配置，逐个替换鸿蒙化的三方库\n3. 通过 melos 管理多包项目，Flutter 项目进行模块化、组件化、插件化拆分，职责分离，平台抽象，不同平台组合打包，有效解决平台不一致问题\n\n\n## 公众号\n\n\u003e 少湖说：少胡说，多观察。\n\n\u003cimg src=\"./qrcode.png\" width=\"300\"\u003e\n\n`关注公众号，加入交流群。`\n\n## 参考资料\n\n- [鸿蒙Flutter实战：01-搭建开发环境](https://gitee.com/zacks/awesome-harmonyos-flutter/blob/master/%E9%B8%BF%E8%92%99%20Flutter%20%E5%AE%9E%E6%88%98/%E9%B8%BF%E8%92%99Flutter%E5%AE%9E%E6%88%98%EF%BC%9A01-%E6%90%AD%E5%BB%BA%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83.md)\n- [鸿蒙Flutter实战：09-现有Flutter项目支持鸿蒙](https://gitee.com/zacks/awesome-harmonyos-flutter/blob/master/%E9%B8%BF%E8%92%99%20Flutter%20%E5%AE%9E%E6%88%98/%E9%B8%BF%E8%92%99Flutter%E5%AE%9E%E6%88%98%EF%BC%9A09-%E7%8E%B0%E6%9C%89Flutter%E9%A1%B9%E7%9B%AE%E6%94%AF%E6%8C%81%E9%B8%BF%E8%92%99.md)\n- [Flutter三方库适配计划](https://docs.qq.com/sheet/DVVJDWWt1V09zUFN2)\n- [flutter-ohos-demo项目代码](https://gitee.com/zacks/flutter-ohos-demo.git)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzacksleo%2Fflutter-ohos-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzacksleo%2Fflutter-ohos-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzacksleo%2Fflutter-ohos-demo/lists"}