<!-- Copyright 2019 The FlutterCandies author. All rights reserved. Use of this source code is governed by an Apache license that can be found in the LICENSE file. -->

Flutter WeChat Assets Picker

Language: English | 中文

An image picker (also with videos and audios) for Flutter projects based on the WeChat's UI.

Current WeChat version that UI based on: 8.3.x UI designs will be updated following the WeChat update in anytime.

To take a photo or a video for assets, please check the detailed usage in the example, and head over to [wechat_camera_picker][wechat_camera_picker pub]. The package is a standalone extension that can to be used with combination.

See the [Migration Guide][] to learn how to migrate between breaking changes.

Versions compatibility

The package only guarantees to be working on the stable version of Flutter. We won't update it in real-time to align with other channels of Flutter.

	3.0	3.3	3.7	3.10	3.13	3.16
8.9.0+	❌	❌	❌	❌	❌	✅
8.7.0+	❌	❌	❌	❌	✅	❌
8.5.0+	❌	❌	❌	✅	❌	❌
8.4.0+	❌	❌	✅	❌	❌	❌
8.0.0+	✅	✅	❌	❌	❌	❌
7.3.0+	✅	✅	❌	❌	❌	❌

If you got a resolve conflict error when running flutter pub get, please use dependency_overrides to fix it.

Package credits

The package is built from these wonderful packages.

Name	Features
[photo_manager][photo_manager pub]	The basic abstractions and management for assets.
[extended_image][extended_image pub]	Preview assets with expected behaviors.
[provider][provider pub]	Helps to manage the interaction state of the picker.
[video_player][video_player pub]	Plays videos and audios correspondingly.

Their implementation should be relatively stable in the package. If you've found any issues related to them when using the picker, submit issues to our issue tracker first.

<details> <summary>Table of content</summary> <!-- TOC -->

• Flutter WeChat Assets Picker
  • Versions compatibility
  • Package credits
  • Features ✨
    • Notes 📝
  • Projects using this plugin 🖼️
  • Screenshots 📸
  • READ THIS FIRST ‼️
  • Preparing for use 🍭
    • Flutter
    • Android
      • Permissions
    • iOS
    • macOS
  • Usage 📖
    • Localizations
    • Simple usage
    • Detailed usage
      • Display selected assets
      • Register assets change observe callback
      • Upload an AssetEntity with a form data
        • With http
        • With dio
    • Custom pickers
  • Frequently asked question ❔
    • Changing the default album name (Recent to others)
    • Execution failed for task ':photo_manager:compileDebugKotlin'
    • Create AssetEntity from File or Uint8List (rawData)
    • Glide warning 'Failed to find GeneratedAppGlideModule'
  • Contributors ✨
  • Credits

<!-- TOC --> </details>

Features ✨

• ♿ Complete a11y support with TalkBack and VoiceOver
• ♻️ Fully customizable with delegates override
• 🎏 Fully customizable theme based on ThemeData
• 💚 Completely WeChat style (even more)
• ⚡️ Adjustable performance with different configurations
• 📷 Image support
  • 🔬 HEIF Image type support <a href="#notes-">⁽¹⁾</a>
• 🎥 Video support
• 🎶 Audio support <a href="#notes-">⁽²⁾</a>
• 1️⃣ Single picking mode
• 💱 Internationalization (i18n) support
  • ⏪ RTL language support
• ➕ Special item builder support
• 🗂 Custom sort path delegate support
• 📝 Custom text delegate support
• ⏳ Custom filter options support
• 💻 macOS support

Notes 📝

1. HEIF (HEIC) images are support to obtain and conversion, but the display with them are based on Flutter's image decoder. See flutter/flutter#20522. Use entity.file or AssetEntityImage for them when displays.
2. Due to limitations on iOS and macOS, audio can only be fetched within the sandbox.

Projects using this plugin 🖼️

name	pub	github
insta_assets_picker

Screenshots 📸

READ THIS FIRST ‼️

Be aware of below notices before you started anything:

• Due to understanding differences and the limitation of a single document, documents will not cover all the contents. If you find nothing related to your expected features and cannot understand about concepts, run the example project and check every options first. It has covered 90% of regular requests with the package.
• The package deeply integrates with the [photo_manager][photo_manager pub] plugin, make sure you understand these two concepts as much as possible:
  • Asset (photos/videos/audio) - AssetEntity
  • Assets collection (albums/libraries) - AssetPathEntity

When you have questions about related APIs and behaviors, check [photo_manager's API docs][] for more details.

Most usages are detailed covered by the example. Please walk through the example carefully before you have any questions.

Preparing for use 🍭

Flutter

Run flutter pub add wechat_assets_picker, or add wechat_assets_picker to pubspec.yaml dependencies manually.

dependencies:
  wechat_assets_picker: ^latest_version

The latest stable version is:

The latest dev version is:

Then import the package in your code:

import 'package:wechat_assets_picker/wechat_assets_picker.dart';

Android

When using the package, please upgrade targetSdkVersion and compileSdkVersion to 33. Otherwise, no assets can be fetched on Android 13.

Permissions

Name	Required	Declared	Max API Level	Others
READ_EXTERNAL_STORAGE	YES	YES	32
WRITE_EXTERNAL_STORAGE	NO	NO	29
ACCESS_MEDIA_LOCATION	YES*	NO	N/A	Required when reading EXIF
READ_MEDIA_IMAGES	YES*	YES	N/A	Required when reading images
READ_MEDIA_VIDEO	YES*	YES	N/A	Required when reading videos
READ_MEDIA_AUDIO	YES*	YES	N/A	Required when reading audios

If you're targeting Android SDK 33+, and you don't need to load photos, videos or audios, consider declare only relevant permission in your apps, more specifically:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.your.app">
    <!--Requesting access to images and videos.-->
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
    <!--When your app has no need to access audio, remove it or comment it out.-->
    <!--<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />-->
</manifest>

iOS

1. Platform version has to be at least 11.0. Modify ios/Podfile and update accordingly.

   platform :ios, '11.0'

   Remove the # heading if the line starts with it.
2. Add the following content to Info.plist.

<key>NSPhotoLibraryUsageDescription</key>
<string>Replace with your permission description.</string>

macOS

1. Platform version has to be at least 10.15. Modify macos/Podfile and update accordingly.

   platform :osx, '10.15'

   Remove the # heading if the line starts with it.
2. Set the minimum deployment target of the macOS to 10.15. Use XCode to open macos/Runner.xcworkspace .
3. Follow the iOS instructions and modify Info.plist accordingly.

Usage 📖

Localizations

When you're picking assets, the package will obtain the Locale? from your BuildContext, and return the corresponding text delegate of the current language. Make sure you have a valid Locale in your widget tree that can be accessed from the BuildContext. Otherwise, the default Chinese delegate will be used.

Embedded text delegates languages are:

• 简体中文 (default)
• English
• העברית
• Deutsche
• Локализация
• 日本語
• مة العربية
• Délégué
• Tiếng Việt
• Türkçe Yerelleştirme

If you want to use a custom/fixed text delegate, pass it through the AssetPickerConfig.textDelegate.

Simple usage

final List<AssetEntity>? result = await AssetPicker.pickAssets(context);

Use AssetPickerConfig for more picking behaviors.

final List<AssetEntity>? result = await AssetPicker.pickAssets(
  context,
  pickerConfig: const AssetPickerConfig(),
);

Fields in AssetPickerConfig:

Name	Type	Description	Default
selectedAssets	List<AssetEntity>?	Selected assets. Prevent duplicate selection.	null
maxAssets	int	Maximum asset that the picker can pick.	9
pageSize	int?	Number of assets per page. Must be a multiple of gridCount.	80
gridThumbnailSize	ThumbnailSize	Thumbnail size for the grid's item.	ThumbnailSize.square(200)
pathThumbnailSize	ThumbnailSize	Thumbnail size for the path selector.	ThumbnailSize.square(80)
previewThumbnailSize	ThumbnailSize?	Preview thumbnail size in the viewer.	null
requestType	RequestType	Request type for picker.	RequestType.common
specialPickerType	SpecialPickerType?	Provides the option to integrate a custom picker type.	null
keepScrollOffset	bool	Whether the picker should save the scroll offset between pushes and pops.	null
sortPathDelegate	SortPathDelegate<AssetPathEntity>?	Path entities sort delegate for the picker, sort paths as you want.	CommonSortPathDelegate
sortPathsByModifiedDate	bool	Whether to allow sort delegates to sort paths with FilterOptionGroup.containsPathModified.	false
filterOptions	PMFilter?	Allow users to customize assets filter options.	null
gridCount	int	Grid count in picker.	4
themeColor	Color?	Main theme color for the picker.	Color(0xff00bc56)
pickerTheme	ThemeData?	Theme data provider for the picker and the viewer.	null
textDelegate	AssetPickerTextDelegate?