Flutter 开发者第一次接触鸿蒙生态时,大概率都会遇到同一个尴尬:三方库列表看着很全,但点进去“鸿蒙支持”那一栏全是灰色。这段时间我把 assets_scanner 这个媒体资源扫描库完整做了一遍鸿蒙化适配,踩了不少坑,也把整个流程跑通了。如果你正在做 Flutter 插件鸿蒙化,或者准备在鸿蒙设备上实现自动化扫描类功能,这篇文章应该能帮你省下不少排查时间。
assets_scanner 在 Flutter 社区里的定位很明确:帮你扫描设备里的图片、视频、音频,返回带元数据的资源列表,避免手写一堆原生代码。它原本的 Android 端靠 MediaStore,iOS 端靠 Photos 框架,逻辑成熟、接口清晰。但要让它在鸿蒙上跑起来,不能只改 Dart 层,必须把原生 API 换成 ArkTS 能调用的鸿蒙媒体库接口,这就是鸿蒙化适配的核心工作。
这篇文章会从方案选型开始,讲清楚为什么优先选择 federated plugin 结构,然后逐步拆解鸿蒙侧权限、媒体资源 API、平台通道注册和数据模型转换,最后给你一份可直接参考的实现和排障清单。文章里的代码我尽量给全,但鸿蒙 SDK 迭代很快,实际落地时请以你本地 SDK 的 API 说明为准。
1. 项目概览与鸿蒙化方案选型
1.1 assets_scanner 到底解决什么问题
做管理类 App、相册应用、内容审核工具,甚至聊天软件里的图片选择器,都绕不开一件事:把系统媒体库里用户的可视资源读出来,再按类型、时间、文件大小去筛选。你可能会说,这不就是一个系统接口的事吗?真正动手才发现,Android 上要处理运行时权限、MediaStore 的行为差异,不同品牌的 ROM 还会阉割返回字段;iOS 上则要考虑相册权限分级的复杂度。assets_scanner 这类库存在的意义,就是把这些原生差异封装成一套统一的 Dart 接口,让你不用在平台通道里反复搬运代码。
在不同平台上,同一个“媒体资源”模型的含义并不完全一致。Android 的 MediaStore 里有 _ID、DATA、SIZE、MIME_TYPE 这些字段;iOS 的 PHAsset 则有 localIdentifier、pixelWidth、duration。assets_scanner 把这些统一成类似 AssetEntity 的数据结构,业务侧拿到的就是一个纯净的 Flutter Model。鸿蒙化要做的事,本质上就是把这个 AssetEntity 的数据源,从 Android/iOS 原生实现替换成鸿蒙的媒体库查询结果。
我实际在做的时候发现,最花时间的不在查询本身,而在数据模型的含义对齐。鸿蒙资源对象的 media_type 字段取值、URI 前缀、日期字段单位,都跟 Android 不一致。如果不先梳理清楚,后面写转换层时就会反复返工。
1.2 鸿蒙化适配的三种路线与最终选择
确定要支持鸿蒙之后,摆在面前的无非是三条路,我用一张对比表把你的选项理清楚:
| 方案 | 做法 | 优点 | 缺点 |
|---|---|---|---|
| 直接改原库源码 | 在原作者仓库上新增鸿蒙平台实现 | 改动直观,收拢在一个工程里 | 污染上游代码,后续升级原库很痛苦 |
| 新建独立适配库 | 不碰原库,维护一个 assets_scanner_harmonyos 包 |
职责清晰,按需引入 | 需要处理接口对齐问题 |
| Federated Plugin | 原库拆成接口层和各平台实现包 | 官方推荐,接入体验最平滑 | 改动幅度最大,需要理解整套机制 |
两条常规路线在前,但最终我选了 Federated Plugin。核心原因不是“看起来更专业”,而是它把一个插件的“对外 API”和“平台实现”彻底拆开了。assets_scanner 继续保留原有 API 不动,鸿蒙专属实现放到一个独立实现包里。这样做的好处非常实际:上游插件更新时,接口层同步升级即可,我的鸿蒙实现包只要适配对应接口版本,不需要再 fork 一份源码维护。
如果你只是在内部项目里应急用,直接改原库源码倒也不是不行。但一旦库要发布、要长期维护,或者未来还要支持更多平台,Federated Plugin 这种“接口归接口、实现归实现”的思路,确实更符合工程化的要求。鸿蒙生态现在处于快速演进期,接口版本经常动,把平台实现隔离出去,以后升级 SDK 时影响面会小很多。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 鸿蒙侧媒体资源能力与权限体系拆解
2.1 新老 API:mediaLibrary 与 photoAccessHelper 的选型对比
鸿蒙的媒体资源 API 经历过一次明显的代际更替。早期版本里常见的是 @ohos.multimedia.mediaLibrary,提供 getMediaLibrary、FileKey、FetchOptions 这一套接近 Android 查询风格的接口。从 API 12 左右开始,官方开始主推 photoAccessHelper,配合 PhotoAccessHelper.FetchOptions 来查询。5.0 之后,新的思路更倾向于用 PhotoViewPicker 这类独立选择器,配合直接文件访问接口,而不是把整个媒体库一次性铺开。
typescript复制// 老 API 风格(示意)
import mediaLibrary from '@ohos.multimedia.mediaLibrary';
let media = mediaLibrary.getMediaLibrary(context);
let fileKey = mediaLibrary.FileKey;
let fetchOp = {
selections: `${fileKey.MEDIA_TYPE} = ?`,
selectionArgs: [mediaLibrary.MediaType.IMAGE.toString()]
};
typescript复制// 新 API 风格(示意)
import { photoAccessHelper } from '@kit.MediaLibraryKit';
let phAccessHelper = photoAccessHelper.getPhotoAccessH
