Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 flutter_media_metadata

晚烛

88人浏览 · 2026-10-17 20:33:55

晚烛 · 2026-10-17 20:33:55 发布

Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 flutter_media_metadata

音乐播放器要显示歌名、专辑、封面，视频应用要提取时长与码率——媒体元数据是播放类应用的基础数据。flutter_media_metadata 从音视频文件提取完整的元数据模型。把它带到鸿蒙时，媒体解析能力是适配目标。

本文以 flutter_media_metadata 1.0.0+1 为例，记录我如何保留原有 Dart API、补齐 Flutter OH 插件入口、在鸿蒙端接入真实系统能力，并在 HarmonyOS API 26 真机上完成构建、安装、启动和按钮调用验证。

适配仓库： oh-flutter/flutter_media_metadata

适配分支： feat/ohos_flutter_media_metadata_1.0.0+1

适配 TAG： 1.0.0+1-ohos.2

一、先看最终效果

在这里插入图片描述

图 1：HarmonyOS API 26 真机启动 Demo。页面显示 flutter_media_metadata 1.0.0+1。

在这里插入图片描述

图 2：点击“读取媒体元数据”后返回真实时长 duration = 2000000 微秒（2 秒测试音频），字段来自 AVMetadataExtractor。

验证点	实测结果	证据
Flutter OH 3.47 工程构建	通过	`entry-default-signed.hap`
安装、启动（真机）	通过	图 1
`MetadataRetriever.fromFile`	解析出真实时长（2.0 秒）	图 2
元数据	`AVMetadataExtractor`	图 2

二、这个库原来是怎么工作的

flutter_media_metadata 的接口是单方法 + 富模型：

Dart MetadataRetriever
  -> MethodChannel('flutter_media_metadata')
  -> Android MediaMetadataRetriever / FFmpeg（桌面）
  -> MetadataRetriever(file) 返回 Metadata 模型

返回的 Metadata 模型包含 trackName、trackArtistNames、albumName、trackDuration、albumArt 等近 20 个字段。

三、实际环境

Flutter 鸿蒙环境搭建不在本文重复展开，直接参考 Flutter OH 环境搭建指南。

组件	版本
Flutter OH	`3.47.4-ohos-1.0.4`
Dart	`3.13.3`
DevEco Studio	`26.0.0 Release`
HarmonyOS SDK	API 26
测试设备	华为畅享 90 Pro Max，HarmonyOS `7.0.0.105`（API 26）
目标库	`flutter_media_metadata 1.0.0+1`

flutter --version
hdc list targets

四、确认上游版本并同步到 AtomGit

仓库初始适配提交为 dd8a9f1，完成后分支最新提交为 dd8a9f1。

git clone https://atomgit.com/oh-flutter/flutter_media_metadata.git
cd flutter_media_metadata
git switch feat/ohos_flutter_media_metadata_1.0.0+1
git log --oneline -5

五、创建适配分支并检查工程结构

git switch -c feat/ohos_flutter_media_metadata_1.0.0+1

关键目录如下：

flutter_media_metadata/
├── lib/                                        # 原有 Dart API 和 MethodChannel
├── ohos/
│   ├── index.ets                               # OHOS 插件导出入口
│   └── src/main/ets/components/plugin/
│       └── FlutterMediaMetadataPlugin.ets                           # 通道实现
├── example/lib/main.dart                        # 真机验证 Demo
├── example/ohos/                                # Flutter OH 宿主工程
├── pubspec.yaml                                # 声明 ohos 平台
└── README.OpenHarmony_CN.md                    # 鸿蒙适配说明

pubspec.yaml 中的关键声明是：

flutter:
  plugin:
    platforms:
      ohos:
        pluginClass: FlutterMediaMetadataPlugin

pluginClass 必须和 ohos/index.ets 导出的类名一致，否则 Dart 端能编译，运行时却不会注册插件。

六、适配过程：注册通道并对齐语义

const extractor = await media.createAVMetadataExtractor();
extractor.fdSrc = { fd: file.fd };
const metadata = await extractor.fetchMetadata();
// duration 是秒（字符串），Dart 侧要毫秒
const trackDurationMs = Math.round(Number(metadata.duration) * 1000);

字段	映射
`title` / `artist` / `album`	`trackName` / `trackArtistNames` / `albumName`
`duration`（秒）	`trackDuration`（毫秒）
`sampleRate`	`bitrate`
`albumArt`	保持 null（鸿蒙无封面提取接口）

七、构建配置与签名

示例工程的目标 SDK 对齐到 26，与 @ohos/flutter_ohos 的最低要求一致：

{
  "name": "default",
  "compatibleSdkVersion": "26.0.0",
  "targetSdkVersion": "26.0.0",
  "runtimeOS": "HarmonyOS"
}

Demo 的 AppScope/app.json5 统一成 com.example.flutter_oh_demo，与 DevEco 调试签名对应。证书、p12、p7b 和密码没有提交到仓库，读者应在自己的 DevEco Studio 中生成调试签名。

八、通过 AtomGit 引入适配版

在另一个 Flutter OH 应用中使用时，建议锁定 TAG：

dependencies:
  flutter_media_metadata:
    git:
      url: https://atomgit.com/oh-flutter/flutter_media_metadata.git
      ref: 1.0.0+1-ohos.2

flutter pub get

然后在 pubspec.lock 检查 source: git、AtomGit 地址和 resolved-ref，确认没有解析到 pub.dev 的同名版本。

九、构建、安装和真机验证

cd example
flutter pub get
flutter analyze
flutter build hap --debug
hdc install -r build/ohos/hap/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.flutter_oh_demo

构建输出为 ✓ Built build/ohos/hap/entry-default-signed.hap.，随后 hdc 报告安装成功并启动 Ability。真机上按本文的截图顺序逐一点击按钮完成验证。