1. 插件介绍

Flutter Image Gallery Saver 是一个专为 Flutter 应用开发设计的图片和文件保存库，它能够将图片、GIF 和视频等媒体文件保存到设备的本地图库中。该插件解决了 Flutter 原生不支持将图像直接保存到系统图库的问题，经过适配后完美支持鸿蒙系统，为开发者提供了便捷的媒体文件保存解决方案。

核心功能

• 图片保存：支持将本地绘制的图像、网络图片保存到系统图库
• GIF 保存：支持将 GIF 动图保存到系统图库
• 视频保存：支持将视频文件保存到系统图库
• 质量控制：支持设置图片保存质量
• 自定义文件名：支持为保存的文件指定自定义名称

典型用例

• 社交媒体应用的图片分享功能
• 图片编辑应用的保存功能
• 视频应用的缓存和分享功能
• 截图保存功能

2. 安装与配置

由于这是专为鸿蒙系统定制修改的版本，需要通过 Git 方式引入依赖。

2.1 添加依赖

在项目的 pubspec.yaml 文件中，添加以下配置：

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

2.2 安装依赖

执行以下命令安装依赖：

flutter pub get

3. 使用指南

3.1 导入包

在需要使用的文件中导入包：

import 'package:image_gallery_saver/image_gallery_saver.dart';

3.2 API 调用

3.2.1 保存图片

保存图片可以使用 saveImage 方法，支持保存 Uint8List 格式的图片数据：

// 保存图片，quality 和 name 参数可选
final result = await ImageGallerySaver.saveImage(
    imageBytes, // Uint8List 格式的图片数据
    quality: 80, // 保存质量，0-100，默认 80
    name: "custom_image" // 自定义文件名
);
print(result); // 打印保存结果

3.2.2 保存文件

保存文件可以使用 saveFile 方法，支持保存图片、GIF 和视频等文件：

// 保存文件，name 和 isReturnPathOfIOS 参数可选
final result = await ImageGallerySaver.saveFile(
    filePath, // 文件路径
    name: "custom_file", // 自定义文件名
    isReturnPathOfIOS: true // 是否返回 iOS 设备上的文件路径
);
print(result); // 打印保存结果

4. 完整示例

4.1 保存本地绘制的图片

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

class SaveLocalImageExample extends StatefulWidget {
  @override
  _SaveLocalImageExampleState createState() => _SaveLocalImageExampleState();
}

class _SaveLocalImageExampleState extends State<SaveLocalImageExample> {
  GlobalKey _globalKey = GlobalKey();

  _saveLocalImage() async {
    // 获取需要保存的 widget
    RenderRepaintBoundary boundary = _globalKey.currentContext!.findRenderObject() as RenderRepaintBoundary;
    // 将 widget 转换为图片
    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(),
          quality: 100,
          name: "local_drawing"
      );
      print("保存结果: $result");
      // 显示保存成功提示
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text("图片保存成功"))
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("保存本地绘制图片"),
      ),
      body: Center(
        child: Column(
          children: <Widget>[
            SizedBox(height: 20),
            // 需要保存的 widget
            RepaintBoundary(
              key: _globalKey,
              child: Container(
                alignment: Alignment.center,
                width: 300,
                height: 300,
                color: Colors.blue,
                child: Text(
                  "Hello HarmonyOS",
                  style: TextStyle(fontSize: 24, color: Colors.white),
                ),
              ),
            ),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: _saveLocalImage,
              child: Text("保存图片到图库"),
            ),
          ],
        ),
      ),
    );
  }
}

4.2 保存网络图片

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

class SaveNetworkImageExample extends StatelessWidget {
  _saveNetworkImage() async {
    // 从网络获取图片数据
    var response = await Dio().get(
        "https://ss0.baidu.com/94o3dSag_xI4khGko9WTAnF6hhy/image/h%3D300/sign=a62e824376d98d1069d40a31113eb807/838ba61ea8d3fd1fc9c7b6853a4e251f94ca5f46.jpg",
        options: Options(responseType: ResponseType.bytes)
    );
    // 保存图片到图库
    final result = await ImageGallerySaver.saveImage(
        Uint8List.fromList(response.data),
        quality: 60, // 设置保存质量
        name: "network_image" // 设置自定义文件名
    );
    print("保存结果: $result");
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("保存网络图片"),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: _saveNetworkImage,
          child: Text("保存网络图片到图库"),
        ),
      ),
    );
  }
}

4.3 保存 GIF 动图

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

class SaveGifExample extends StatelessWidget {
  _saveNetworkGifFile() async {
    // 获取临时目录
    var appDocDir = await getTemporaryDirectory();
    // 设置临时文件路径
    String savePath = appDocDir.path + "/temp.gif";
    // GIF 网络地址
    String fileUrl = "https://hyjdoc.oss-cn-beijing.aliyuncs.com/hyj-doc-flutter-demo-run.gif";
    // 下载 GIF 到临时目录
    await Dio().download(fileUrl, savePath);
    // 保存 GIF 到图库
    final result = await ImageGallerySaver.saveFile(savePath);
    print("保存结果: $result");
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("保存 GIF 动图"),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: _saveNetworkGifFile,
          child: Text("保存 GIF 到图库"),
        ),
      ),
    );
  }
}

4.4 保存视频

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

class SaveVideoExample extends StatelessWidget {
  _saveNetworkVideoFile() async {
    // 获取临时目录
    var appDocDir = await getTemporaryDirectory();
    // 设置临时文件路径
    String savePath = appDocDir.path + "/temp.mp4";
    // 视频网络地址
    String fileUrl = "https://s3.cn-north-1.amazonaws.com.cn/mtab.kezaihui.com/video/ForBiggerBlazes.mp4";
    // 下载视频到临时目录
    await Dio().download(
        fileUrl,
        savePath,
        onReceiveProgress: (count, total) {
          // 显示下载进度
          print((count / total * 100).toStringAsFixed(0) + "%");
        }
    );
    // 保存视频到图库
    final result = await ImageGallerySaver.saveFile(savePath);
    print("保存结果: $result");
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text("保存视频"),
      ),
      body: Center(
        child: ElevatedButton(
          onPressed: _saveNetworkVideoFile,
          child: Text("保存视频到图库"),
        ),
      ),
    );
  }
}

4. 约束与限制

• Flutter 版本要求：3.7.12-ohos-1.0.6 及以上
• 鸿蒙 SDK 版本要求：5.0.0(12) 及以上
• IDE 要求：DevEco Studio 5.0.13.200 及以上
• 注意：在鸿蒙平台上不支持存储 flv、mts、rm、vob、wms 格式的视频

5. 总结

Flutter Image Gallery Saver 为鸿蒙系统提供了便捷的媒体文件保存功能，使开发者能够轻松实现图片、GIF 和视频的保存功能。通过简单的 API 调用，即可完成从网络或本地获取媒体文件并保存到系统图库的操作，极大地简化了开发流程。

该插件具有以下优势：

• 简单易用的 API 设计
• 支持多种媒体类型
• 灵活的配置选项（质量、文件名等）
• 良好的鸿蒙系统兼容性

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

---

注意：本指南基于 Image Gallery Saver 2.0.3 版本编写，具体 API 可能会随版本更新而有所变化，请以最新文档为准。