GalleryPicker
GalleryPicker 是一个基于 Android 官方 Photo Picker API 封装的现代图片/视频选择库。它专注于提供统一、简洁、可兼容多 Android 版本的媒体选择能力，支持从相册获取图片/视频、拍照、图片裁剪、压缩等功能，且无需获取任何存储权限即可适配 Android 5.0+ 系统。
功能特性
- 无需权限：使用系统标准 Photo Picker，无需申请
READ_EXTERNAL_STORAGE权限（Android 11+）。 - 多版本适配：
- Android 11 (API 30) +：使用原生 Photo Picker。
- Android 4.4 (API 19) - Android 10 (API 29)：通过 Google Play 服务自动向后移植 Photo Picker，或回退到系统文件选择器 (
ACTION_OPEN_DOCUMENT)。
- 功能丰富：
- 支持单选/多选图片和视频。
- 支持调用相机拍照和录制视频。
- 支持图片裁剪（仅限单选）。
- 支持图片压缩（Luban 算法）。
- 支持混合单选（图片或视频）。
- 易于使用：链式调用，回调清晰。
接入指南
本文档提供了将 GalleryPicker 库集成到您的 Android 应用程序中的详细指南。
1. 添加依赖
在您的项目 build.gradle 文件中添加 JitPack 仓库和依赖项。
根目录 build.gradle:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}App 模块 build.gradle:
dependencies {
implementation 'com.github.darryrzhong:GalleryPicker:1.0.0' // 请检查最新版本
}2. 初始化全局配置 (可选)
你可以在 Application 中进行全局配置，如果不设置则使用默认配置。
GalleryPickerOption.setColorPrimary(R.color.purple_200) // 设置app主题色
.setTextColorPrimary(R.color.white) // 设置app主题色搭配字体色
.maxItems(1) // 设置最大选择数量 1 单选 >1多选
.isCompress(true) // 默认图片压缩
.ignoreSize(100) // 小于100kb文件不进行压缩
.quality(75) // 压缩比例 默认75%
.isCrop(false) // 是否进行图片裁剪 默认不裁剪
.maxVideoSize(15) // 最大选择视频文件大小 默认15Mb
.debug(false) // 日志调试3. 权限配置
特别提醒：使用 Photo Picker 选择媒体文件不需要任何存储权限。但是，如果需要使用相机拍照或录制视频，虽然 Android 11+ 调用系统相机不需要权限，但如果你的应用清单中声明了相机权限，则必须在运行时获取该权限。
<uses-permission android:name="android.permission.CAMERA" />4. 配置 FileProvider (仅拍照/录像需要)
为了让相机应用能够将拍摄的照片/视频保存到你的应用私有目录，需要配置 FileProvider。
- 在
AndroidManifest.xml中添加provider：
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}.fileprovider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/file_paths" />
</provider>- 在
res/xml目录下创建file_paths.xml：
<?xml version="1.0" encoding="utf-8"?>
<resources>
<paths>
<cache-path
name="picture_photo"
path="picture_photo/"/>
</paths>
</resources>进阶使用
使用 GalleryPickerHelper 进行媒体选择，无需关心页面跳转及生命周期管理。
1. 启动参数配置
启动参数的优先级高于全局默认配置。
GalleryPickerHelper.newInstance()
.isCompress(true)
.isCrop(true)
.ignoreSize(100) // kb
.quality(75) // 75%
.maxItems(9) // 单选 or 多选
.maxVideoSize(15) // 视频文件大小限制 MB
.launchMediaPicker(this, MediaType.IMAGE, object : MediaResultCallback {
override fun onMediaResult(mediaFiles: List<MediaData>) {
// 处理结果
}
})2. 相册获取 (单选)
GalleryPickerHelper.newInstance()
.launchMediaPicker(
requireActivity(),
MediaType.IMAGE, object : MediaResultCallback {
override fun onMediaResult(mediaFiles: List<MediaData>) {
mediaFiles.firstOrNull()?.let {
val paths = arrayListOf<String>()
paths.add(it.filePath)
// 预览图片
GalleryPickerHelper.toPreViewImage(requireActivity(), 0, paths)
}
}
})3. 相册获取 (多选)
GalleryPickerHelper.newInstance()
.maxItems(9)
.launchMediaPicker(
requireActivity(),
MediaType.IMAGE, object : MediaResultCallback {
override fun onMediaResult(mediaFiles: List<MediaData>) {
if (mediaFiles.isNotEmpty()) {
val paths = arrayListOf<String>()
mediaFiles.forEach {
paths.add(it.filePath)
}
GalleryPickerHelper.toPreViewImage(requireActivity(), 0, paths)
}
}
})
4. 相册获取 (带裁剪)
图片裁剪只支持单选模式。
GalleryPickerHelper.newInstance()
.isCrop(true)
.launchMediaPicker(
requireActivity(),
MediaType.IMAGE, object : MediaResultCallback {
override fun onMediaResult(mediaFiles: List<MediaData>) {
// 返回的是裁剪后的图片路径
mediaFiles.firstOrNull()?.let {
val paths = arrayListOf<String>()
paths.add(it.filePath)
GalleryPickerHelper.toPreViewImage(requireActivity(), 0, paths)
}
}
})5. 拍照选择
调用拍照前，请确保已处理好相机权限（如果清单文件中声明了）。
GalleryPickerHelper.newInstance()
.launchMediaPicker(
requireActivity(),
MediaType.CAMERA, object : MediaResultCallback {
override fun onMediaResult(mediaFiles: List<MediaData>) {
mediaFiles.firstOrNull()?.let {
val paths = arrayListOf<String>()
paths.add(it.filePath)
GalleryPickerHelper.toPreViewImage(requireActivity(), 0, paths)
}
}
})6. 视频选择
视频选择支持设置最大文件大小限制（默认 15MB）。目前仅支持单选。
GalleryPickerHelper.newInstance()
.launchMediaPicker(
requireActivity(),
MediaType.VIDEO, object : MediaResultCallback {
override fun onMediaResult(mediaFiles: List<MediaData>) {
mediaFiles.firstOrNull()?.let {
GalleryPickerHelper.toPreViewVideo(requireActivity(), it.filePath)
}
}
})7. 图片 & 视频混合选择
支持同时展示图片和视频，但用户只能选择其中一种类型（单选）。
GalleryPickerHelper.newInstance()
.launchMediaPicker(
requireActivity(),
MediaType.IMAGE_OR_VIDEO, object : MediaResultCallback {
override fun onMediaResult(mediaFiles: List<MediaData>) {
mediaFiles.firstOrNull()?.let {
if (it.mimeType == MimeType.VIDEO) {
GalleryPickerHelper.toPreViewVideo(requireActivity(), it.filePath)
} else if (it.mimeType == MimeType.IMAGE) {
val paths = arrayListOf<String>()
paths.add(it.filePath)
GalleryPickerHelper.toPreViewImage(requireActivity(), 0, paths)
}
}
}
})8. 拍摄视频
GalleryPickerHelper.newInstance()
.launchMediaPicker(
requireActivity(),
MediaType.CAPTURE_VIDEO, object : MediaResultCallback {
override fun onMediaResult(mediaFiles: List<MediaData>) {
mediaFiles.firstOrNull()?.let {
GalleryPickerHelper.toPreViewVideo(requireActivity(), it.filePath)
}
}
})9. 辅助功能
图片预览 (仅支持本地路径):
GalleryPickerHelper.toPreViewImage(this, 0, arrayListOf("path1", "path2"))视频预览 (仅支持本地路径):
GalleryPickerHelper.toPreViewVideo(this, "video_path")检查设备兼容性:
GalleryPickerHelper.isPhotoPickerAvailable(this)
设备兼容性说明
照片选择器适用于符合以下条件的设备：
- 搭载 Android 11 (API 30) 或更高版本。
- 通过 Google 系统更新接收对模块化系统组件的更改。
对于搭载 Android 4.4 (API 19) 到 Android 10 (API 29) 的设备，以及搭载 Android 11 或 12 且支持 Google Play 服务的 Android Go 设备，Google Play 服务会自动安装向后移植的照片选择器模块。
如需通过 Google Play 服务自动安装向后移植的照片选择器模块，请将以下条目添加到应用清单文件的 标记中:
<!-- Trigger Google Play services to install the backported photo picker module. -->
<service android:name="com.google.android.gms.metadata.ModuleDependencies"
android:enabled="false"
android:exported="false"
tools:ignore="MissingClass">
<intent-filter>
<action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>
<meta-data android:name="photopicker_activity:0:required" android:value="" />
</service>如果照片选择器不可用，本库会自动降级调用 ACTION_OPEN_DOCUMENT intent，以系统文件管理器的方式进行媒体选择（此时系统会忽略最大选择数量限制）。
浙公网安备 33010602011771号