Flutter插件鸿蒙化适配实践：以assets_scanner媒体扫描库为例

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 鸿蒙化适配的三种路线与最终选择

确定要支持鸿蒙之后，摆在面前的无非是三条路，我用一张对比表把你的选项理清楚：

两条常规路线在前，但最终我选了 Federated Plugin。核心原因不是“看起来更专业”，而是它把一个插件的“对外 API”和“平台实现”彻底拆开了。assets_scanner 继续保留原有 API 不动，鸿蒙专属实现放到一个独立实现包里。这样做的好处非常实际：上游插件更新时，接口层同步升级即可，我的鸿蒙实现包只要适配对应接口版本，不需要再 fork 一份源码维护。

如果你只是在内部项目里应急用，直接改原库源码倒也不是不行。但一旦库要发布、要长期维护，或者未来还要支持更多平台，Federated Plugin 这种“接口归接口、实现归实现”的思路，确实更符合工程化的要求。鸿蒙生态现在处于快速演进期，接口版本经常动，把平台实现隔离出去，以后升级 SDK 时影响面会小很多。

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.getPhotoAccessHelper(context);
let fetchOptions = new photoAccessHelper.FetchOptions();
fetchOptions.fetchKey = photoAccessHelper.PhotoKey.URI;
let fetchResult = await phAccessHelper.getAssets(fetchOptions);
let assets = await fetchResult.getAllObjects();

这里有一个很关键的取舍：我最终用的是 photoAccessHelper，原因不只是新老替代的关系。老 API 的 FileKey.MEDIA_TYPE 虽然也能筛出图片，但返回字段的丰富程度和后续扩展性都不如新 API。另一个重要因素是鸿蒙官方对 API 的演进态度很明确，老接口处于冻结维护状态，新功能都往 photoAccessHelper 上堆。从适配工程角度看，选新 API 至少能保证未来两三个版本内不用推倒重来。

当然，photoAccessHelper 也不是没有坑。它的 getAssets 返回的是 FetchResult，里面是 PhotoAsset 对象集合，而不是你熟悉的文件路径。要拿真实文件内容或缩略图，往往还得配合 fileIo 和 AVImageGenerator 这类组件。所以适配层不能只查一次列表，还要考虑缩略图的生成方式。

2.2 权限声明和动态授权流程

鸿蒙的权限模型和 Android 很像，但在声明时机和授权弹窗行为上有自己的规则。你要在 module.json5 的 requestPermissions 里配置权限，然后在运行时用 abilityAccessCtrl 请求用户授权。

json复制{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_IMAGEVIDEO"
      },
      {
        "name": "ohos.permission.READ_AUDIO"
      }
    ]
  }
}

这里必须注意，鸿蒙的媒体权限按资源类型拆分得比较细。图片视频共用一个 READ_IMAGEVIDEO，音频单独一个 READ_AUDIO。如果你的 assets_scanner 只做图片和视频，那就别把音频权限也写上，否则审核阶段容易被质疑权限滥用。

运行时动态申请的标准流程是这样：

typescript复制import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';

let atManager = abilityAccessCtrl.createAtManager();
let permissions: Array<Permissions> = ['ohos.permission.READ_IMAGEVIDEO'];
let requestResult = await atManager.requestPermissionsFromUser(context, permissions);

我第一次跑通时就是在这里栽了跟头：只声明了权限，没有处理用户拒绝后的分支逻辑。用户一旦点了拒绝，后续媒体查询会直接返回空列表，而 Flutter 侧完全不知道发生了什么。所以鸿蒙适配层里，权限请求结果一定要显式抛回 Dart 侧，给业务方一个明确的状态，而不是静默失败。

3. 实操：完整跑通 assets_scanner 的鸿蒙适配

3.1 工程结构与 federated plugin 布局

鸿蒙化适配的第一步不是写代码，而是搭好工程骨架。在 Federated Plugin 结构下，我把工程拆成了两层。第一层是原来的 assets_scanner，保留它已有的 AssetsScanner 公开 API 和抽象接口；第二层是新建的 assets_scanner_harmonyos，负责实现鸿蒙平台的扫描逻辑。

text复制assets_scanner/
├── lib/
│   ├── assets_scanner.dart
│   ├── assets_scanner_interface.dart
│   └── assets_scanner_platform.dart
├── android/
├── ios/
└── harmonyos/
    └── assets_scanner_harmonyos/
        ├── lib/
        │   └── assets_scanner_harmonyos.dart
        └── ohos/
            ├── entry/
            │   └── src/main/
            │       ├── module.json5
            │       └── ets/
            │           └── plugins/
            │               └── AssetsScannerPlugin.ets
            └── pubspec.yaml

在 assets_scanner_harmonyos/pubspec.yaml 里声明插件实现关系，这是 Federated Plugin 的关键配置。字段写法类似这样：

yaml复制flutter:
  plugin:
    implements: assets_scanner
    platforms:
      ohos:
        package: com.example.assets_scanner_harmonyos
        pluginClass: AssetsScannerPlugin
        dartPluginClass: AssetsScannerHarmonyosPlugin

这里有个容易踩的细节：dartPluginClass 和 pluginClass 是两套不同的注册入口。pluginClass 让鸿蒙原生侧能定位到 ArkTS 插件类，dartPluginClass 则是让 Flutter 引擎在纯 Dart 侧就能完成平台分发。如果你只是想复用 MethodChannel 做通信，可以不设 dartPluginClass，直接从 Dart 侧通过 MethodChannel('assets_scanner/scan') 发起调用。我的做法是两边都保留了入口，方便后续扩展 Pigeon 代码生成。

3.2 平台通道注册与 Dart 侧改造

平台通道是整个适配的“神经中枢”。Dart 侧继续沿用原有的 MethodChannel 协议，但鸿蒙原生侧需要用 ArkTS 注册一个同名 Channel 的处理器。

dart复制// Dart 侧核心方法
class AssetsScannerHarmonyosPlugin extends AssetsScannerPlatform {
  static const MethodChannel _channel = MethodChannel('assets_scanner/scan');

  @override
  Future<List<AssetEntity>> scanAssets(AssetType type) async {
    final list = await _channel.invokeListMethod<Map<Object?, Object?>>(
      'scanAssets',
      {'type': type.name},
    );
    return list
        .map((e) => AssetEntity.fromJson(Map<String, dynamic>.from(e)))
        .toList();
  }
}

ArkTS 侧对应注册代码：

typescript复制import { FlutterPlugin, MethodChannel, FlutterPluginBinding } from '@ohos/flutter_ohos';

export class AssetsScannerPlugin implements FlutterPlugin {
  private channel: MethodChannel | null = null;

  onAttachedToEngine(binding: FlutterPluginBinding): void {
    this.channel = new MethodChannel(binding.getBinaryMessenger(), 'assets_scanner/scan');
    this.channel.setMethodCallHandler({
      onMethodCall: (call, result) => {
        if (call.method === 'scanAssets') {
          this.handleScan(call.arguments, result);
        }
      }
    });
  }
}

写这段代码时，我的一个经验是：参数名和返回值类型一定要和 Dart 侧严格对齐，否则会在运行时收到格式转换异常。尤其 Map 的 value 类型，鸿蒙 ArkTS 是强类型语言，Object 和 Object? 的差别都能让整个通道静默失败。

3.3 图片、视频、音频三类资源的扫描实现

扫描逻辑本身并不复杂，无非是 media_type 的筛选。但鸿蒙的 media_type 取值和 Android 不一样，这点必须单独封装一层映射，不要指望直接复用 Android 代码。

ArkTS 扫描核心逻辑：

typescript复制private async handleScan(args: any, result: any): Promise<void> {
  try {
    const type = args['type'] as string;
    let mediaType: number;
    if (type === 'image') {
      mediaType = 1;
    } else if (type === 'video') {
      mediaType = 3;
    } else {
      mediaType = 2;
    }

    const fetchOptions = new photoAccessHelper.FetchOptions();
    fetchOptions.fetchKey = photoAccessHelper.PhotoKey.URI;
    fetchOptions.fetchColumn = [
      'uri',
      'media_type',
      'display_name',
      'size',
      'date_added',
      'width',
      'height',
      'duration'
    ];
    fetchOptions.selections = `media_type = ?`;
    fetchOptions.selectionArgs = [mediaType.toString()];

    const fetchResult = await this.phAccessHelper.getAssets(fetchOptions);
    const assets = await fetchResult.getAllObjects();
    result.success(this.toDartJsonList(assets));
  } catch (err) {
    result.error('scan_failed', JSON.stringify(err), null);
  }
}

有一点我必须强调，getAssets 里如果传入的 fetchColumn 包含不存在的字段，某些 SDK 版本会抛异常。最稳妥的做法是先只取 uri 和 media_type，其他字段在拿到 PhotoAsset 对象后再逐字段读取。你可能会问，为什么不能全部在 fetch 阶段搞定？因为鸿蒙的媒体库返回字段在部分低版本上有兼容问题，与其跟 SDK 斗智斗勇，不如在转换层做容错。

3.4 数据模型转换：鸿蒙对象到 Dart 对象

这是整个适配里最“琐碎但关键”的一步。我们最终要把 PhotoAsset 转成 Dart 侧 AssetEntity 能解析的 JSON 结构。

typescript复制private toDartJsonList(assets: Array<photoAccessHelper.PhotoAsset>): Array<Object> {
  return assets.map((asset) => {
    const duration = asset.duration ?? 0;
    return {
      'id': asset.uri,
      'uri': asset.uri,
      'type': asset.mediaType === 1 ? 'image' : asset.mediaType === 3 ? 'video' : 'audio',
      'displayName': asset.displayName ?? '',
      'size': asset.size ?? 0,
      'width': asset.width ?? 0,
      'height': asset.height ?? 0,
      'duration': duration
    };
  });
}

这里我特别用了 asset.uri 作为 id，而没有找单独的 id 字段。鸿蒙的 PhotoAsset 在不同版本上暴露主键的方式不统一，uri 反而是最稳定的唯一标识。Dart 侧如果期望的是自增整数 ID，那你就要在适配层做一层映射表，但不能依赖跨进程持久化。我的经验是，直接用 URI 作为业务 ID 最容易保持一致性。

Dart 侧还应该做好字段兜底：

dart复制factory AssetEntity.fromJson(Map<String, dynamic> json) {
  return AssetEntity(
    id: json['id'] ?? '',
    uri: json['uri'] ?? '',
    type: _parseType(json['type']),
    displayName: json['displayName'] ?? '',
    size: json['size'] ?? 0,
    width: json['width'] ?? 0,
    height: json['height'] ?? 0,
    duration: json['duration'] ?? 0,
  );
}

不要假设鸿蒙每次返回都带全字段，null 的情况比想象中多。例如某些音频文件就没有 width 和 height，某些视频的 duration 字段可能为 0。Dart 侧的空安全兜底做得好，线上崩溃率会明显降低。

3.5 分页、排序与缩略图增强

如果你只是演示 Demo，一次性把几千条资源全部读出来没问题。但真实业务里，一次 getAllObjects() 拉回 5000 张图片会让 Flutter 侧瞬间卡顿，还会撑爆内存。所以适配层必须考虑分页。

鸿蒙的 FetchResult 支持游标式的分段取数：

typescript复制const count = fetchResult.getCount();
const pageSize = 200;
let start = 0;
while (start < count) {
  const pageAssets = await fetchResult.getObjectsByOffset(start, pageSize);
  // 转换并返回给 Dart 层
  start += pageSize;
}

Dart 侧可以配合 Stream 或一次请求一个 page 参数来做自动加载更多。我个人更推荐在 Dart 侧暴露一个 scanAssetsPaged 的增量接口，让业务侧用列表滚动的时机去加载下一页，而不是一次性把所有数据推到 UI 层。

缩略图是另一个绕不开的话题。原版 assets_scanner 在 Android/iOS 上会把缩略图也一并处理掉，给业务侧返回本地缓存路径。鸿蒙上这一步不能直接用原来的图片加载库，我推荐用 AVImageGenerator 从视频里取帧，用文件 IO 直接读图片字节，然后再交给 Flutter 侧缓存。缩略图生成的密度也要控制好，适配层应该在请求参数里允许业务侧指定想要的尺寸，避免每次都生成原图比例的缩略图。

4. 常见问题与排查技巧实录

4.1 权限拒绝或授权结果回调无反应

这是适配鸿蒙插件时遇到最多的问题，通常有三个表现：回调一直不触发、拒绝之后二次请求无效、首次弹窗出现但 Flutter 侧收不到结果。

首先检查 module.json5 里的权限是否有拼写错误，权限名是区分大小写的。其次，鸿蒙在部分版本上对同一权限的多次请求有节流行为，用户如果连续点击拒绝，系统可能在一段时间内直接默认拒绝。我的处理方式是在 Flutter 层做一个前置的引导弹窗，明确告诉用户“为什么要访问相册”，用户在知情后再点授权，成功率会高很多。

另外一个隐蔽坑：如果你在插件代码里请求权限，但传入的 context 不是当前 UIAbility 的上下文，授权弹窗可能不会达到前台。始终优先用 getContext() 获取绑定到 Activity/Stage 的上下文，不要在全局静态方法里去捞。

4.2 扫描结果为空或字段缺失

权限没问题但扫描结果为空，这种问题最容易让新手迷惑。先确认你是否真的往鸿蒙设备里塞了对应类型的媒体文件，模拟器里经常是空的。接着看 fetchOptions 的 selections 拼接是否正确，尤其是 selectionArgs 的类型是字符串数组，数字必须转成字符串。

字段缺失的问题，多半出在 fetchColumn 和 getAssets 的配合上。我实测下来，width 和 height 在某些版本的 PhotoAsset 上需要先从 URI 打开文件才能拿到，而不是查询阶段就返回。所以转换层要做二次兜底：如果 asset.width 为空，可以通过 fileIo.openSync(uri) 拿到文件描述符再获取宽高，但不要对每个资源都这么干，否则性能会急剧下降。

4.3 内存增长与列表卡顿

扫描五千张图片，列表 RecyclerView 风格滑动不卡几乎不可能。常见原因有两个：Dart 侧一次性接收了过大的 JSON 列表；或者鸿蒙侧把每个资源的原图信息都加载了。

针对第一个原因，用分页接口替代一次性全量接口是必须的。针对第二个原因，鸿蒙的 PhotoAsset 本身是轻量对象，但 thumbnail 的生成会带来明显的内存开销。如果业务侧只需要展示缩略网格，就在适配层限制生成缩略图的数量，并且用 LRU 缓存管理图片字节。Flutter 侧也可以参考 ImageCache 的 width 参数限制解码尺寸，不要拿原图尺寸去解码一个 200x200 的头像位。

4.4 插件在鸿蒙 Release 包中未注册

Debug 模式下一切正常，一打 Release 包就找不到平台实现。这个问题在鸿蒙 Flutter 开发里非常典型，开发环境和发布环境的构建流程有差异，插件注册逻辑不一定被完整带入。

最直接的排查方式是查看最终产物里是否包含 AssetsScannerPlugin 相关的代码。如果确认被打掉了，多半是插件声明配置有问题，比如 pluginClass 和实际 ArkTS 类入口不匹配。还有一些时候是因为代码混淆配置把插件类重命名了，要在混淆规则里把插件类加入白名单。我的习惯是，每做完一个平台的 Release 验证，就第一时间把混淆规则和插件配置文件固化到文档里，不然过两周自己都会忘。

4.5 版本兼容：API 12 与旧 API 的适配策略

鸿蒙各个设备系统版本跨度大，同一套代码在不同版本上的表现可能截然不同。API 12 以前，photoAccessHelper 还不完善，老设备上得回退到 mediaLibrary；API 12 以后，mediaLibrary 的部分接口又会被标记废弃。处理这种兼容问题，最好的办法是在适配层内部做一次能力检测，在运行时判断 SDK 版本，再决定走哪套查询逻辑。

typescript复制if (canIUse('SystemCapability.Multimedia.PhotoAccessHelper')) {
  // 走 photoAccessHelper 新逻辑
} else {
  // 走 mediaLibrary 旧逻辑
}

这种动态路由的方式，比一次性绑定某个 API 要稳得多。只要你把新旧两套查询结果都统一到 toDartJsonList 这一个出口，上层业务就完全无感知。

5. 适配完成后的验证经验与工程化建议

5.1 测试矩阵与真机验证要点

适配完成不等于功能可用，媒体库这种东西必须靠真机验证。我建议至少准备下面三组设备：API 12 以上新版本设备、API 10 左右的旧版本设备、不带真摄像头的平板设备。测试用例不要只看“能扫出图片”这一条，每一类都要单独验证：

• 图片资源：横向、纵向、超宽全景图、带 EXIF 的图片、无权限下的空数据
• 视频资源：视频时长字段、缩略图生成、超大视频文件是否卡死
• 音频资源：无封面音频、带封面的音频、录音文件

另一个容易忽略的验证点是“资源变化后的增量”。用户拍照、截图、卸载重装后权限重置，这些行为都会影响扫描结果。适配层最好提供一个类似 clearCache 或 rescan 的接口，让业务侧能够主动刷新。

5.2 从 assets_scanner 到其他 Flutter 三方库的鸿蒙化思路

assets_scanner 的鸿蒙化适配不是一个孤例。Flutter 生态里有大量依赖原生 API 的三方库，最终都会面临同样的问题。做了一轮之后，我把这套思路沉淀成了通用方法：

• 第一步，在原生 API 层面找对应能力，鸿蒙官方文档里的 Server 能力和媒体能力基本覆盖了 Android/iOS 的大部分场景。
• 第二步，梳理数据结构映射。这一步要特别留意 long、double、Map 等类型在平台通道两端的表示差异。
• 第三步，先跑通最小可用的 MethodChannel，再补分页、缓存、缩略图等增强能力。不要一开始就追求完整参数对齐。

这个过程里，我认为最重要的一点就是保持“接口优先级”的思考方式。先定义清楚 Dart 侧希望看到什么，再去反向调研鸿蒙 API 是否能提供，而不是先看鸿蒙能做什么，再决定 Dart 侧削足适履。把接口层稳住了，不管底层 API 怎么换，你的插件都能活得很久。

最后再分享一个小体会

这次适配做下来，我最深的感触是：鸿蒙化 Flutter 插件这个事，真正的难度不在写代码，而在对“平台能力差异”的理解。assets_scanner 的每次查询背后，都是系统媒体库在替你组织数据、管理权限、回收资源。适配层要做的不是把鸿蒙的 API 翻译成 Dart 调用，而是用业务能理解的语言，把这些底层动作重新表达出来。你在做其他插件适配时，也建议先想清楚这两个问题：你的库到底面向哪类业务，鸿蒙侧能不能用更简洁的方式做到同样效果。方向对了，后面所有步骤都只是执行。