z_file_saver_handler

一个用于将图片保存到系统相册的 Flutter 工具库。支持网络 URL、Asset、本地文件、Base64 多种来源，自动处理跨平台权限与统一文件命名。适配 Android 与 iOS。

特性

• 统一入口：ZFileSaver.saveImageToGallery 一行保存到相册
• 自动权限：根据平台与系统版本智能请求相册/存储权限
• 多来源支持：网络、Asset、本地文件、Base64 全覆盖
• 统一命名：{AppName}_yyyyMMdd_HHmmss 的文件名格式
• 友好反馈：保存成功/失败通过 SnackBar 提示

安装

在你的应用 pubspec.yaml 中添加依赖（示例）：

dependencies:
  z_file_saver_handler: ^0.0.1

导入

import 'package:z_file_saver_handler/z_file_saver_handler.dart';
// 提供：ZFileSaver、ZImageType、ZImageTypeUtil

快速上手

// 传入 BuildContext 用于权限弹窗与结果 SnackBar 提示
await ZFileSaver.saveImageToGallery(context, imagePath);

imagePath 支持：

• 网络图片：https://example.com/a.jpg
• Asset 资源：assets/images/demo.png
• 本地文件：/storage/emulated/0/Download/a.jpg
• Base64：data:image/png;base64,xxxx

示例：

// 1) 网络图片
await ZFileSaver.saveImageToGallery(context, 'https://example.com/a.jpg');

// 2) Asset 图片
await ZFileSaver.saveImageToGallery(context, 'assets/images/demo.png');

// 3) 本地文件
await ZFileSaver.saveImageToGallery(context, '/storage/emulated/0/Download/a.jpg');

// 4) Base64 图片
await ZFileSaver.saveImageToGallery(context, 'data:image/png;base64,XXXXX');

平台配置

• iOS（Info.plist）：

  • NSPhotoLibraryUsageDescription
  • NSPhotoLibraryAddUsageDescription

• Android（AndroidManifest.xml）建议：

<!-- Android 13+ -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

<!-- Android 10–12 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />

<!-- Android 9 及以下写入存储 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29" />

库会自动根据系统版本申请 photos 或 storage 权限。

API

• ZFileSaver.saveImageToGallery(BuildContext context, String imagePath)

  • 自动判断图片来源并保存至相册
  • 成功与失败均通过 SnackBar 提示

• ZImageTypeUtil.getImageType(String path) -> ZImageType

  • 识别 network | asset | file | base64

• ZImageTypeUtil.getImageProvider(String path) -> ImageProvider

  • 返回对应的 NetworkImage | AssetImage | FileImage | MemoryImage

注意事项

• 需提供有效的 BuildContext（用于权限与提示）。
• iOS 首次调用会弹出相册权限弹窗，未授权将无法保存。
• Android 不同版本权限差异较大，建议按上述清单声明。

主页与许可

• 主页：https://github.com/Jazzzy126/z_file_saver
• 许可：MIT（详见仓库 LICENSE）