插件介绍

fluttertpc_gallery_saver 是一个功能强大的 Flutter 插件，专门用于将图片和视频保存到设备的相册中。无论是从网络下载的媒体文件，还是应用内临时生成的图片和视频，都可以通过这个插件快速保存到系统相册，并且在鸿蒙系统的图库应用中可见。

核心功能

• 📷 保存图片：支持将本地图片文件或网络图片 URL 保存到系统相册
• 🎥 保存视频：支持将本地视频文件或网络视频 URL 保存到系统相册
• 📁 相册管理：支持指定保存到特定相册
• 🔄 网络支持：自动处理网络媒体文件的下载和保存
• 🎯 跨平台兼容：在鸿蒙平台上完美适配，同时支持 Android 和 iOS

快速开始

环境要求

• Flutter SDK 版本：≥ 1.10.0
• Dart SDK 版本：≥ 2.12.0
• 鸿蒙平台：支持 OpenHarmony 5.0.0 及以上版本

依赖配置

在你的 Flutter 项目中，打开 pubspec.yaml 文件，添加以下依赖配置。注意使用 atomgit.com 作为 Git 源：

dependencies:
  flutter:
    sdk: flutter

  # Gallery Saver 插件
  gallery_saver:
    git:
      url: https://atomgit.com/openharmony-sig/fluttertpc_gallery_saver.git

  # 依赖的鸿蒙适配组件
  path_provider:
    git:
      url: https://atomgit.com/openharmony-sig/flutter_packages.git
      path: packages/path_provider/path_provider

  http: ^0.13.3

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

flutter pub get

权限配置

在鸿蒙平台上使用 Gallery Saver 插件，需要在应用配置文件中添加相应权限。

1. 打开 entry/src/main/module.json5 文件，添加以下权限配置：

{
  "module": {
    "abilities": [
      {
        "requestPermissions": [
          {
            "name": "ohos.permission.INTERNET",
            "reason": "用于下载网络媒体文件",
            "usedScene": {
              "abilities": ["EntryAbility"],
              "when": "inuse"
            }
          },
          {
            "name": "ohos.permission.READ_MEDIA",
            "reason": "用于访问媒体库",
            "usedScene": {
              "abilities": ["EntryAbility"],
              "when": "inuse"
            }
          },
          {
            "name": "ohos.permission.WRITE_IMAGEVIDEO",
            "reason": "用于保存图片和视频到相册",
            "usedScene": {
              "abilities": ["EntryAbility"],
              "when": "inuse"
            }
          }
        ]
      }
    ]
  }
}

2. 打开 entry/src/main/resources/base/element/string.json 文件，添加权限说明：

{
  "string": [
    {
      "name": "network_reason",
      "value": "用于下载网络媒体文件"
    },
    {
      "name": "media_reason",
      "value": "用于访问媒体库"
    },
    {
      "name": "write_imagevideo_reason",
      "value": "用于保存图片和视频到相册"
    }
  ]
}

注意：由于使用了 system_basic 级别的权限，你可能需要将应用权限等级设置为 system_basic。

API 使用指南

导入包

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

import 'package:gallery_saver/gallery_saver.dart';

保存本地图片

将应用内生成的图片或从其他来源获取的本地图片保存到相册：

import 'dart:io';
import 'package:image_picker/image_picker.dart';

// 从相机拍摄图片
void _takeAndSavePhoto() async {
  final imagePicker = ImagePicker();
  final XFile? image = await imagePicker.pickImage(source: ImageSource.camera);

  if (image != null) {
    // 保存图片到相册
    bool? success = await GallerySaver.saveImage(image.path);

    if (success == true) {
      print('图片保存成功！');
    } else {
      print('图片保存失败！');
    }
  }
}

保存网络图片

将网络上的图片 URL 保存到相册：

void _saveNetworkImage() async {
  String imageUrl = 'https://example.com/image.jpg';

  bool? success = await GallerySaver.saveImage(
    imageUrl,
    albumName: 'MyAppPhotos', // 可选：指定保存到特定相册
    toDcim: true, // 可选：保存到 DCIM 目录
    headers: {'Authorization': 'Bearer token'}, // 可选：网络请求头
  );

  if (success == true) {
    print('网络图片保存成功！');
  } else {
    print('网络图片保存失败！');
  }
}

保存本地视频

将应用内录制的视频或从其他来源获取的本地视频保存到相册：

import 'package:image_picker/image_picker.dart';

// 从相机录制视频并保存
void _recordAndSaveVideo() async {
  final imagePicker = ImagePicker();
  final XFile? video = await imagePicker.pickVideo(
    source: ImageSource.camera,
    maxDuration: Duration(seconds: 30),
  );

  if (video != null) {
    // 保存视频到相册
    bool? success = await GallerySaver.saveVideo(video.path);

    if (success == true) {
      print('视频保存成功！');
    } else {
      print('视频保存失败！');
    }
  }
}

保存网络视频

将网络上的视频 URL 保存到相册：

void _saveNetworkVideo() async {
  String videoUrl = 'https://example.com/video.mp4';

  bool? success = await GallerySaver.saveVideo(
    videoUrl,
    albumName: 'MyAppVideos', // 可选：指定保存到特定相册
    toDcim: true, // 可选：保存到 DCIM 目录
  );

  if (success == true) {
    print('网络视频保存成功！');
  } else {
    print('网络视频保存失败！');
  }
}

支持的媒体格式

图片格式

• JPEG (.jpeg, .jpg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)
• TIFF (.tif)
• HEIC (.heic)

视频格式

• MP4 (.mp4)
• MOV (.mov)
• AVI (.avi)
• WMV (.wmv)
• 3GP (.3gp, .3gpp)
• MKV (.mkv)
• FLV (.flv)

API 参考

保存图片

Future<bool?> saveImage(
  String path, {
    String? albumName,
    bool toDcim = false,
    Map<String, String>? headers
  }
)

参数说明：

• path：图片文件路径或网络 URL
• albumName：可选，指定保存的相册名称
• toDcim：可选，是否保存到 DCIM 目录，默认为 false
• headers：可选，网络请求头，用于需要认证的网络资源

返回值：

• true：保存成功
• false：保存失败
• null：操作异常

保存视频

Future<bool?> saveVideo(
  String path, {
    String? albumName,
    bool toDcim = false,
    Map<String, String>? headers
  }
)

参数说明：

• path：视频文件路径或网络 URL
• albumName：可选，指定保存的相册名称
• toDcim：可选，是否保存到 DCIM 目录，默认为 false
• headers：可选，网络请求头，用于需要认证的网络资源

返回值：

• true：保存成功
• false：保存失败
• null：操作异常

常见问题

权限问题

如果遇到权限相关的错误，请确保：

1. 已在 module.json5 中添加了所有必要的权限
2. 应用权限等级已设置为 system_basic
3. 应用运行时已获得用户授权

网络资源保存失败

• 确保网络资源 URL 包含 http:// 或 https:// 前缀
• 对于需要认证的资源，添加正确的 headers 参数
• 检查设备网络连接是否正常

保存路径问题

• 确保本地文件路径正确且应用有访问权限
• 对于临时文件，确保文件在保存期间未被删除

总结

fluttertpc_gallery_saver 是鸿蒙平台上一款功能强大的媒体文件保存插件，它为开发者提供了简单易用的 API，能够快速将图片和视频保存到系统相册。无论是本地文件还是网络资源，都能高效处理，并且支持多种媒体格式。

通过本文的介绍，你应该已经了解了如何在鸿蒙平台上配置和使用这个插件。它的跨平台特性使得你的应用可以在不同系统上保持一致的用户体验，同时在鸿蒙平台上得到了专门的优化和适配。

---

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