Flutter 图片选择器插件
| Android | iOS | |
|---|---|---|
| 支持 | SDK 21+ | 11.0+ |
简化您 Flutter 应用中的媒体选择、裁剪和相机功能。轻松从图库选择图片/视频，裁剪图片，并拍摄新照片/视频。
安装
$ flutter pub add hl_image_picker
注意：如果您仅为
Android或iOS开发应用程序，则无需安装hl_image_picker。相反，您可以根据目标平台选择以下任一包：
- iOS – hl_image_picker_ios
- Android – hl_image_picker_android
设置
要使用此插件，您需要执行以下设置步骤：
iOS
- 将
Privacy Description添加到您的ios/Runner/Info.plist文件中。
<key>NSPhotoLibraryUsageDescription</key>
<string>This app requires access to the photo library</string>
<key>NSCameraUsageDescription</key>
<string>This app requires access to the camera</string>
<!-- Include this description only if your plugin requires recording videos and needs access to the device's microphone. -->
<key>NSMicrophoneUsageDescription</key>
<string>This app requires access to the microphone</string>
iOS 14 您可以通过在 Info.plist 中将 PHPhotoLibraryPreventAutomaticLimitedAccessAlert 设置为 yes 来阻止系统自动提示。
<key>PHPhotoLibraryPreventAutomaticLimitedAccessAlert</key>
<true/>
- (可选) 如果您想本地化相机，请打开 Xcode，转到 Info 选项卡，并为相机添加缺失的本地化。
Android
- 确保在您的
android/app/build.gradle文件中将minSdkVersion设置为 21 或更高版本。
android {
...
defaultConfig {
minSdkVersion 21
...
}
}
- 将权限添加到您的
AndroidManifest.xml文件中。
<!-- Android 12 and lower -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!-- Targeting Android 13 or higher -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<!-- Request the camera permission -->
<uses-feature android:name="android.hardware.camera" android:required="false" />
<uses-permission android:name="android.permission.CAMERA" />
<!-- Add this permission if you need to record videos -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
用法
从图库中选择图片/视频
import 'package:hl_image_picker/hl_image_picker.dart';
final _picker = HLImagePicker();
List<HLPickerItem> _selectedImages = [];
_openPicker() async {
final images = await _picker.openPicker(
// Properties
);
setState(() {
_selectedImages = images;
});
}
属性
| 属性 | 描述 | 类型 |
|---|---|---|
| selectedIds | 一个字符串 ID 列表，代表从图库中最初选择的图片或视频。这允许用户在打开选择器之前预先选择项目。 | [String] |
| pickerOptions | 选择器的附加选项 | HLPickerOptions |
| cropping | 指示是否启用了裁剪。仅当 mediaType = MediaType.image 且 maxSelectedAssets = 1 时才有效。 |
布尔值 |
| cropOptions | 裁剪功能的配置选项 | HLCropOptions |
| localized | 为插件显示的自定义文本 | LocalizedImagePicker |
拍照或录制视频
import 'package:hl_image_picker/hl_image_picker.dart';
final _picker = HLImagePicker();
HLPickerItem? _selectedImage;
_openCamera() async {
final image = await _picker.openCamera(
// Properties
);
setState(() {
_selectedImage = image;
});
}
属性
| 属性 | 描述 | 类型 |
|---|---|---|
| cameraOptions | 相机功能的附加选项 | HLCameraOptions |
| cropping | 指示是否启用了裁剪 | 布尔值 |
| cropOptions | 裁剪功能的配置选项 | HLCropOptions |
| localized | 为插件显示的自定义文本 | LocalizedImageCropper |
打开图片裁剪器
import 'package:hl_image_picker/hl_image_picker.dart';
final _picker = HLImagePicker();
HLPickerItem? _selectedImage;
_openCropper_() async {
final image = await _picker.openCropper("image_path_to_crop",
// Properties
);
setState(() {
_selectedImage = image;
});
}
属性
| 属性 | 描述 | 类型 |
|---|---|---|
| imagePath | 需要裁剪的图片的路径 | 字符串 |
| cropping | 指示是否启用了裁剪 | 布尔值 |
| cropOptions | 裁剪功能的配置选项 | HLCropOptions |
| localized | 为插件显示的自定义文本 | LocalizedImageCropper |
HLPickerOptions
| 属性 | 描述 | 默认值 |
|---|---|---|
| mediaType | 您想要选择的媒体类型：MediaType.image、MediaType.video、MediaType.all。 |
MediaType.all |
| maxSelectedAssets | 可以选中的最大项目数。 | 1 |
| minSelectedAssets | 必须选中的最小项目数。 | |
| maxFileSize | 选定项目的最大允许文件大小。 | |
| minFileSize | 选定项目的最小允许文件大小。 | |
| enablePreview | 启用或禁用预览功能。（Android 上的点击和 iOS 上的长按） | 假 |
| convertHeicToJPG | 选择时将 HEIC 格式的图片转换为 JPEG 格式。（仅限 iOS） | 假 |
| convertLivePhotosToJPG | 选择时将 Live Photos 转换为 JPEG 格式。（仅限 iOS） | 真 |
| recordVideoMaxSecond | 录制视频的最大时长（秒）。 | 60 |
| isExportThumbnail | 确定是否为选定的视频导出缩略图。 | 假 |
| thumbnailCompressQuality | 导出的缩略图的压缩质量（0.1-1）。 | 0.9 |
| thumbnailCompressFormat | 导出的缩略图的图片格式：CompressFormat.jpg、CompressFormat.png。 |
CompressFormat.jpg |
| maxDuration | 选定视频的最大时长（秒）。 | |
| minDuration | 选定视频的最小时长（秒）。 | |
| numberOfColumn | 选择器列表中每行显示的的项目数。 | 3 |
| usedCameraButton | 确定是否在选择器列表中显示相机按钮。 | 真 |
HLCropOptions
| 属性 | 描述 | 默认值 |
|---|---|---|
| aspectRatio | 指定裁剪所需的纵横比。 | |
| aspectRatioPresets | 提供一组预定义的裁剪纵横比选项。 | |
| compressQuality | 确定导出图片的压缩质量（0.1-1）。 | 0.9 |
| compressFormat | 指定导出图片的图片格式：CompressFormat.jpg、CompressFormat.png。 |
CompressFormat.jpg |
| croppingStyle | 裁剪样式：CroppingStyle.normal、CroppingStyle.circular。 |
CroppingStyle.normal |
| maxSizeOutput | 设置导出图片的最大宽度和最大高度。 |
HLCameraOptions
| 属性 | 描述 | 默认值 |
|---|---|---|
| cameraType | 指定要使用的相机类型：CameraType.video、CameraType.image |
CameraType.image |
| recordVideoMaxSecond | 录制视频的最大时长（秒）。 | 60 |
| isExportThumbnail | 确定是否为录制的视频导出缩略图。 | 假 |
| thumbnailCompressQuality | 导出的缩略图的压缩质量（0.1-1）。 | 0.9 |
| thumbnailCompressFormat | 导出的缩略图的图片格式：CompressFormat.jpg、CompressFormat.png。 |
CompressFormat.jpg |
HLPickerItem (响应)
| 属性 | 描述 | 类型 |
|---|---|---|
| path | 项目的路径。 | 字符串 |
| id | 项目的唯一标识符。 | 字符串 |
| 名称 | 项目的文件名。 | 字符串 |
| mimeType | 项目的 MIME 类型。 | 字符串 |
| size | 项目的尺寸（以千字节 KB 为单位）。 | 整数 |
| width | 项目的宽度 | 整数 |
| 高度 | 项目的高度 | 整数 |
| 类型 | 指示项目是图片还是视频。 |
字符串 |
| duration | 视频的时长 | double? |
| thumbnail | 视频缩略图的路径 | String? |
LocalizedImagePicker
| 属性 | 描述 | 默认值 |
|---|---|---|
| maxDurationErrorText | 当选中的视频超过最大时长时显示的错误消息。 | 超出视频最大时长 |
| minDurationErrorText | 当选中的视频短于最小时长时显示的错误消息。 | 视频太短 |
| maxFileSizeErrorText | 当选中的文件超过最大文件大小时显示的错误消息。 | 超出最大文件大小 |
| minFileSizeErrorText | 当选中的文件小于最小文件大小时显示的错误消息。 | 文件大小太小 |
| noAlbumPermissionText | 当应用程序没有权限访问相册时显示的错误消息。 | 没有访问相册的权限 |
| noCameraPermissionText | 当应用程序没有权限访问相机时显示的错误消息。 | 没有访问相机的权限 |
| maxSelectedAssetsErrorText | 当超过最大项目数时显示的错误消息。 | 超出选定项目的最大数量 |
| minSelectedAssetsErrorText | 未满足最小项目数时显示的错误消息。 | 需要至少选择 {minSelectedAssets} 项 |
| noRecordAudioPermissionText | 当应用程序没有录制音频权限时显示的错误消息。 | 没有录制音频的权限 |
| doneText | 显示在“完成”按钮上的文本。 | 已完成 |
| cancelText | 显示在“取消”按钮上的文本。 | 取消 |
| loadingText | 当选择器处于加载状态时显示的文本。 | 加载 |
| defaultAlbumName | 默认相册的名称。 | 最近 |
| tapHereToChangeText | 显示在 defaultAlbumName 下方的文本。（仅限 iOS） |
点击此处更改 |
| okText | 显示在“确定”按钮上的文本。 | 确定 |
| emptyMediaText | 当没有可用媒体时显示的文本。（仅限 iOS） | 无可用媒体 |
| cropDoneText | 显示在“完成”按钮上的文本。（仅限 iOS） | 已完成 |
| cropCancelText | 显示在“取消”按钮上的文本。（仅限 iOS） | 取消 |
| cropTitleText | 在裁剪图片屏幕上显示的标题。（仅限 iOS） |
LocalizedImageCropper
| 属性 | 描述 | 默认值 |
|---|---|---|
| cropDoneText | 显示在“完成”按钮上的文本。（仅限 iOS） | 已完成 |
| cropCancelText | 显示在“取消”按钮上的文本。（仅限 iOS） | 取消 |
| cropTitleText | 在裁剪图片屏幕上显示的标题。（仅限 iOS） |
ProGuard
-keep class com.luck.picture.lib.** { *; }
-dontwarn com.yalantis.ucrop**
-keep class com.yalantis.ucrop** { *; }
-keep interface com.yalantis.ucrop** { *; }
开源库
iOS: TLPhotoPicker and TOCropViewController
Android: PictureSelector
