插件介绍

flutter_image_gallery_saver 是一个用于将图片、视频等媒体文件保存到设备相册的 Flutter 插件，支持 Android、iOS 和 HarmonyOS 平台。该插件基于 image_gallery_saver@2.0.3 版本进行鸿蒙平台适配，解决了 Flutter 应用在鸿蒙系统上保存媒体文件到相册的需求。

主要功能特点：

• 支持保存图片数据（Uint8List）到相册
• 支持保存本地文件（图片、视频等）到相册
• 提供图片质量控制
• 支持自定义保存文件名
• 鸿蒙平台完全适配，使用鸿蒙原生媒体库 API

使用说明

1. 包的引入

由于这是一个鸿蒙平台适配的自定义修改版本，需要通过 Git 方式引入依赖。在项目的 pubspec.yaml 文件中添加以下配置：

dependencies:
  image_gallery_saver:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_image_gallery_saver.git

添加依赖后，执行以下命令获取包：

flutter pub get

2. API 调用

flutter_image_gallery_saver 提供了两个主要 API 方法：saveImage 和 saveFile。

2.1 保存图片数据

saveImage 方法用于将图片字节数据保存到相册，支持设置图片质量和文件名。

方法签名：

static FutureOr<dynamic> saveImage(Uint8List imageBytes, {
  int quality = 80,
  String? name,
  bool isReturnImagePathOfIOS = false
})

参数说明：

• imageBytes：图片的字节数据，类型为 Uint8List，不能为空
• quality：图片保存质量，范围 0-100，默认值为 80
• name：保存到相册的文件名，可选
• isReturnImagePathOfIOS：在 iOS 平台是否返回图片路径，鸿蒙平台忽略此参数

返回值：
返回一个 Map 类型的数据，包含保存结果信息，例如：{"isSuccess": true, "filePath": "...", "message": "success save"}

示例代码：

保存网络图片到相册：

import 'dart:typed_data';
import 'package:dio/dio.dart';
import 'package:image_gallery_saver/image_gallery_saver.dart';

_saveNetworkImage() async {
  var response = await Dio().get(
      "https://example.com/image.jpg",
      options: Options(responseType: ResponseType.bytes));
  final result = await ImageGallerySaver.saveImage(
      Uint8List.fromList(response.data),
      quality: 60,
      name: "my_image");
  print(result);
}

保存本地截图到相册：

import 'dart:ui' as ui;
import 'dart:typed_data';
import 'package:flutter/rendering.dart';
import 'package:image_gallery_saver/image_gallery_saver.dart';

GlobalKey _globalKey = GlobalKey();

_saveScreenshot() async {
  RenderRepaintBoundary boundary =
      _globalKey.currentContext!.findRenderObject() as RenderRepaintBoundary;
  ui.Image image = await boundary.toImage();
  ByteData? byteData =
      await (image.toByteData(format: ui.ImageByteFormat.png));
  if (byteData != null) {
    final result =
        await ImageGallerySaver.saveImage(byteData.buffer.asUint8List());
    print(result);
  }
}

2.2 保存文件

saveFile 方法用于将本地文件（图片、视频等）保存到相册，支持自定义文件名。

方法签名：

static Future saveFile(String file, {
  String? name,
  bool isReturnPathOfIOS = false
})

参数说明：

• file：要保存的文件路径，类型为 String
• name：保存到相册的文件名，可选
• isReturnPathOfIOS：在 iOS 平台是否返回文件路径，鸿蒙平台忽略此参数

返回值：
返回一个 Map 类型的数据，包含保存结果信息，例如：{"isSuccess": true, "filePath": "...", "message": "success save"}

示例代码：

保存网络视频到相册：

import 'package:dio/dio.dart';
import 'package:path_provider/path_provider.dart';
import 'package:image_gallery_saver/image_gallery_saver.dart';

_saveNetworkVideo() async {
  var appDocDir = await getTemporaryDirectory();
  String savePath = appDocDir.path + "/temp.mp4";
  String fileUrl = "https://example.com/video.mp4";

  await Dio().download(fileUrl, savePath, onReceiveProgress: (count, total) {
    print((count / total * 100).toStringAsFixed(0) + "%");
  });

  final result = await ImageGallerySaver.saveFile(savePath);
  print(result);
}

保存本地图片文件到相册：

import 'package:image_gallery_saver/image_gallery_saver.dart';
import 'package:path_provider/path_provider.dart';

_saveLocalFile() async {
  var appDocDir = await getApplicationDocumentsDirectory();
  String filePath = appDocDir.path + "/my_local_image.jpg";

  // 假设 filePath 指向一个已存在的图片文件
  final result = await ImageGallerySaver.saveFile(filePath, name: "local_image");
  print(result);
}

平台兼容性

功能	鸿蒙平台支持
saveImage	是
saveFile	是
图片质量控制	是
自定义文件名	是

注意事项：

• 鸿蒙平台当前不支持存储 flv、mts、rm、vob、wms 格式的视频文件
• 保存大文件时可能需要较长时间，请适当处理用户交互
• 确保应用已获取必要的权限

总结

flutter_image_gallery_saver 是一个功能强大且易用的 Flutter 插件，为开发者提供了在鸿蒙平台上保存媒体文件到相册的能力。通过简单的 API 调用，开发者可以轻松实现图片和视频的保存功能，提升应用的用户体验。

使用该插件的关键步骤：

1. 通过 Git 方式引入鸿蒙适配版本的依赖
2. 导入插件包
3. 根据需求选择 saveImage 或 saveFile 方法
4. 处理返回结果，提供用户反馈

该插件的鸿蒙平台适配基于原生媒体库 API，确保了保存功能的稳定性和兼容性，是 Flutter 应用在鸿蒙系统上实现媒体文件保存的理想选择。