ByteNote

本文介绍 flutter_wechat_assets_picker，一个基于微信 UI 风格的 Flutter 资源选择器插件，支持图片、视频和音频的选择，目前已在 GitHub 上获得超过 1600 个 Star。

项目简介

flutter_wechat_assets_picker 是由 FlutterCandies 团队开发的开源 Flutter 插件，它完美复刻了微信 8.0.51 版本的资源选择器界面。该插件不仅支持图片选择，还支持视频和音频的选择功能，是目前 Flutter 生态中最受欢迎的资产选择器插件之一。

该项目采用 Apache-2.0 开源许可证，拥有 981 次提交、34 位贡献者、514 个 Fork，已发布 152 个版本（最新版本为 v10.1.0），展现了极高的社区活跃度和项目成熟度。插件已被收录在 Awesome Flutter 列表中，并在 pub.dev 上以 wechat_assets_picker 的包名发布。

核心特性

完整的微信风格 UI

插件完整复刻了微信的资源选择器界面设计，包括相册列表、网格缩略图、多选操作、预览查看等核心交互。UI 设计会跟随微信版本的更新而同步更新，确保始终与最新版微信保持一致。

多类型资产支持

插件支持多种媒体类型的选择：

图片选择：支持常规图片格式，包括 HEIF/HEIC 图片的获取和转换
视频选择：支持视频文件的浏览和选择
音频选择：支持音频文件的选择（iOS 和 macOS 上仅支持沙盒内的音频）

全面的无障碍支持

插件提供了完整的无障碍功能支持，兼容 Android 的 TalkBack 和 iOS 的 VoiceOver，确保所有用户都能顺畅使用。

高度可定制化

通过委托（Delegate）覆盖机制，开发者可以完全自定义选择器的行为和外观：

完全自定义主题，基于 ThemeData
自定义文本委托
自定义排序路径委托
自定义过滤选项
自定义特殊项构建器
支持通过继承和重写来创建完全自定义的选择器

性能可调

插件提供了多种配置选项，允许开发者根据应用需求调整性能表现，包括缩略图大小、分页数量、网格列数等参数的精细控制。

国际化支持

插件内置了多种语言的文本委托：

简体中文（默认）
English
Hebrew
Deutsch
Russian
Japanese
Arabic
French
Vietnamese
Turkish

同时支持 RTL（从右到左）语言布局。

跨平台支持

插件支持以下平台：

Android：需要 targetSdkVersion 和 compileSdkVersion 升级到 33
iOS：最低平台版本 11.0
macOS：最低平台版本 10.15

技术栈

核心依赖

插件基于以下几个优秀的 Flutter 包构建：

包名	功能
photo_manager	资产的基本抽象和管理
extended_image	预览资产并提供预期的交互行为
provider	管理选择器的交互状态
video_player	播放视频和音频

主要语言构成

项目几乎完全使用 Dart 编写（占比 99.2%），这体现了其作为一个纯 Dart/Flutter 插件的特性，平台特定代码通过依赖包来处理。

Flutter 版本兼容性

插件保证在 Flutter 稳定版上正常工作，各版本对应关系如下：

插件版本	Flutter 3.10	Flutter 3.13	Flutter 3.16	Flutter 3.22	Flutter 3.27
10.0.0+	-	-	-	-	支持
9.5.0+	-	-	-	支持	支持
8.9.0+	-	-	支持	-	-
8.7.0+	-	支持	-	-	-
8.5.0+	支持	-	-	-	-

安装指南

添加依赖

在 pubspec.yaml 中添加依赖：

yaml

dependencies:
  wechat_assets_picker: ^10.1.0

或者通过命令行添加：

bash

flutter pub add wechat_assets_picker

导入包

在 Dart 代码中导入：

dart

import 'package:wechat_assets_picker/wechat_assets_picker.dart';

Android 配置

将 targetSdkVersion 和 compileSdkVersion 升级到 33。在 AndroidManifest.xml 中添加必要权限：

xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.your.app">
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
    <!-- 如果不需要访问音频，可以移除或注释掉 -->
    <!-- <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" /> -->
</manifest>

iOS 配置

在 ios/Podfile 中设置最低平台版本：

ruby

platform :ios, '11.0'

在 Info.plist 中添加相册访问描述：

xml

<key>NSPhotoLibraryUsageDescription</key>
<string>替换为你的权限描述文本。</string>

macOS 配置

在 macos/Podfile 中设置最低平台版本：

ruby

platform :osx, '10.15'

使用 Xcode 打开 macos/Runner.xcworkspace，设置最低部署目标为 10.15，并按照 iOS 的说明修改 Info.plist。

快速开始

基础用法

最简单的调用方式只需要一行代码：

dart

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

配置选项

通过 AssetPickerConfig 自定义选择行为：

dart

final List<AssetEntity>? result = await AssetPicker.pickAssets(
  context,
  pickerConfig: const AssetPickerConfig(
    maxAssets: 9,              // 最多选择 9 个资产
    requestType: RequestType.common,  // 请求类型
    gridCount: 4,              // 网格列数
    pageSize: 80,              // 每页资产数量
    themeColor: Color(0xff00bc56),    // 主题色（微信绿）
  ),
);

AssetPickerConfig 主要参数说明

参数名	类型	描述	默认值
selectedAssets	`List<AssetEntity>?`	已选资产列表，防止重复选择	`null`
maxAssets	`int`	最大可选择数量	9
pageSize	`int?`	每页资产数量（须为 gridCount 的倍数）	80
requestType	`RequestType`	请求的资源类型	`RequestType.common`
gridCount	`int`	网格列数	4
themeColor	`Color?`	主题颜色	微信绿
textDelegate	`AssetPickerTextDelegate?`	文本委托	默认中文
specialPickerType	`SpecialPickerType?`	特殊选择器类型	`null`
dragToSelect	`bool`	是否支持拖拽多选	`true`
enableLivePhoto	`bool`	是否启用 Live Photo	`true`

使用示例

单选模式

当 maxAssets 设为 1 时，自动进入单选模式：

dart

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

自定义相册名称

使用 pathNameBuilder 自定义相册显示名称：

dart

AssetPickerConfig(
  pathNameBuilder: (AssetPathEntity path) => switch (path) {
    final p when p.isAll => '最近',
    _ => path.name,
  },
)

显示已选资产

使用 AssetEntityImage 显示选中资产的缩略图：

dart

AssetEntityImage(asset, isOriginal: false);

或使用 ImageProvider 方式：

dart

Image(image: AssetEntityImageProvider(asset, isOriginal: false));

注册资产变化监听

dart

// 注册监听
AssetPicker.registerObserve();

// 取消监听
AssetPicker.unregisterObserve();

上传 AssetEntity 到服务器

使用 http 包上传：

dart

import 'package:http/http.dart' as http;

Future<void> upload() async {
  final entity = await obtainYourEntity();
  final file = await entity.file;
  final uri = Uri.https('example.com', 'create');
  final request = http.MultipartRequest('POST', uri)
    ..fields['test_field'] = 'test_value'
    ..files.add(await http.MultipartFile.fromPath('file', file!.path));
  final response = await request.send();
}

使用 dio 包上传：

dart

import 'package:dio/dio.dart' as dio;

Future<void> upload() async {
  final entity = await obtainYourEntity();
  final file = await entity.file;
  final uri = Uri.https('example.com', 'create');
  final response = dio.Dio().requestUri(
    uri,
    data: dio.FormData.fromMap({
      'file': await dio.MultipartFile.fromFile(file!.path),
    }),
  );
}

自定义选择器

通过继承 AssetPickerBuilderDelegate、AssetPickerViewerBuilderDelegate 等类，可以实现完全自定义的选择器界面：

dart

class MyCustomPickerDelegate extends AssetPickerBuilderDelegate<AssetEntity, AssetPathEntity> {
  // 实现自定义逻辑
}

项目链接

GitHub 仓库：https://github.com/fluttercandies/flutter_wechat_assets_picker
pub.dev 包：https://pub.dev/packages/wechat_assets_picker
开源许可证：Apache-2.0 License
组织：FlutterCandies
最新版本：v10.1.0
最新开发版：可通过 pub.dev 的 pre-release 频道获取

该插件是 Flutter 社区中最成熟、功能最完善的资源选择器之一，适合需要微信风格图片/视频选择功能的应用直接使用。丰富的自定义选项和完善的文档使其成为生产环境的可靠选择。如需拍照或录像功能，可以配合团队提供的 wechat_camera_picker 扩展包使用。

字节笔记本

Flutter WeChat Assets Picker - 微信风格资源选择器

项目简介

核心特性

完整的微信风格 UI

多类型资产支持

全面的无障碍支持

高度可定制化

性能可调

国际化支持

跨平台支持

技术栈

核心依赖

主要语言构成

Flutter 版本兼容性

安装指南

添加依赖

导入包

Android 配置

iOS 配置

macOS 配置

快速开始

基础用法

配置选项

AssetPickerConfig 主要参数说明

使用示例

单选模式

自定义相册名称

显示已选资产

注册资产变化监听

上传 AssetEntity 到服务器

自定义选择器

项目链接