图片选择器
最新版本 8.2.0
Github 地址: filepicker
-
微信选择库样式风格,完全防微信,图片编辑功能对齐,头像剪裁,超越微信的更多场景。
-
用了很多,都没有丝滑的选择效果的开源库,滑动选择丝滑。闲来没事,随手写一个吧。
-
图库选择,文件选择
-
仿华为相册滑动选择手势逻辑,
-
支持多选,限制数量,不限制数量。
-
选择条件可限定:图片 / 视频各自限量(如图片 9 张、视频 1 个),可以要求必须选够,
也能让图片和视频只能选其中一类(互斥)。见「按类型限量」一节。 -
使用场景,多用于 视频剪辑选择库,相册管理选择库,朋友圈选图或者视频。
-
使用最新版的 filepicker 库,必须使用最新版的xwidget库。都是 5.8.1 以上确保。
好不好用,直接安装。
- 扫码:
demo 已经按「使用场景」重构,每个场景各自选项 + 「开始」+ 结果展示,互不干涉:
普通选择 / 规则 / 文件 / 头像裁剪 / 点击编辑 / 预览编辑 / 拍照直出 / 录像直出。
功能总览
按重要度排序:先"选图",再"编辑",再"头像裁剪",最后是外围能力。
| 优先级 | 能力 | 说明 | 入口 |
|---|---|---|---|
| 1 | 图片 / 视频 / 文件选择 | 图库网格、滑动选择、单选/多选、数量与大小限制 | 基本用法 |
| 2 | 图片编辑 | 画笔(涂鸦)、文字、裁剪、马赛克;会话级覆盖不改原图,完成后发布相册;支持「点击即编辑」 | 3.1 图片编辑 |
| 3 | 头像裁剪 | setAvatarCropMode(true);支持固定比例/自由裁剪,框可拖拽、可锁比例、初始大小可调 | 3.2 头像裁剪 |
| 4 | 预览 | 单图预览(可编辑)、多选预览(可逐张编辑)、底部已选缩略图条 | 基本用法 |
| 5 | 分类型限量 / 互斥 | 「图片 9 张 + 视频 1 个」「必须选够」「二选一」 | 基本用法 §6 |
| 6 | 相机入口 / 直接相机 | 网格内拍照入口;setOpenCameraDirect 完全不经过列表(仅图片/视频) | 3.3 直接相机 |
| 7 | 多类型文件 | 音频、文档、PDF、APK、压缩包、自定义后缀 | 基本用法 §3 |
| 8 | UI 配置 / 多语言 | 文案、颜色、图标、编辑页完整 i18n | FilePickerUIConfig |
| 9 | 编辑产物 / 缓存 | 成品发布到 Pictures/filepicker/,返回真实路径;临时缓存返回时异步清理 | 编辑结果说明 |
功能展示
以下截图均来自 demo(
app/),小图展示;完整交互直接运行 demo 体验。
demo 首页:多个界面分别展示 不同场景用法。
普通选择 | 规则 | 文件 | 头像裁剪 |
点击编辑 | 预览编辑 | 拍照直出 | 录像直出 |
图片选择与预览
多选网格(已选 6 张) | 大图预览 / 编辑入口 |
图片编辑(画笔 / 文字 / 裁剪 / 马赛克)
画笔 | 画笔颜色/粗细 | 文字输入 | 文字效果 | 马赛克(像素/模糊) |
头像裁剪
头像裁剪参数 | 头像裁剪页 |
文件选择(音频 / 文档 / PDF / APK / 压缩包 / 自定义后缀)
/tr>
单独 Word 文档 | PDF / 文档混排 |
目录
| 章节 | 内容 |
|---|---|
| 一、快速接入 | 依赖版本、Gradle 接入 |
| 二、基本用法 | Activity / Fragment 启动、选择文件、拍照、分类型限量 |
| 三、功能模块 | 图片编辑(画笔/文字/裁剪/马赛克)、头像裁剪 |
| 四、API 文档 | FilePicker、Builder、FilePickerSelectType、FilePickerUIConfig |
| 五、常见问题与温馨提示 | 常见坑与建议 |
| 特别鸣谢 | 依赖的开源库 |
| 版本记录 | 各版本升级日志 |
一、快速接入
1.1 依赖与版本
依赖说明
- 下面的这个三方库,本maven仓库中的aar都过滤掉了。建议自己从下面引用,防止库冲突。
dependencies {
// 基础组件库 (必须)
implementation("com.gitee.pichs:filepicker:8.2.0")
// 基础组件库 (必须)
implementation("com.gitee.pichs:xwidget:5.8.1")
// glide 图片加载 (必须)
implementation("com.github.bumptech.glide:glide:4.16.0")
//基础库(必须)
implementation(libs.androidx.core.ktx)
implementation(libs.androidx.appcompat)
implementation(libs.androidx.activity.ktx)
implementation(libs.androidx.fragment.ktx)
implementation(libs.material)
implementation(libs.androidx.recyclerview)
implementation(libs.androidx.annotation)
implementation(libs.kotlinx.coroutines.android)
implementation(libs.kotlinx.coroutines.core)
// brv (必须)
implementation("com.github.liangjingkanji:BRV:1.6.1")
// 弹窗 (必须)
implementation("io.github.razerdp:BasePopup:3.2.1")
// 视频播放库 (必须)采用exoplayer
implementation("androidx.media3:media3-exoplayer:1.7.1")
implementation("androidx.media3:media3-ui:1.7.1")
}
使用libs.version.toml用户引入方式
dependencies {
api(libs.filepicker)
api(libs.xwidget)
api(libs.glide)
api(libs.brv)
api(libs.basepopup)
api(libs.media3.exoplayer)
api(libs.media3.ui)
}
#### libs.versions.toml 写法
[versions]
xwidget="5.8.1"
filepicker="8.2.0"
brv="1.6.1"
basepopup="3.2.1"
glide="4.16.0"
activityKtx="1.9.0"
fragmentKtx="1.6.2"
recyclerview="1.4.0"
kotlinxCoroutinesAndroid="1.7.3"
kotlinxCoroutinesCore="1.7.3"
media3Exoplayer="1.7.1"
[libraries]
androidx-media3-exoplayer={module="androidx.media3:media3-exoplayer",version.ref="media3Exoplayer"}
androidx-media3-ui={module="androidx.media3:media3-ui",version.ref="media3Exoplayer"}
androidx-activity-ktx={group="androidx.activity",name="activity-ktx",version.ref="activityKtx"}
androidx-fragment-ktx={group="androidx.fragment",name="fragment-ktx",version.ref="fragmentKtx"}
androidx-recyclerview={group="androidx.recyclerview",name="recyclerview",version.ref="recyclerview"}
kotlinx-coroutines-android={group="org.jetbrains.kotlinx",name="kotlinx-coroutines-android",version.ref="kotlinxCoroutinesAndroid"}
kotlinx-coroutines-core={group="org.jetbrains.kotlinx",name="kotlinx-coroutines-core",version.ref="kotlinxCoroutinesCore"}
xwidget={group="com.gitee.pichs",name="xwidget",version.ref="xwidget"}
filepicker={group="com.gitee.pichs",name="filepicker",version.ref="filepicker"}
basepopup={group="io.github.razerdp",name="BasePopup",version.ref="basepopup"}
brv={group="com.github.liangjingkanji",name="BRV",version.ref="brv"}
glide={group="com.github.bumptech.glide",name="glide",version.ref="glide"}
二、基本用法
1. 在 Activity 中启动
FilePicker.with(this) // this: FragmentActivity
.setSelectType(FilePickerSelectType.ofImage()) // 设置选择类型
.setMaxSelectNumber(9) // 设置最大选择数量
.setSlideChooseEnable(true) // 开启滑动选择
.setOnSelectCallback(object : OnSelectCallback {
override fun onSelectedCallback(isUseOriginal: Boolean, list: MutableList<MediaEntity>) {
// 选择完成回调
println("是否使用原图: $isUseOriginal")
list.forEach {
println("文件路径: ${it.path}")
}
}
override fun onCancel() {
// 取消选择
}
})
.setUiConfig(
FilePickerUIConfig(
isHideSelectTab = false,
allAlbumName = "全部",
confirmBtnText = "发送",
isShowOriginal = false,
isPreviewPageIndexMode = true,
isShowSelectedListDeleteIcon = true,
folderNickNameMap = hashMapOf(
"DCIM" to "相册"
)
)
).
.start()
2. 在 Fragment 中启动
FilePicker.with(this) // this: Fragment
.setSelectType(FilePickerSelectType.ofImage())
.setMaxSelectNumber(5)
.setMaxFileSize(50 * 1024 * 1024) // 50MB
.setMinFileSize(1 * 1024) // 1KB
.setOnSelectCallback { isUseOriginal, list ->
// 选择完成回调
}
.setUiConfig(
FilePickerUIConfig(
isHideSelectTab = true,
allAlbumName = "全部",
confirmBtnText = "下一步",
isShowOriginal = false,
isPreviewPageIndexMode = true,
isShowSelectedListDeleteIcon = true,
folderNickNameMap = hashMapOf(
"DICM" to "相机",
"Download" to "下载"
)
)
).
.start()
3. 选择文件(音频 / 文档 / 压缩包)
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofAudio()) // 文件类型:ofAudio/ofDocument/ofPdf/ofApk/ofZipAll...
.setMaxSelectNumber(1)
.setSingleClickEnable(true) // 单击直接返回,文件选择场景常用
.setOnSelectCallback { isUseOriginal, list ->
// 返回 MediaEntity(含 path/name/mimeType/size)
}
.start()
4. 自定义后缀过滤
任意后缀组合,不需要为每种后缀单独加类型:
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofExtensions("xz", "tar", "bak"))
.start()
有专属类型入口的后缀(图片、音频、文档、核心压缩包等)优先用
ofXxx(),
两者在 UI 模式与预览上的差异见下方 类型入口怎么选。
详见下方 自定义后缀过滤。
5. 拍照 / 录像入口(默认关闭)
在网格第一格放一个"相机"格子,点击调起系统相机拍照或录像,拍完自动插到列表第一个。
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofImage()) // 或 ofVideo()
.setShowCameraEntry(true)
.start()
默认 false:不开启时这条链路完全不参与 —— 不占列表格子、不注册 viewType、不请求权限,
对宿主等同于不存在。
生效条件:setShowCameraEntry(true),且当前类型下相机能产出点东西(图片或视频)。
GIF / 音频 / 文档不显示;有 tab 的类型里入口跟着当前 tab 走。
格子的画法按"能产出几种"决定:
| 当前生效类型 | 格子 |
|---|---|
只有图片(ofImage(),或 ofAll() 的「图片」页) | 整格 = 拍照 |
只有视频(ofVideo(),或 ofAll() 的「视频」页) | 整格 = 录像 |
图片 + 视频(ofAll() / ofAllWithGif() 的「全部」页) | 从中间劈开:左半边录像、右半边拍照 |
| 只有 GIF(「GIF」页) | 不显示入口 |
行为说明:
| 项 | 说明 |
|---|---|
| 位置 | 网格左上角第一格,随列表滚动,尺寸与相邻格子一致 |
| 点击 | 调起系统相机(拍照 ACTION_IMAGE_CAPTURE / 录像 ACTION_VIDEO_CAPTURE) |
| 拍完 | 自动插到列表第一个位置,并默认勾选上("这张就是要用的") |
| 已到上限 | 仍然插入,但不勾选(不会超过 maxSelectNumber),并 toast 提示 |
| 单选立即返回 | maxSelectNumber == 1 且开了 setSingleClickEnable(true) 时,拍完直接回调返回,\ |
拍到的这张会**替换**掉已有选择(宿主通过 `setSelectedList` 预置的那张也一样) |
| 大小超限 | 产物不符合 minFileSize / maxFileSize 时不插入、不勾选,toast 提示(文案见
cameraEntrySizeLimitToastContent) |
| 产物落地 | 写进系统相册(DCIM/Camera),和系统相机拍的照片放在一起 |
| 取消拍摄 | 会清理掉本次产生的空记录/空文件,不会在相册里留下打不开的空条目 |
| 图标与文案 | 图标默认用库内资源,可换 cameraEntryIconResId(拍照)/ cameraEntryVideoIconResId(录像);
文字标签用 cameraEntryPhotoText / cameraEntryVideoText |
权限与 manifest:
-
库不声明也不占用 CAMERA 权限 —— 拍摄由相机 App 自己完成,调用方不需要该权限。
但如果宿主 App 自己声明了android.permission.CAMERA却还没授权,ACTION_IMAGE_CAPTURE/
ACTION_VIDEO_CAPTURE会直接抛SecurityException(系统规定)。这种情况下库会先申请权限,
授权后自动继续拍摄。真机实测原话(华为 BRE-AL80 / Android 12,宿主声明了但未授权):
Permission Denial: starting Intent { act=android.media.action.VIDEO_CAPTURE ... } with revoked permission android.permission.CAMERA -
库不往宿主 manifest 里加任何东西(没有
<provider>、没有<queries>)。 -
产物写入系统相册:Android 10+ 不需要任何存储权限;Android 7.0–9 需要
WRITE_EXTERNAL_STORAGE
(与本库查询相册本身的前提一致)。
为什么不用
resolveActivity()判断有没有相机 App(官方文档推荐这么写):
宿主 targetSdk ≥ 30 时,没声明<queries>的应用会被包可见性过滤,resolveActivity()/
queryIntentActivities()对这几个相机 action 一律返回 null / 0,但startActivity依然能成功。
同一台华为设备上实测:四个相机 action 的resolveActivity全是null,而实际能起
com.huawei.camera/com.android.camera.VideoCamera。用resolveActivity() != null当守卫
会让相机入口永远点不动。本库因此改成startActivity包 try/catch。
6. 按类型限量(图片 N 张 / 视频 M 个 / 互斥)
setMaxSelectNumber 只能管一个总数。7.2.0 起新增按类型分别限量:图片、视频各自设上限,
可以要求"必须选够",也可以要求"图片和视频只能选其中一类"。
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofAll())
.setSelectRules(
SelectRule.ofImage(0, 9), // 图片最多 9 张(min = 0 表示不强制)
SelectRule.ofVideo(0, 1), // 视频最多 1 个
)
.start()
SelectRule.ofImage(min, max) / ofVideo(min, max) / ofGif(min, max):
-
max:该类型的硬上限,到顶后勾不上,提示"图片最多选择2个"; -
min > 0:必须选。提交时数量必须落在min..max内;不满足时确定按钮不高亮,
点击提示"图片必须选3个",且不会返回; -
没配规则的类型不受限制。
| 需求 | 写法 |
|---|---|
| 图片 ≤ 9、视频 ≤ 1,可混选 | setSelectRules(SelectRule.ofImage(0, 9), SelectRule.ofVideo(0, 1)) |
| 图片必须正好 9 张 | setSelectRules(SelectRule.ofImage(9, 9)) |
| 视频必须 1 个、图片最多 9 张 | setSelectRules(SelectRule.ofVideo(1, 1), SelectRule.ofImage(0, 9)) |
| 图片和视频只能选其中一类 | 上面的规则 + .setExclusive(true) |
| 合计最多 5 个(不分类,旧模型) | .setMaxSelectNumber(5)(配了规则后无效:不互斥=各 max 累加,互斥=取最大 max) |
| GIF 不占图片额度 | .setGifCountsAsImage(false) |
⚠️
setMaxSelectNumber是旧模型的"合计上限":只要调用了setSelectRules(...),
这个数字就完全不生效(库会打 warn 日志),最终合计上限由规则推导,互斥与否算法不同:
规则形态 合计上限算法 示例(图片 max=9、视频 max=1) 不互斥(默认) 各类型 max累加最多 10 个 互斥( setExclusive(true))取各类型 max的最大值最多 9 个(只能选一类) 某个类型 max设为不限(Int.MAX_VALUE,默认值)合计不限 不限 一个规则都没配 回退旧模型, setMaxSelectNumber生效— 所以上面例子写
setMaxSelectNumber(5)没有任何作用:不互斥时上限是 10、互斥时是 9。
新项目直接用规则表达即可,不要再传第二个数字。
互斥(setExclusive(true))的锁定规则:
-
只有一类配了
min > 0→ 直接锁定那一类,另一类点了会被拦下(等于"只能选图片 / 只能选视频"); -
两类都配了
min > 0→ 先点哪类就锁定哪类,另一类的"必须选"本次作废; -
已选类型全部取消后自动解锁,可以改选另一类。
启用条件(重要):setExclusive(...) 和 setGifCountsAsImage(...) 只有在配置了
setSelectRules(...) 之后才生效。一个规则都不配时,它们会被忽略(打 warn 日志),
数量限制仍由 setMaxSelectNumber(n) 决定 —— 这样"只开互斥、没配规则"不会把你设的最大数量弄丢。
和 setMaxSelectNumber 的关系:用了规则,setMaxSelectNumber 就不生效了。
数量限制始终只有一个来源:
-
不用规则 →
setMaxSelectNumber(n)是唯一口径(老行为); -
用了规则 → 合计上限由各类型
max自动叠加得出(互斥时取单类型最大的max),
调用方不需要再写第二个数字,也就不存在"合计上限和规则冲突"这种配置。
所以规则模式下没有任何"谁优先"的抉择 —— 从设计上就没有第二个数字。
三个提示文案都可以在 FilePickerUIConfig 里改:selectTypeMaxToastContent("图片最多选择2个")、
selectExclusiveConflictToastContent("当前只能选择视频")、selectRuleNotSatisfiedToastContent
("图片必须选3个")。
预选列表(
setSelectedList)超出规则时会按规则截断并打 warn 日志,不会静默吞掉。
三、功能模块
3.1 图片编辑(画笔 / 文字 / 裁剪 / 马赛克)
在预览页直接编辑图片:画笔(涂鸦)/ 文字 / 裁剪 / 马赛克。
编辑结果不修改原图;点「完成」后把最终合并图保存到系统相册Pictures/filepicker/,
返回给调用方的就是编辑后的真实图片地址。
开启编辑(开关)
编辑入口默认关闭,需要显式打开:
FilePicker.with(this)
.setEditInPreviewEnable(true) // ← 开关:预览页是否出现「编辑」入口
.start()
开启后:
-
单图预览页右上角出现「编辑」
-
多选预览页(首页选完 N 张 → 预览)同样出现「编辑」,可逐张编辑
完整示例
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofImage())
.setMaxSelectNumber(9)
// 1) 预览页可编辑(默认 false,必须显式打开)
.setEditInPreviewEnable(true)
// 2) 头像裁剪参数不在这里配:见下方「头像裁剪(独立裁剪页)」
// 3) 编辑临时缓存目录(可选,默认 Android/data/<包名>/cache/filepicker/)
.setEditCacheDir(cacheDir.absolutePath)
.setOnSelectCallback { isUseOriginal, list ->
list.forEach { entity ->
// 返回结果里的 path / uri 就是最终要用的图片地址:
// - 没编辑过 = 原图
// - 编辑过 = 编辑后的成品(Pictures/filepicker/xxx.jpg)
// 会话内的临时字段 editedPath 在返回时已清空,这里不需要(也不应该)读它
uploadFile(entity.path)
}
}
.start()
编辑结果说明
| 字段 / API | 含义 |
|---|---|
MediaEntity.path / uri | 原图地址;从选择器返回结果时,编辑过的条目已换成编辑后的真实地址 |
MediaEntity.editedPath | 会话内编辑产物地址(预览、已编辑角标使用),返回结果时清空 |
FilePicker.clearEditCache(context) | 手动清理编辑临时缓存(返回调用方时库已自动异步清理) |
FilePicker.editCacheSize(context) | 当前编辑缓存大小(字节) |
FilePicker.editCacheDir(context) | 编辑缓存目录 |
-
编辑产物发布位置:
Pictures/filepicker/filepicker_edit_yyyyMMdd_HHmmss.jpg
(系统相册可见,下次选择可直接再次选中) -
头像裁剪:
setAvatarCropAspectRatio(1f),单选模式下点图片直接进入 1:1 裁剪页
多语言(i18n)
编辑/裁剪页的所有文案都在 FilePickerUIConfig 里,接入方按自己 App 的语言注入即可
(下面的 getString(...) 就是各自 strings.xml 里的多语言资源):
val uiConfig = FilePickerUIConfig(
// 顶栏
editCancelText = getString(R.string.picker_cancel),
editDoneText = getString(R.string.picker_done),
editUndoLabel = getString(R.string.picker_undo),
editRedoLabel = getString(R.string.picker_redo),
// 主菜单工具名(无障碍/读屏用)
editToolBrushLabel = getString(R.string.picker_brush),
editToolTextLabel = getString(R.string.picker_text),
editToolCropLabel = getString(R.string.picker_crop),
editToolMosaicLabel = getString(R.string.picker_mosaic),
// 二级面板
editBrushSizeLabel = getString(R.string.picker_brush_size),
editTextFontModeLabel = getString(R.string.picker_text_font_mode),
editTextBgModeLabel = getString(R.string.picker_text_bg_mode),
editColorDotLabelFormat = getString(R.string.picker_color_format), // 含 %1$d
mosaicPixelLabel = getString(R.string.picker_mosaic_pixel),
mosaicBlurLabel = getString(R.string.picker_mosaic_blur),
editEraserLabel = getString(R.string.picker_eraser),
// 裁剪页
cropRotateLabel = getString(R.string.picker_rotate),
cropMirrorLabel = getString(R.string.picker_mirror),
cropResetText = getString(R.string.picker_reset), // 「还原」
cropCancelLabel = getString(R.string.picker_crop_cancel),
cropConfirmLabel = getString(R.string.picker_crop_confirm),
// 提示
editLoadImageFailedToastContent = getString(R.string.picker_load_failed),
editSaveFailedToastContent = getString(R.string.picker_save_failed),
)
FilePicker.with(this)
.setUiConfig(uiConfig)
.setEditInPreviewEnable(true)
.start()
setAvatarCropResetText("还原")只是一个便捷方法,内部就是写
uiConfig.cropResetText;做完整多语言时建议统一用FilePickerUIConfig配。
这些字段都有中文默认值,不传也能正常用。
单图点击直接编辑(不用勾选、不用点「编辑」)
想让用户「点一张图 → 直接进编辑弹窗 → 编辑完返回」,用 setEditOnClickEnable(true):
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofImage())
.setEditOnClickEnable(true) // ← 点图直接弹编辑弹窗(自动强制单选 + 单击)
.start()
| 操作 | 行为 |
|---|---|
| 点任意图片 | 直接弹出编辑弹窗(画笔/文字/裁剪/马赛克),不需要先勾选、也不需要进预览页点「编辑」 |
| 编辑弹窗「完成」 | 生成编辑后成品(发布到 Pictures/filepicker/),直接返回给调用方,结果 path = 成品地址 |
| 编辑弹窗「取消」/返回键 | 只关闭弹窗,回到选择器继续选(不返回、不产生文件) |
| 相机入口拍照 | 拍完点确定也会直接进编辑弹窗(开着相机入口时) |
说明与约束:
-
该模式由库强制:单选 + 单击即编辑;
setMaxSelectNumber/setSelectRules会被忽略(打 warn 日志)。 -
与
setAvatarCropMode(true)同时开启时,头像裁剪优先(会打 warn 日志)。 -
setEditInPreviewEnable是「先选、再在预览里编辑」;setEditOnClickEnable是「点一张就编辑」——
两者是不同入口,按产品交互选一个即可。
注意事项
-
编辑是会话级覆盖:不改原图文件、不覆盖相册原图;「已编辑」角标显示在缩略图左下角(16dp)。
-
再次进入选择器并传入
setSelectedList(list)时,编辑过的条目以编辑后的图展示。 -
Android 10+ 发布到相册走 MediaStore(无需存储权限);9 及以下写公共目录并触发媒体扫描。
-
文字/画笔比例相对原图短边:裁剪只裁图片,已有文字/画笔仍可编辑,越界部分自然裁掉。
3.2 头像裁剪(独立裁剪页)
头像场景:单选、点一张图直接进入 1:1 裁剪页(独立 Activity),裁剪确认后返回成品图。
不经过编辑弹窗,也不修改相册原图。
⚠️ 头像裁剪是「霸道」模式(务必先看)
只有在 setAvatarCropMode(true) 开启后,库才会接管以下参数(并打 warn 日志),
不需要、也无法通过其它参数改变"单张 + 直接裁剪"的行为:
| 你设置的参数 | 头像模式下的实际行为 |
|---|---|
setMaxSelectNumber(n) | 强制为 1(传 0/9/任意值都一样,日志会提示被忽略) |
setSingleClickEnable(false) | 强制为 true(点图即进裁剪页) |
setSelectRules(...) | 不生效(规则模式让位,日志提示被忽略) |
setEditInPreviewEnable(...) | 不受影响(多选预览编辑照常,但头像模式只有 1 张) |
原因:头像裁剪的结果是"一张裁剪后的头像",一次只能处理一张,所以数量/规则参数在这里没有意义。
怎么调(最简写法)
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofImage())
.setAvatarCropMode(true) // ← 总开关(默认 false,不开就没有头像裁剪)
.setAvatarCropAspectRatio(1f) // 可选:比例,不设默认 1:1
.setAvatarCropOutputMaxSize(1024) // 可选:导出最长边(头像 512~1024 足够)
.setAvatarCropQuality(95) // 可选:导出质量 60~100
.setOnSelectCallback { _, list ->
val avatar = list.firstOrNull()
// 返回时 path / uri 已经是裁剪后的成品地址(Pictures/filepicker/xxx.jpg)
Log.d("avatar", "裁剪结果: ${avatar?.path}")
}
.start()
其它比例同理:setAvatarCropAspectRatio(4f / 3f)、setAvatarCropAspectRatio(16f / 9f);
不调用 setAvatarCropAspectRatio 时头像模式默认 1:1。
裁剪框大小 / 可拖拽 / 比例锁定(8.2+)
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofImage())
.setAvatarCropMode(true)
.setAvatarCropAspectRatio(1f) // 0 = 自由裁剪;不设置 = 默认 1:1
.setAvatarCropResizable(true) // 框能否拖拽改大小;默认 false
.setAvatarCropRatioLocked(false) // 可拖但不锁比例(自由拉宽拉高);默认 true
.setAvatarCropFrameScale(0.75f) // 初始框=屏幕短边×0.75(范围 0.05~1)
.start()
aspect | resizable | ratioLocked | 初始框 | 拖拽行为 |
|---|---|---|---|---|
| >0(如 1:1) | false(默认) | — | 短边×frameScale 居中 | 不能改框,只能平移/双指缩放图片 |
| >0 | true | true(默认) | 同上 | 8 个把手缩放,比例锁定 |
| >0 | true | false | 同上 | 8 个把手自由缩放(宽高独立,可变形) |
| 0(自由裁剪) | false | — | 同上 | 不能改框,只能平移/双指缩放图片 |
| 0(自由裁剪) | true | — | 同上 | 8 个把手自由缩放 |
-
frameScale默认 0.75(屏幕短边 × 0.75)、范围 0.05~1;所有模式初始框都居中 -
resizable=false时关闭"停手 2 秒自动放大框",框不会自己动 -
以上参数只作用于头像裁剪页,编辑弹窗里的裁剪(自由裁剪)完全不受影响
生命周期与结果### 生命周期与结果
| 环节 | 说明 |
|---|---|
| 入口 | setAvatarCropMode(true) 后,点图 → FilePickerCropActivity(固定比例裁剪框) |
| 裁剪页 UI | 取消 / 旋转 / 镜像 / 还原 / 确认裁剪;比例固定,不能拖成其它比例 |
| 确认裁剪 | 生成成品图 → 发布到系统相册 Pictures/filepicker/ → 登记媒体库 |
| 返回结果 | MediaEntity.path / uri = 裁剪后的成品地址;editedPath 仅会话内使用 |
| 取消 | 关闭裁剪页,不产生任何文件 |
注意
-
头像模式与「预览页编辑」(
setEditInPreviewEnable)不冲突:多选时仍可编辑;
但头像模式固定单选,实际只会处理一张。 -
想保留"先勾选、再确认"的流程但又要裁剪,请用编辑弹窗里的裁剪(
setEditInPreviewEnable(true)),
不要再设置setAvatarCropAspectRatio(二者是不同入口)。
3.3 直接打开相机(完全不经过图片列表)
外部 App 点一下按钮 → 直接相机 → 拍完确定直接编辑/返回。
全程不出现图片列表(不会"闪一下主页"),也不需要媒体库读取权限。
FilePicker.with(this) // 必须是 FragmentActivity / Fragment
.setSelectType(FilePickerSelectType.ofImage()) // 视频用 ofVideo()
.setOpenCameraDirect(true) // ← 直接相机(无列表)
.setEditOnClickEnable(true) // 可选:拍完直接进编辑弹窗
// .setAvatarCropMode(true) // 或:拍完直接进头像裁剪
.setOnSelectCallback { _, list ->
val path = list.firstOrNull()?.path // 图片:编辑/裁剪后的成品;视频:视频路径
}
.start()
| 操作 | 行为 |
|---|---|
| 进入流程 | 直接拉起系统相机,不启动选择器、不查媒体库 |
| 相机取消 / 返回 | 回调 onCancel(),回到调用方界面,不产生文件 |
| 拍完确定(图片) | setEditOnClickEnable(true) → 直接进编辑弹窗;setAvatarCropMode(true) → 进头像裁剪;都没开 → 直接回调原图 |
| 编辑/裁剪点取消 | 整个流程取消,回调 onCancel()(不会回到列表) |
| 拍完确定(视频) | 视频无编辑,直接回调视频路径 |
| 完成后 | 编辑/裁剪成品发布到 Pictures/filepicker/,回调成品路径 |
实现说明(重要):
-
内部是一个无界面 Fragment(
FilePickerCaptureFragment)挂在调用方 Activity 上:
申请相机权限 → 拉系统相机 → 拍照后按配置进编辑/裁剪或直接回调 → 移除自己;
不新增 Activity、不出现列表 UI。 -
该模式走回调式 API(
FilePicker.with(activity/fragment)+setOnSelectCallback);
不支持startActivityForResult拿结果。 -
相机权限:宿主 Manifest 需声明
CAMERA(库不声明);宿主声明了未授权时库会先申请。 -
仅对
ofImage()/ofVideo()生效:ofAll()、音频、文档等类型会忽略该开关(打 warn 日志,
走普通选择流程),避免出现"选项类型对不上却直接弹相机"的怪行为;
四、API 文档
FilePicker
| 方法名 | 描述 |
|---|---|
with(activity) | 使用 FragmentActivity 初始化 |
with(fragment) | 使用 Fragment 初始化 |
convertToPathList(list) | 将 MediaEntity 列表转换为路径列表 |
convertToEntityList(list) | 将路径列表转换为 MediaEntity 列表 |
7.0.0 起类型入口方法统一收敛到
FilePickerSelectType(语义更贴合)。
FilePicker.ofImage()等老方法已标注@Deprecated,仍可正常使用(内部转发),
IDE 会提示迁移,建议尽快替换为FilePickerSelectType.ofXxx()。完整对照见
已废弃 API。
已废弃 API(@Deprecated)
以下方法自 7.0.0 起标注 @Deprecated(源码级兼容,调用不报错、行为不变,内部直接转发到新入口)。
新代码请一律使用右列写法:
| 废弃(不要再用) | 最新写法 |
|---|---|
FilePicker.ofAll() | FilePickerSelectType.ofAll() |
FilePicker.ofAllWithGif() | FilePickerSelectType.ofAllWithGif() |
FilePicker.ofImage() | FilePickerSelectType.ofImage() |
FilePicker.ofVideo() | FilePickerSelectType.ofVideo() |
FilePicker.ofGif() | FilePickerSelectType.ofGif() |
FilePicker.ofAudio() | FilePickerSelectType.ofAudio() |
FilePicker.ofDocument() | FilePickerSelectType.ofDocument() |
FilePicker.ofPdf() | FilePickerSelectType.ofPdf() |
FilePicker.ofDoc() | FilePickerSelectType.ofDoc() |
FilePicker.ofPpt() | FilePickerSelectType.ofPpt() |
FilePicker.ofExcel() | FilePickerSelectType.ofExcel() |
FilePicker.ofTxt() | FilePickerSelectType.ofTxt() |
FilePicker.ofApk() | FilePickerSelectType.ofApk() |
FilePicker.ofZipAll() | FilePickerSelectType.ofZipAll() |
FilePicker.ofZip() | FilePickerSelectType.ofZip() |
FilePicker.ofRar() | FilePickerSelectType.ofRar() |
FilePicker.of7Z() | FilePickerSelectType.of7Z() |
6.x 已删除的
ofTar()/ofGz()/ofBz2()/ofIso()/ofBr()/ofLz4()/ofZstd()/ofXz()
不在废弃之列(已移除),替代写法见下方 7.0.0 旧 API 迁移对照表。
FilePickerSelectType 类型入口
| 方法名 | 描述 |
|---|---|
ofAll() | 选择图片和视频 |
ofAllWithGif() | 选择图片、视频和GIF |
ofImage() | 只选择图片 |
ofVideo() | 只选择视频 |
ofGif() | 只选择GIF |
ofAudio() | 只选择音频 |
ofDocument() | 选择所有文档类型 |
ofPdf() | 只选择PDF |
ofDoc() | 只选择DOC和DOCX |
ofPpt() | 只选择PPT和PPTX |
ofExcel() | 只选择XLS和XLSX |
ofTxt() | 只选择TXT |
ofMarkdown() | 只选择 Markdown(.md / .markdown) |
ofXmind() | 只选择 XMind 思维导图(.xmind) |
ofFreemind() | 只选择 FreeMind 思维导图(.mm) |
ofApk() | 只选择APK |
ofZipAll() | 选择所有压缩包类型 |
ofZip() | 只选择ZIP |
ofRar() | 只选择RAR |
of7Z() | 只选择7Z |
ofExtensions(...) | 按任意后缀组合自定义过滤(见下节) |
类型入口怎么选
有专属类型入口的后缀,优先用类型入口;没有的才用 ofExtensions()。
两者能力上都能查到文件,但语义与体验有差别:
| 场景 | 推荐入口 | 原因 |
|---|---|---|
| 选图片/视频 | ofImage() / ofVideo() / ofAll() | 相册网格模式、大图预览、原图选项齐全 |
| 选音频/文档/APK | ofAudio() / ofDocument() / ofApk() | 专属查询条件与图标 |
| 选 Markdown/思维导图 | ofMarkdown() / ofXmind() / ofFreemind() | 按后缀查询,专属图标(见下) |
| 选压缩包 | ofZipAll() / ofZip() / ofRar() / of7Z() | mime + 后缀双轨查询,图标专属 |
| 选其他任意后缀 | ofExtensions("xz", "bak", ...) | 无对应类型时的通用方案 |
ofExtensions() 与类型入口的差异(按后缀捞文件的语义带来的):
-
UI 呈现为文件列表模式(按时间排序 + 文件夹分组),不是相册网格模式
-
无大图预览手势(
isCanPreview()不放行ext:类型) -
查询按文件名后缀匹配,会包含隐藏目录(
.开头路径)下的文件——若需排除,
设置setMaxFileSize()(走filePathNotContains("/.")过滤)或自行过滤结果
Markdown / 思维导图(按后缀识别)
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofMarkdown()) // .md / .markdown
// .setSelectType(FilePickerSelectType.ofXmind()) // .xmind
// .setSelectType(FilePickerSelectType.ofFreemind()) // .mm
.start()
这三个类型只按文件名后缀查询与识别,不走 mime 轨,因为 MediaStore 给不出可靠的 mime:
| 后缀 | MediaStore 常见 mime | 后果(若按 mime 判) |
|---|---|---|
.xmind | application/zip(xmind 本质是 zip 容器) | 查询会捞出所有 zip;图标显示成 zip |
.md | text/plain 或 application/octet-stream | 图标显示成 txt |
.mm | application/octet-stream | 无专属图标 |
因此它们不属于压缩包:不参与 ZIP_ALL、isArchive() 的任何推导,与.xmind 是 zip 容器这件事无关。
图标映射里这三个判断排在 isTxt() / isZip() 之前,后缀命中即显示专属图标。
归属上它们是文档类型,但
ofDocument()的查询条件不含这三种(ofDocument()行为保持不变),
需要单独用ofMarkdown()/ofXmind()/ofFreemind()。
后缀表统一登记在 FilePickerSelectType.DOC_EXTS,新增别名(如 mdown / mkd)只需加一行,查询与图标自动跟上。
自定义后缀过滤
tar/gz/bz2/iso/br/lz4/zstd/xz 等其他压缩格式不再单独提供 API,统一用
FilePickerSelectType.ofExtensions() 按任意后缀组合:
// 按任意后缀过滤,直接作为 selectType 传入
FilePicker.with(this)
.setSelectType(FilePickerSelectType.ofExtensions("xz", "tar", "bak"))
.start()
-
后缀自动去掉前导点、转小写、去重,并过滤 SQL 通配符(
%_) -
任意后缀都能查(真机已验证:编造后缀
.qqqxx7、大写.ABCxyz、双重点.tar.gz均命中),
前提是文件位于 MediaStore 索引的公共存储;应用私有目录、.nomedia目录内的文件查不到 -
图标识别不受影响:内置的 tar/gz/bz2/iso/br/lz4/zstd/xz 类型常量与图标映射仍然生效,
老代码直接传FilePickerSelectType.TAR等字符串常量依旧可用 -
查询、识别由内部「压缩包登记处」统一驱动:
ZIP_ALL由登记处派生,
单个类型(如ZIP)只取登记处中自己那一行,互不影响
7.0.0 旧 API 迁移对照表:
| 6.x(已删除) | 7.0.0 等价写法 |
|---|---|
ofTar() | FilePickerSelectType.ofExtensions("tar") |
ofGz() | FilePickerSelectType.ofExtensions("gz", "tgz") |
ofBz2() | FilePickerSelectType.ofExtensions("bz2") |
ofIso() | FilePickerSelectType.ofExtensions("iso") |
ofBr() | FilePickerSelectType.ofExtensions("br") |
ofLz4() | FilePickerSelectType.ofExtensions("lz4") |
ofZstd() | FilePickerSelectType.ofExtensions("zstd") |
ofXz() | FilePickerSelectType.ofExtensions("xz") |
ofTar() + ofIso() 组合 | FilePickerSelectType.ofExtensions("tar", "iso") |
也可以不做任何改动:把 selectType 直接传
FilePickerSelectType.TAR等字符串常量,查询、过滤、图标展示行为与旧版一致。
Builder
| 方法名 | 描述 |
|---|---|
setSelectType(type) | 设置选择的文件类型 |
setMaxSelectNumber(num) | 设置最大选择数量(0/Int.MAX_VALUE = 不限)。只在不用 setSelectRules 时生效;规则模式下合计上限由规则自动叠加,本方法被忽略 |
setSelectRules(vararg rules) | 按类型分别限量,见「按类型限量」 |
setExclusive(exclusive) | 互斥:图片与视频只能选其中一类。需先配 setSelectRules,否则不生效 |
setGifCountsAsImage(counts) | GIF 是否占用图片额度,默认 true。需先配 setSelectRules,否则不生效 |
setMaxFileSize(size) | 设置最大文件大小(字节) |
setMinFileSize(size) | 设置最小文件大小(字节) |
setSlideChooseEnable(enable) | 是否启用滑动选择,默认 true |
setSingleClickEnable(enable) | 是否启用单选立即返回,默认 false。仅在 maxSelectNumber 为1时生效 |
setShowCameraEntry(enable) | 是否显示网格第一格的拍照/录像入口,默认 false。仅对单一的图片或视频类型生效,详见下文 |
setSelectedList(list) | 设置已选中的 MediaEntity 列表 |
setSelectedPathList(list) | 设置已选中的文件路径列表 |
setUiConfig(config) | 设置自定义UI配置 |
setOnSelectCallback(callback) | 设置选择结果回调 |
setAvatarCropMode(enable) | 头像裁剪总开关(默认 false)。开启后裁剪相关参数才生效,见「3.2 头像裁剪」 |
setAvatarCropAspectRatio(a) | 头像裁剪比例:0f = 自由裁剪;>0 固定比例(1f=1:1);不设置默认 1:1;需先开 setAvatarCropMode(true) |
setAvatarCropResizable(b) | 裁剪框能否拖动改大小;默认 false(只能平移/缩放图片) |
setAvatarCropRatioLocked(b) | 可拖拽时是否锁定比例;默认 true(锁比例缩放),false = 可随意拉宽拉高(变形) |
setAvatarCropFrameScale(s) | 初始裁剪框尺寸占屏幕短边比例;默认 0.75,范围 0.05~1 |
setAvatarCropOutputMaxSize(s) | 头像裁剪导出最长边,默认 2048 |
setAvatarCropQuality(q) | 头像裁剪导出质量 60~100,默认 90 |
setAvatarCropResetText(t) | 裁剪页「还原」文案(等价 uiConfig.cropResetText) |
setEditInPreviewEnable(enable) | 预览页编辑开关(默认 false);开启后单图/多选预览出现「编辑」 |
setEditOnClickEnable(enable) | 单图点击直接编辑开关(默认 false);点图直接弹编辑弹窗,完成即返回、取消继续选 |
setOpenCameraDirect(enable) | 直接相机开关(默认 false);完全不经过图片列表,直接相机 → 编辑/裁剪 → 回调;仅 ofImage() / ofVideo() 生效 |
setEditCacheDir(path) | 编辑临时缓存目录(默认 Android/data/<包名>/cache/filepicker/) |
start() | 启动选择器 |
头像裁剪的旧方法
setCropAspectRatio/setCropOutputMaxSize/setCropQuality/
setCropResetText在 8.0.0 起标注@Deprecated,内部转发到新方法,仍可编译使用。
图片编辑 / 头像裁剪 API(8.x)
| 分类 | API / 字段 | 说明 |
|---|---|---|
| 编辑开关 | setEditInPreviewEnable(true) | 预览页出现「编辑」(单图预览 + 多选预览) |
| 编辑缓存 | FilePicker.editCacheDir(ctx) / editCacheSize(ctx) / clearEditCache(ctx) | 缓存目录 / 大小 / 手动清理(返回调用方时库已自动异步清理) |
| 头像裁剪 | setAvatarCropMode(true) + setAvatarCropAspectRatio(1f) | 强制单选 + 点图直接进裁剪页 |
| 结果字段 | MediaEntity.path / uri | 最终地址:未编辑=原图;编辑/头像裁剪=Pictures/filepicker/ 成品 |
| 结果字段 | MediaEntity.editedPath | 仅会话内预览/角标使用,返回结果时清空,宿主不要读 |
| 成品发布 | 自动 | 编辑/头像裁剪成品发布到 Pictures/filepicker/ 并登记媒体库(10+ 走 MediaStore;9 及以下写公共目录 + 扫描) |
UI 自定义配置 (FilePickerUIConfig)
通过 FilePicker.with(this).setUiConfig(uiConfig) 进行设置。
val uiConfig = FilePickerUIConfig().apply {
isHideSelectTab = false
confirmBtnText = "完成"
allAlbumName = "所有文件"
// ... 更多配置
}
| 属性 | 类型 | 描述 | 默认值 |
|---|---|---|---|
isHideSelectTab | Boolean | 是否隐藏顶部分类Tab | false |
confirmBtnText | String | 确定按钮的文本 | "确定" |
isPreviewPageIndexMode | Boolean | 预览页面是否显示页码 | true |
allAlbumName | String | “全部”文件夹的显示名称 | "全部" |
previewText | String | 预览页面的标题 | "预览" |
isShowBottomPreviewText | Boolean | 是否显示底部预览按钮 | true |
previewSelectText | String | 预览页面底部“选择”按钮文本 | "选择" |
originalText | String | “原图”选项的文本 | "原图" |
isShowOriginal | Boolean | 是否显示“原图”选项 | true |
isOriginalChecked | Boolean | “原图”选项是否默认选中 | false |
isShowHomePageSelectedBottomListWidget | Boolean | 是否显示主页底部已选列表 | true |
isShowSelectedListDeleteIcon | Boolean | 是否显示已选列表项的删除按钮 | false |
selectedListDeleteIconResId | Int | 已选列表项删除按钮的图标资源ID | 0 |
selectedListDeleteIconBackgroundColor | Int | 已选列表项删除按钮的背景色 | Color.TRANSPARENT |
atLeastSelectOneToastContent | String | 未选择任何文件时的提示 | "至少选择一个" |
selectMaxNumberOverToastContent | String | 超出最大选择数量时的提示 | "已达到最大选择数量" |
selectTypeMaxToastContent | String | 命中分类型上限时的提示(%1$s=类型名,%2$d=上限) | "%1$s最多选择%2$d个" |
selectExclusiveConflictToastContent | String | 互斥下点了另一类时的提示(%1$s=当前只能选的类型) | "当前只能选择%1$s" |
selectRuleNotSatisfiedToastContent | String | 必选未满足时的提示(%1$s=类型名,%2$d=要求数量) | "%1$s必须选%2$d个" |
cameraEntryIconResId | Int | 拍照入口的图标(0 = 库内默认) | 0 |
cameraEntryVideoIconResId | Int | 录像入口的图标(0 = 库内默认) | 0 |
cameraEntryPhotoText | String | 「拍照」半边下面的文字 | "拍照" |
cameraEntryVideoText | String | 「录像」半边下面的文字 | "录像" |
cameraEntryFailedToastContent | String | 相机入口启动失败时的提示 | "无法启动相机" |
cameraEntrySizeLimitToastContent | String | 拍摄产物不符合大小限制时的提示 | "拍摄的文件不符合大小限制,未加入列表" |
folderNickNameMap | HashMap<String, String> | 文件夹名称映射,用于自定义显示名称 | emptyHashMap() |
编辑页 editCancelText | String | 编辑页顶栏「取消」 | "取消" |
editDoneText | String | 编辑页顶栏「完成」 | "完成" |
editUndoLabel / editRedoLabel | String | 撤销/重做无障碍描述 | "撤销" / "重做" |
editToolBrushLabel / editToolTextLabel / editToolCropLabel / editToolMosaicLabel | String | 工具名(无障碍) | 画笔/文字/裁剪/马赛克 |
editBrushSizeLabel | String | 画笔粗细滑条描述 | "画笔粗细" |
editTextFontModeLabel / editTextBgModeLabel | String | 文字输入底部 T 按钮两种模式描述 | 见源码默认值 |
editColorDotLabelFormat | String | 颜色点描述格式(%1$d=颜色值) | "颜色%1$d" |
mosaicPixelLabel / mosaicBlurLabel | String | 马赛克两种效果描述 | "像素马赛克" / "雾化" |
editEraserLabel | String | 橡皮按钮描述 | "橡皮" |
editLoadImageFailedToastContent | String | 图片加载失败提示 | "图片加载失败" |
editSaveFailedToastContent | String | 保存失败提示 | "保存失败,请重试" |
裁剪页 cropRotateLabel / cropMirrorLabel | String | 旋转 / 镜像按钮描述 | "旋转" / "镜像" |
cropResetText | String | 「还原」文案 | "还原" |
cropCancelLabel / cropConfirmLabel | String | 取消裁剪 / 确认裁剪按钮描述 | "取消裁剪" / "确认裁剪" |
五、常见问题与温馨提示
常见问题
| 问题 | 处理 |
|---|---|
| 编辑了图片,但回调里拿不到"编辑产物"? | 返回结果里编辑过的条目 path 已经是编辑后成品地址(Pictures/filepicker/xxx.jpg),editedPath 会清空。直接用 entity.path 即可 |
头像裁剪设了 setCropAspectRatio 没反应? | 8.0.0 起必须开总开关:setAvatarCropMode(true);关闭时裁剪参数不生效(warn 日志) |
| 编辑/裁剪页文案是中文,能做多语言吗? | 能。全部文案在 FilePickerUIConfig(editCancelText…cropResetText…),传自己 getString(...) 即可 |
| 头像模式下拍照后没进裁剪页? | 8.0.0 起已修:拍完点确定会先进 1:1 裁剪页;若仍复现,检查是否开了 setAvatarCropMode(true) |
| 编辑产物在系统相册找不到? | 位置是 内部存储/Pictures/filepicker/(媒体库扫描有延迟,部分机型几秒) |
温馨提示
如果 UI 效果与你的需求差距较大,强烈建议下载源码自己改(fork 后按需调整),
比提"能不能再改一点"更省时间;布局/图标/文案都集中在 filepicker/src/main/res 里。
结束语
FilePicker 旨在提供简洁、灵活、可定制的文件选择功能,广泛适用于相册、文件管理、视频选择等场景。
如需深入定制或遇到问题,欢迎补充需求,我可以帮您生成对应的开发指导。
特别鸣谢
本项目在开发过程中参考和使用了以下优秀的开源项目,特此致谢:
-
xwidget - 提供了超级方便的基础组件。
-
BRV —— 便捷的 RecyclerView 适配器库
-
BasePopup —— 强大的弹窗库
-
Glide —— 高效的图片加载库
-
androidx.media3 —— 官方视频播放组件
感谢你们的无私奉献,让开发变得更加高效和有趣!
版本记录
8.2.0
头像裁剪页能力扩展:自由裁剪 / 可拖拽裁剪框 / 比例锁定开关 / 初始框大小可配;demo 重构为按场景分 Tab。
无破坏性变更:不传新参数时,头像裁剪行为与原版一致(1:1、框不可拖、初始框居中)。
新增(头像裁剪页)
-
setAvatarCropAspectRatio(aspect)支持自由裁剪0f= 自由裁剪;> 0= 固定比例(1f1:1、0.5f1:2、0.75f3:4、1.777f16:9…);不设置 = 默认 1:1
-
setAvatarCropResizable(true):裁剪框可拖拽改大小- 开关打开后显示 8 个把手,可拖动改变裁剪框大小;默认
false(框固定,只能平移/双指缩放图片)
- 开关打开后显示 8 个把手,可拖动改变裁剪框大小;默认
-
setAvatarCropRatioLocked(true):拖拽时是否锁定比例- 默认
true(锁比例缩放);传false可随意拉宽拉高(变形)
- 默认
-
setAvatarCropFrameScale(0.75f):初始裁剪框大小- 占屏幕短边比例,默认 0.75,范围 0.05 ~ 1;始终居中,超出安全区自动等比缩小
-
以上参数只作用于头像裁剪页,编辑弹窗里的自由裁剪完全不受影响
优化
-
裁剪框「停手自动放大」时间 2s → 1.5s(编辑弹窗裁剪 & 头像裁剪可拖拽时共用)
-
裁剪框不可拖拽时关闭自动放大(框不会自己动)
-
固定比例裁剪框尺寸从写死 86% 改为可配置(默认 75%)
demo 重构
-
首页改为 ViewPager2 + TabLayout + 8 个场景 Fragment,每个场景独立选项 + 开始 + 结果展示,互不干涉:
普通选择 / 规则 / 文件 / 头像裁剪 / 点击编辑 / 预览编辑 / 拍照直出 / 录像直出 -
文件类型改为 4 列网格(库支持的全部类型),自定义后缀提供 20 个常用预设可点选填入
-
头像裁剪、拍照直出支持自定义比例(单选「自定义」才显示输入框,输入数字自动补冒号)
-
规则页输入框加标题、最大值在上 / 最小值在下;最小值 > 最大值时文字标红并拦截开始
-
README 新增「功能展示」章节(19 张真机截图,小图展示、可点开大图)