PictureSelector Library版本迁移指南：从v2.x到v3.x的变化
项目地址: https://gitcode.com/gh_mirrors/pict/PictureSelector 概述
PictureSelector 是一款针对Android平台下的图片选择器（Picture Selector Library for Android），支持从相册获取图片、视频、音频&拍照，支持裁剪(单图or多图裁剪)、压缩、主题自定义配置等功能，支持动态获取权限&适配Android 5.0+系统的开源图片选择框架。从v2.x版本升级到v3.x版本带来了许多重要的变化和改进，本指南将详细介绍这些变化以及如何顺利完成迁移。
主要变化概览
架构调整
v3.x版本对项目架构进行了重大调整，将原有的单一模块拆分为多个独立的功能模块，以实现更好的模块化和按需引入。主要模块包括：
- selector：核心选择器功能模块
- ucrop：图片裁剪模块
- compress：图片压缩模块
- camerax：自定义相机模块
这种模块化设计允许开发者根据项目需求选择性地引入所需功能，减少不必要的依赖和应用体积。
依赖管理变化
在v2.x版本中，开发者通常需要引入完整的PictureSelector库，而v3.x版本采用了更灵活的依赖管理方式。
v2.x版本依赖方式：
implementation 'com.luck.picture.lib:picture_library:2.5.8'
v3.x版本依赖方式：
// PictureSelector 基础 (必须)
implementation 'io.github.lucksiege:pictureselector:v3.11.2'
// 图片压缩 (按需引入)
implementation 'io.github.lucksiege:compress:v3.11.2'
// 图片裁剪 (按需引入)
implementation 'io.github.lucksiege:ucrop:v3.11.2'
// 自定义相机 (按需引入)
implementation 'io.github.lucksiege:camerax:v3.11.2'
详细的依赖配置可以参考项目的README_CN.md文件。
核心API变化
初始化方式
v3.x版本中，图片选择器的初始化方式发生了显著变化，引入了更加流畅的链式调用API。
v2.x版本初始化方式：
PictureSelector.create(MainActivity.this)
.openGallery(PictureMimeType.ofImage())
.maxSelectNum(9)
.minSelectNum(1)
.imageSpanCount(4)
.selectionMode(PictureConfig.MULTIPLE)
.forResult(PictureConfig.CHOOSE_REQUEST);
v3.x版本初始化方式：
PictureSelector.create(this)
.openGallery(SelectMimeType.ofImage())
.setImageEngine(GlideEngine.createGlideEngine())
.forResult(new OnResultCallbackListener<LocalMedia>() {
@Override
public void onResult(ArrayList<LocalMedia> result) {
// 处理选择结果
}
@Override
public void onCancel() {
// 处理取消操作
}
});
注意到v3.x版本中引入了ImageEngine概念，需要显式设置图片加载引擎。项目提供了多种图片引擎实现，包括：
回调机制变化
v3.x版本将传统的onActivityResult回调方式改为了更现代的监听器模式，简化了结果处理流程。
v2.x版本结果处理：
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (resultCode == RESULT_OK) {
switch (requestCode) {
case PictureConfig.CHOOSE_REQUEST:
List<LocalMedia> selectList = PictureSelector.obtainMultipleResult(data);
// 处理选择结果
break;
}
}
}
v3.x版本结果处理：
PictureSelector.create(this)
.openGallery(SelectMimeType.ofImage())
.setImageEngine(GlideEngine.createGlideEngine())
.forResult(new OnResultCallbackListener<LocalMedia>() {
@Override
public void onResult(ArrayList<LocalMedia> result) {
// 直接在这里处理选择结果
}
@Override
public void onCancel() {
// 处理取消操作
}
});
UI/UX改进
v3.x版本带来了全新的UI设计和用户体验改进，提供了多种预设主题风格，满足不同应用场景需求。
主题风格选择
v3.x版本提供了多种内置主题风格，包括默认风格、数字风格、白色风格等，开发者可以根据应用需求进行选择。
通过.setSelectorUIStyle()方法可以自定义选择器的UI样式，详细配置方法请参考主题API说明。
布局自定义
v3.x版本支持更灵活的布局自定义，可以通过重载布局文件来实现完全自定义的界面效果。
.setInjectLayoutResourceListener(new OnInjectLayoutResourceListener() {
@Override
public int getLayoutResourceId(Context context, int resourceSource) {
// 返回自定义布局资源ID
return 0;
}
})
项目中提供了多种自定义布局文件示例，例如：
新功能介绍
v3.x版本引入了多项重要新功能，提升了图片选择器的功能性和灵活性。
数据源单独获取
v3.x版本允许单独获取相册数据，而不需要打开选择器界面，这对于需要自定义相册界面的场景非常有用。
// 获取专辑列表
PictureSelector.create(this)
.dataSource(SelectMimeType.ofAll())
.obtainAlbumData(new OnQueryDataSourceListener<LocalMediaFolder>() {
@Override
public void onComplete(List<LocalMediaFolder> result) {
// 处理专辑数据
}
});
// 获取媒体文件列表
PictureSelector.create(this)
.dataSource(SelectMimeType.ofAll())
.obtainMediaData(new OnQueryDataSourceListener<LocalMedia>() {
@Override
public void onComplete(List<LocalMedia> result) {
// 处理媒体文件数据
}
});
自定义相机
v3.x版本引入了基于CameraX的自定义相机模块，提供了更强大的拍照功能和更好的兼容性。
PictureSelector.create(this)
.openCamera(SelectMimeType.ofImage())
.forResult(new OnResultCallbackListener<LocalMedia>() {
@Override
public void onResult(ArrayList<LocalMedia> result) {
// 处理拍照结果
}
@Override
public void onCancel() {
// 处理取消操作
}
});
自定义相机模块的详细使用方法请参考自定义相机文档。
媒体文件预览
v3.x版本提供了功能完善的媒体文件预览功能，支持图片、视频和音频的预览操作。
PictureSelector.create(this)
.openPreview()
.setImageEngine(GlideEngine.createGlideEngine())
.setExternalPreviewEventListener(new OnExternalPreviewEventListener() {
@Override
public void onPreviewDelete(int position) {
// 处理预览时的删除操作
}
@Override
public boolean onLongPressDownload(LocalMedia media) {
// 处理长按下载操作
return false;
}
}).startActivityPreview(position, true, list);
权限处理变化
随着Android系统版本的升级，权限管理变得越来越严格。v3.x版本针对权限处理进行了全面优化，提供了更细粒度的权限控制和更友好的权限申请流程。
权限声明
v3.x版本需要在AndroidManifest.xml中声明的权限有所变化：
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.CAMERA" />
<!-- Android 13版本适配，细化存储权限 -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
完整的权限声明列表请参考权限使用说明。
权限申请
v3.x版本提供了自定义权限申请的功能，可以根据应用需求定制权限申请流程：
.setPermissionsInterceptListener(new OnPermissionsInterceptListener() {
@Override
public void requestPermission(Fragment fragment, String[] permissionArray, OnRequestPermissionListener call) {
// 自定义权限申请逻辑
}
@Override
public boolean hasPermissions(Fragment fragment, String[] permissionArray) {
// 检查权限是否已授予
return false;
}
});
迁移步骤和注意事项
迁移步骤概览
- 更新项目依赖，替换v2.x版本为v3.x版本的模块化依赖
- 修改初始化代码，适应新的链式调用API
- 更新权限声明，添加Android 13所需的细化存储权限
- 调整结果回调处理方式，使用新的监听器模式
- 根据需要适配新的主题和UI样式
- 测试并验证所有图片选择相关功能
常见问题解决
1. 图片加载引擎设置
v3.x版本必须显式设置图片加载引擎，否则会导致图片无法正常加载：
// 正确设置方式
.setImageEngine(GlideEngine.createGlideEngine())
2. Android 11及以上沙盒机制适配
针对Android 10及以上版本的沙盒机制，v3.x提供了专门的文件处理方案：
.setSandboxFileEngine(new UriToFileTransformEngine() {
@Override
public void onUriToFileAsyncTransform(Context context, String srcPath, String mineType, OnKeyValueResultCallbackListener call) {
// 自定义沙盒文件处理逻辑
}
});
详细适配方法请参考沙盒机制文件处理文档。
3. 混淆配置更新
v3.x版本的混淆配置有所变化，需要更新proguard-rules.pro文件：
-keep class com.luck.picture.lib.** { *; }
// 如果引入了Camerax库请添加混淆
-keep class com.luck.lib.camerax.** { *; }
// 如果引入了Ucrop库请添加混淆
-dontwarn com.yalantis.ucrop**
-keep class com.yalantis.ucrop** { *; }
完整的混淆配置请参考混淆配置说明。
总结
PictureSelector从v2.x到v3.x的升级带来了许多重要改进，包括模块化架构、流畅的链式API、增强的自定义能力和更好的系统兼容性。虽然迁移过程需要一定的代码调整，但新版本提供的功能和灵活性提升是值得的。
迁移完成后，您的应用将能够支持更多图片选择场景，提供更好的用户体验，同时也能更好地适配最新的Android系统版本和特性。
如果在迁移过程中遇到任何问题，可以参考项目的常见错误文档或提交Issues寻求帮助。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
