开头先说句实在话:Flutter 开发这行,鸿蒙适配这件事迟早躲不开。尤其是手上项目用了一堆三方插件,真到了要把应用跑到鸿蒙设备上的时候,第一个卡点往往不是 UI 框架适配,而是这些底层读系统能力的插件根本不认识鸿蒙。assets_scanner 就是这么个典型,它在 Android 和 iOS 上帮你扫描相册、媒体库、拿缩略图,干得挺欢;但到了鸿蒙侧,没有原生实现,MethodChannel 往底层一调,直接黑屏报 MissingPluginException。
这篇东西不是给你讲概念,是把我把 assets_scanner 往鸿蒙上移植的完整过程拆给你看。从插件工程怎么搭、鸿蒙媒体库 API 怎么对接、缩略图怎么拿,到权限配置和一堆踩坑记录,全都记录在案。适合正在做 Flutter 鸿蒙化改造的兄弟参考,也适合那些想搞明白 Flutter 插件在鸿蒙上到底怎么工作的朋友。
1. 先搞清楚 assets_scanner 的底细和鸿蒙化目标
1.1 assets_scanner 到底解决什么问题
assets_scanner 在 Flutter 生态里的定位很简单:给应用提供系统媒体资源的扫描能力。开发者调用它,能从设备上拉出图片、视频、音频的资源列表,并且拿到每个资源的类型、宽高、时长、大小、创建时间这些元数据。它最常见的落地场景是相册选择器、自研图片管理模块、或者需要在应用里做自动化资源索引的工具。
它跨平台的工作方式,本质上就是标准的 Flutter 插件机制:Dart 侧定义好接口,底层通过 MethodChannel 调用 Android 的 MediaStore、iOS 的 PHAsset 来实现真正的系统访问。也就是说,这个库能跑,是因为它的原生侧各个平台都实现了。鸿蒙没有原生侧实现,它就动弹不得。
1.2 为什么在鸿蒙上不能直接用
鸿蒙系统,尤其是 HarmonyOS NEXT 以及 OpenHarmony 分支,对系统媒体库的访问方式跟 Android 完全不一样。Android 走的是 ContentResolver + MediaStore,iOS 走的是 Photos Framework,鸿蒙用的是自家 PhotoAccessHelper 这套 API。你不可能把一个写好的 Android 原生插件模块直接塞进鸿蒙工程里运行,类都不存在。
另外,鸿蒙上的 Flutter 引擎也不是标准 Flutter 官方发行版直接跑的,而是基于 OpenHarmony SIG 维护的 Flutter 分支。这个分支提供了一套鸿蒙侧的 FlutterPlugin、MethodChannel 等对应实现,API 跟官方 Flutter 原生侧长得像,但命名空间、依赖方式、注册流程又是另一套。所以鸿蒙化适配不是简单改几个方法名,而是要单独在鸿蒙工程里写一个 FlutterPlugin 实现,把 Dart 侧传过来的每个方法都接住,再翻译成鸿蒙媒体库的操作。
1.3 鸿蒙化适配的总体路线
我的做法分三层:
- 第一层,Dart 侧不动或者微调。assets_scanner 的 Dart 接口对上层暴露的本来就是统一的,我们只需要保证鸿蒙原生侧返回的数据结构跟 Dart 侧期望的一致,上层页面代码基本可以零改动。
- 第二层,鸿蒙原生侧实现对应的方法通道。照着 assets_scanner 在 Android 侧的方法清单,在鸿蒙工程里逐个实现 scanAssets、获取缩略图、读取文件字节等方法。
- 第三层,处理好鸿蒙平台本身的差异。比如权限模型、生命周期、缩略图解码方式这些跟 Android 不同的地方,需要在适配时单独处理。
这套路线最大的好处是:改造边界清晰,Dart 层业务代码不动,风险被控制在原生桥接这一层。就算以后鸿蒙媒体库 API 升级,也只需要改鸿蒙侧模块。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 搭建鸿蒙侧 Flutter 插件工程
2.1 环境选型和版本对齐
鸿蒙 Flutter 开发环境跟标准 Flutter 不太一样,第一件事就是把工具链对齐。
我用的是 DevEco Studio 作为鸿蒙侧 IDE,然后拉取 OpenHarmony 的 flutter_flutter 分支作为 Flutter SDK。这个分支通常需要手动配置,不能直接用 flutter 官方命令行工具下载的 SDK 来跑鸿蒙设备。建议拿到跟你的鸿蒙设备 SDK 版本匹配的分支,别最新版一通乱试,容易碰一鼻子灰。
版本匹配这块我遇到过一个实际情况:Flutter 侧的 DCOM 组件版本、鸿蒙侧的 ohos SDK 版本、以及 flutter_flutter 分支的版本,三者必须维持一套能互相认可的对应关系。否则最常见的结果就是 Flutter 工程能编译,但跑到鸿蒙设备上 engine 加载失败,甚至 build 阶段直接报版本校验错误。稳妥的做法是直接参考 OpenHarmony-SIG 仓库里 README 列出的版本组合,照抄一份。
2.2 插件工程结构长什么样
一个支持鸿蒙的三方 Flutter 插件,目录一般长这样:
code复制assets_scanner/
├── lib/ # Dart 实现
├── android/ # Android 原生
├── ios/ # iOS 原生
└── harmony/ # 鸿蒙原生
├── entry/
│ └── src/main/
│ ├── ets/
│ │ ├── plugin/
│ │ │ └── AssetsScannerPlugin.ets
│ │ └── utils/
│ └── module.json5
├── build-profile.json5
└── oh-package.json5
关键点在于 harmony 目录下的 entry 模块。它可以被理解为一个独立的鸿蒙应用模块,但里面要引入 Flutter 引擎依赖,并把插件对象暴露给 Flutter 侧。
oh-package.json5 里需要声明依赖框架包,一般会引入 @ohos/flutter_ohos 这类依赖,具体名称取决于你拉取的 flutter_flutter 分支产物。插件本身作为一个 Purple package,因为最终是宿主应用把整个 Flutter 引擎跑起来,所以你在做验证时,往往要建一个壳工程,同时引用 Flutter 模块和这里的 harmony 插件模块。
2.3 注册入口:让 Flutter 引擎找到原生实现
鸿蒙侧插件必须实现 FlutterPlugin 接口,并在 onAttachToEngine 时机注册方法通道。这一步相当于是告诉引擎:Dart 侧发来的 “flutter/assets_scanner” 这个通道上的所有调用,都由我来处理。
插件类的骨架大概是这样的:
``
