ImagePicker 完全入门指南：为什么它是 Android 图片选择器开发的首选方案

ImagePicker 完全入门指南：为什么它是 Android 图片选择器开发的首选方案

【免费下载链接】ImagePickerA customizable library for selecting images on the device.项目地址: https://gitcode.com/gh_mirrors/imagepi/ImagePicker

ImagePicker是一个专为 Android 应用设计的开源图片选择器库，帮你用几行代码实现相册选图、拍照、多选、按文件夹浏览等完整功能，并支持高度自定义 UI 配色与图标。对于正在做 Android 开发的初学者来说，它是替代系统 Intent 选图、减少权限处理负担的快速方案。

为什么选 ImagePicker 而不是自己实现？

自己写一个图片选择器，你需要处理：相册权限（Android 13 前后差异巨大）、媒体扫描、缩略图加载、多选状态管理、拍照存储、UI 布局……工作量不小。

ImagePicker 把这些全部封装好了，核心优势有 5 点：

1. 开箱即用：一行launcher.launch()即可调起选择器，无需配置权限逻辑
2. 内置拍照：基于 CameraX，支持直接拍摄并将图片保存到相册
3. 文件夹模式：默认按相册/文件夹分组浏览，和系统相册体验一致
4. 高度可定制：颜色、图标、文案、网格列数、排序方式、数量限制全部可配
5. 轻量：基于 Kotlin + Jetpack 组件，源码结构清晰易读

快速开始：3 步集成图片选择器

第 1 步：添加 JitPack 仓库与依赖

在settings.gradle中配置仓库，然后在app模块的build.gradle中添加依赖：

// settings.gradle dependencyResolutionManagement { repositories { maven { url 'https://jitpack.io' } } } // app/build.gradle dependencies { implementation 'com.github.nguyenhoanglam:ImagePicker:1.6.4' }

第 2 步：注册选择器回调

在Activity或Fragment中声明一个launcher，选完图后回调会收到图片列表：

private val launcher = registerImagePicker { images -> if (images.isNotEmpty()) { val image = images[0] // ImagePicker 图片选择器返回的图片对象 Glide.with(this).load(image.uri).into(imageView) } }

第 3 步：启动选择器

// 默认配置 launcher.launch() // 自定义配置 val config = ImagePickerConfig( isFolderMode = true, // 文件夹模式 isShowCamera = true, // 显示拍照按钮 limitSize = 10, // 最多选 10 张 selectedIndicatorType = IndicatorType.NUMBER // 角标显示序号 ) launcher.launch(config)

💡 示例工程 MainFragment.kt 展示了在 Fragment 中使用的标准写法，可直接参考。

核心配置项速查表

所有配置集中在 ImagePickerConfig.kt，常用项如下：

配置项	作用	默认值
isCameraMode	直接调起相机拍照，跳过相册	false
isSingleSelectMode	单选模式，选中即返回	false
isFolderMode	按文件夹分组浏览	true
isShowCamera	工具栏显示拍照按钮	true
isSelectAllEnabled	显示"全选"按钮	true
limitSize	最大可选图片数量	不限制
imageSort	排序方式（时间/修改时间/名称）	按添加时间倒序
selectedImages	预先标记为已选中的图片	空列表
customColor	自定义主题色	内置深色主题
customDrawable	自定义工具栏图标	内置图标
customMessage	自定义提示文案（如权限说明）	内置文案

主题定制：一键匹配你的 App 风格

通过customColor可以替换工具栏、背景、角标、SnackBar 等所有颜色：

customColor = CustomColor( background = "#000000", toolbar = "#212121", toolbarTitle = "#FFFFFF", selectedImageIndicator = "#1976D2" )

图标方面，customDrawable支持替换返回键、拍照按钮、全选/取消全选等 6 类图标（建议 24dp 尺寸）。

权限处理：完全托管，不用操心

这是新手最容易踩坑的地方，而 ImagePicker 内部已自动处理（见 ImagePickerActivity.kt）：

• Android 13+：申请READ_MEDIA_IMAGES权限
• Android 13 以下：申请READ_EXTERNAL_STORAGE权限
• 权限被拒：弹出 SnackBar 引导用户跳转系统设置

你不需要在AndroidManifest.xml中额外声明任何存储权限（声明CAMERA可启用拍照按钮的权限预检）。

源码结构一览：想深入时看哪里

项目采用经典分层结构，核心模块路径如下：

• 入口 API：ImagePicker.kt ——ImagePickerLauncher与registerImagePicker扩展函数
• 选择器主界面：ImagePickerActivity.kt —— 整合工具栏、文件夹/图片列表、预览弹窗
• 拍照模块：CameraModule.kt 与 CameraActivity.kt
• 配置模型：ImagePickerConfig.kt —— 所有可配置项及默认值
• 图片数据模型：Image.kt —— 返回的Image含uri、name、bucketName、addedDate
• 示例工程：example/src/main/java/com/imagepicker/example/MainActivity.kt —— 完整配置演示

常见问题 FAQ

Q：返回的图片是什么格式？回调返回ArrayList<Image>，每个Image包含uri（内容 URI）、文件名、所属文件夹和添加时间。用 Glide 等库直接加载uri即可。

Q：支持最低版本？minSdkVersion 21，覆盖 Android 5.0 及以上设备。

Q：可以先预选部分图片吗？可以，通过selectedImages参数传入Image列表，下次打开选择器时这些图片会保持选中状态，非常适合"编辑资料头像"这类场景。

总结

ImagePicker 以极小的接入成本，覆盖了 Android 图片选择器开发中的全部痛点：权限、相册浏览、多选、拍照、主题定制。对于追求开发效率的团队和个人开发者，它是值得直接集成的首选方案 🚀

【免费下载链接】ImagePickerA customizable library for selecting images on the device.项目地址: https://gitcode.com/gh_mirrors/imagepi/ImagePicker