gal

套件介紹

根據套件公開資料產生的選型評估，僅供參考。

gal 套件是一個 Flutter 插件，可啟用將影像和影片儲存至裝置相簿的功能，並內建權限處理。它支援 Android、iOS、macOS 與 Windows，非常適合需要媒體匯出功能的應用程式。此套件透過自動管理權限來簡化存取相簿的過程，減少重複程式碼。它能順暢整合至多媒體工作流程中，特別是涉及影像或影片拍攝、編輯或分享的應用程式。

適用情境

將捕獲的圖片/影片儲存到相簿
編輯後自動匯出媒體
在跨平台應用中整合相簿存取
處理媒體存儲的權限請求
啟用使用者友善的媒體分享

主要特色

自動權限處理
跨平台支援（Android、iOS、macOS、Windows）
用於儲存媒體的簡單 API
內建錯誤管理
輕量且易於整合

適合對象

具有媒體捕獲功能的 Flutter 應用
影像或影片編輯工具
需要相冊存取權限的應用
尋求媒體保存最小設定的開發者
跨平台多媒體應用

使用建議

需要在平台特定的設定檔中具有適當的權限
可能需要針對特定作業系統行為進行額外處理
僅限基本儲存操作，無法進行進階元資料控制
依賴外部倉庫進行更新
不適用於媒體選擇或瀏覽

原始 README

以下為關聯原始碼儲存庫的 README 原文快照，最新內容請造訪原始碼儲存庫。

Dart3 plugin for saving image or video to photos gallery

pub.dev »

📢 Support Us

Please support our volunteer efforts by giving us a LIKE👍 and STAR⭐️.

🧠 DeepWiki Documentation

📱 Supported Platforms

	Android	iOS	macOS	Windows	Linux
Support	SDK 21+	11+	11+	10+	See: gal_linux

Support means that all functions have been tested manually or automatically whenever possible.

📸 Demo

	iOS	Android
Example

✨ Features

Open gallery
Save video
Save image
Save to album
Save with metadata
Handle permission
Handle errors
Comprehensive documentation and wiki

🚀 Getting Started

Add Dependency

Add the latest stable version of gal to your dependencies:

flutter pub add gal

iOS Setup

Add the following keys to ios/Runner/Info.plist:

<key>NSPhotoLibraryAddUsageDescription</key> Required
<key>NSPhotoLibraryUsageDescription</key> Required for iOS < 14 or saving to album

You can copy from example's Info.plist.

Android Setup

Add the following keys to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29" /> Required for API <= 29
android:requestLegacyExternalStorage="true" Required for saving to album in API 29

You can copy from example's AndroidManifest.xml.

[!WARNING] Android emulators with API < 29 require SD card setup. Real devices don't.

macOS Setup

Add the following keys to macos/Runner/Info.plist:

<key>NSPhotoLibraryAddUsageDescription</key> Required
<key>NSPhotoLibraryUsageDescription</key> Required for saving to album

You can copy from example's Info.plist.

[!WARNING] Flutter currently has a fatal problem for loading info.plist, which may cause permission denials or app crashes in some code editors.

Windows Setup

Update Visual Studio to the latest version for using C++ 20.

[!TIP] If you can't compile, try downloading the latest Windows SDK:

Open Visual Studio Installer

Select Modify

Select Windows SDK

Linux Setup

Linux is not officially supported, but can be added through a non-endorsed federated plugin. See: gal_linux

💻 Usage

Save from Local

// Save Image (Supports two ways)
await Gal.putImage('$filePath');
await Gal.putImageBytes('$uint8List');

// Save Video
await Gal.putVideo('$filePath');

// Save to Album
await Gal.putImage('$filePath', album: '$album')
...

Download from Internet

flutter pub add dio

// Download Image
final imagePath = '${Directory.systemTemp.path}/image.jpg';
await Dio().download('$url',imagePath);
await Gal.putImage(imagePath);

// Download Video
final videoPath = '${Directory.systemTemp.path}/video.mp4';
await Dio().download('$url',videoPath);
await Gal.putVideo(videoPath);

Save from Camera

flutter pub add image_picker

// Capture and Save
final image = await ImagePicker.pickImage(source: ImageSource.camera);
await Gal.putImage(image.path);

flutter pub add camera

// Record and Save
...
final video = await controller.stopVideoRecording();
await Gal.putVideo(video.path);

Handle Permissions

// Check Access Permission
final hasAccess = await Gal.hasAccess();

// Request Access Permission
await Gal.requestAccess();

// ... for saving to album
final hasAccess = await Gal.hasAccess(toAlbum: true);
await Gal.requestAccess(toAlbum: true);

Handle Errors

// Save Image with try-catch
try {
  await Gal.putImage('$filePath');
} on GalException catch (e) {
  log(e.type.message);
}

// Exception Type
enum GalExceptionType {
  accessDenied,
  notEnoughSpace,
  notSupportedFormat,
  unexpected;

  String get message => switch (this) {
        accessDenied => 'Permission to access the gallery is denied.',
        notEnoughSpace => 'Not enough space for storage.',
        notSupportedFormat => 'Unsupported file format.',
        unexpected => 'An unexpected error has occurred.',
      };
}