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

晚霞的不甘

15人浏览 · 2026-10-17 19:56:34

晚霞的不甘 · 2026-10-17 19:56:34 发布

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

相册写入是社交、电商、相机类应用的高频需求。Android 侧要处理 MediaStore 与分区存储，iOS 侧要处理 PHPhotoLibrary 的权限模型。gal 把两端差异封装成一组简单 API，还内置了权限检查与请求。把它带到鸿蒙时，第一步同样是弄清鸿蒙的媒体库写入能力边界。

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

适配仓库： oh-flutter/gal

适配分支： feat/ohos_gal_2.3.3

适配 TAG： 2.3.3-ohos.2

一、先看最终效果

图 1：HarmonyOS API 26 真机启动 Demo。页面显示 gal 2.3.3，状态为等待操作。

图 2：点击“检查相册权限”后返回 hasAccess → true，确认式保存链路无需常驻相册权限。

图 3：点击“保存图片到相册”后返回 putImage 已保存 gal_demo_image.png——系统确认式保存把沙箱文件写入了媒体库。

验证点	实测结果	证据
Flutter OH 3.47 工程构建	通过	`entry-default-signed.hap`
安装、启动（真机）	通过	图 1
`hasAccess` / `requestAccess`	返回 `true`	图 2
`putImage`	系统确认框 → 写入图库，返回媒体 URI	图 3
相册写入	已接入 `photoAccessHelper` 确认式保存	图 3

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

gal 的公共入口是静态类 Gal，通过名为 gal 的 MethodChannel 与原生端通信：

Dart Gal
  -> MethodChannel('gal')
  -> Android MediaStore / iOS PHPhotoLibrary
  -> 保存结果或权限状态

它的 API 面很聚焦：hasAccess 查权限、requestAccess 请求权限、open 打开相册应用、putImage / putImageBytes / putVideo 写文件。鸿蒙端本次保留全部方法，权限与写入的调用入口用准确的否定值回答。

三、实际环境

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）
目标库	`gal 2.3.3`

flutter --version
hdc list targets

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

仓库适配提交为 defaad9，分支与 TAG 2.3.3-ohos.2 均指向该提交。

git clone https://atomgit.com/oh-flutter/gal.git
cd gal
git switch feat/ohos_gal_2.3.3
git log --oneline -5

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

git switch -c feat/ohos_gal_2.3.3

关键目录如下：

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

pubspec.yaml 中的关键声明是：

flutter:
  plugin:
    platforms:
      ohos:
        pluginClass: GalPlugin

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

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

// 用户确认式保存：把沙箱文件写进系统媒体库
private async saveToGallery(srcUri: string, isVideo: boolean): Promise<void> {
  const helper = photoAccessHelper.getPhotoAccessHelper(this.ability!.context);
  const destUris = await helper.showAssetsCreationDialog([srcUri], [{
    title: 'image',
    fileNameExtension: isVideo ? 'mp4' : 'png',
    photoType: isVideo ? photoAccessHelper.PhotoType.VIDEO
                       : photoAccessHelper.PhotoType.IMAGE,
  }]);
  if (destUris == null || destUris.length === 0) {
    throw new GalSaveError('ACCESS_DENIED', 'User canceled the save dialog.');
  }
  const src = fs.openSync(srcUri, fs.OpenMode.READ_ONLY);
  const dest = fs.openSync(destUris[0], fs.OpenMode.WRITE_ONLY);
  fs.copyFileSync(src.fd, dest.fd);
  fs.closeSync(src); fs.closeSync(dest);
}

方法	OpenHarmony 实现
`hasAccess` / `requestAccess`	返回 `true`——确认式保存链路不需要常驻相册权限
`putImage` / `putVideo`	`showAssetsCreationDialog` + `copyFileSync` 真实写入媒体库
`putImageBytes`	先写沙箱缓存再走确认式保存
`open`	`startAbility` 拉起系统图库

七、构建配置与签名

示例工程的目标 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:
  gal:
    git:
      url: https://atomgit.com/oh-flutter/gal.git
      ref: 2.3.3-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。真机上按本文的截图顺序逐一点击按钮完成验证。

十、适配结果和当前边界

相册写入已完整接入，只剩两个约束：

来源文件必须在应用沙箱内：showAssetsCreationDialog 只接受 file://<bundleName>/data/storage/... 形式的 URI，传外部绝对路径会返回系统错误 14000011。
需要用户在系统确认框里点"允许"——这是鸿蒙的隐私设计，不是实现缺陷。

十一、FAQ

Q1：为什么 `hasAccess` 返回 true？

现象： 鸿蒙没有独立的"相册权限"概念，showAssetsCreationDialog 在保存时逐次让用户确认，不需要常驻权限。
解决方法： 调用方按返回值决定是否展示保存入口。
验证结果： 真机返回 true，保存流程正常。

Q2：保存时报 14000011？

现象： 源 URI 格式不对。showAssetsCreationDialog 不接受 file:// + 绝对路径。
解决方法： 用 context.cacheDir 拼出 file://<bundleName>/data/storage/el2/base/haps/entry/cache/<file>。
验证结果： 修正后保存成功。