100万以内最好的文件图片选择器,跟微信选图一样。支持文件选择(任何后缀)支持定义规则选择图片或者视频

105 阅读28分钟

图片选择器

最新版本 8.2.0

Github 地址: filepicker
  • 微信选择库样式风格,完全防微信,图片编辑功能对齐,头像剪裁,超越微信的更多场景。

  • 用了很多,都没有丝滑的选择效果的开源库,滑动选择丝滑。闲来没事,随手写一个吧。

  • 图库选择,文件选择

  • 仿华为相册滑动选择手势逻辑,

  • 支持多选,限制数量,不限制数量。

  • 选择条件可限定:图片 / 视频各自限量(如图片 9 张、视频 1 个),可以要求必须选够,
    也能让图片和视频只能选其中一类(互斥)。见「按类型限量」一节。

  • 使用场景,多用于 视频剪辑选择库,相册管理选择库,朋友圈选图或者视频。

  • 使用最新版的 filepicker 库,必须使用最新版的xwidget库。都是 5.8.1 以上确保。

好不好用,直接安装。

  • 扫码:filepicker转存失败,建议直接上传图片文件

demo 已经按「使用场景」重构,每个场景各自选项 + 「开始」+ 结果展示,互不干涉:
普通选择 / 规则 / 文件 / 头像裁剪 / 点击编辑 / 预览编辑 / 拍照直出 / 录像直出。

功能总览

按重要度排序:先"选图",再"编辑",再"头像裁剪",最后是外围能力。

优先级能力说明入口
1图片 / 视频 / 文件选择图库网格、滑动选择、单选/多选、数量与大小限制基本用法
2图片编辑画笔(涂鸦)、文字、裁剪、马赛克;会话级覆盖不改原图,完成后发布相册;支持「点击即编辑」3.1 图片编辑
3头像裁剪setAvatarCropMode(true);支持固定比例/自由裁剪,框可拖拽、可锁比例、初始大小可调3.2 头像裁剪
4预览单图预览(可编辑)、多选预览(可逐张编辑)、底部已选缩略图条基本用法
5分类型限量 / 互斥「图片 9 张 + 视频 1 个」「必须选够」「二选一」基本用法 §6
6相机入口 / 直接相机网格内拍照入口;setOpenCameraDirect 完全不经过列表(仅图片/视频)3.3 直接相机
7多类型文件音频、文档、PDF、APK、压缩包、自定义后缀基本用法 §3
8UI 配置 / 多语言文案、颜色、图标、编辑页完整 i18nFilePickerUIConfig
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()
aspectresizableratioLocked初始框拖拽行为
>0(如 1:1)false(默认)—短边×frameScale 居中不能改框,只能平移/双指缩放图片
>0truetrue(默认)同上8 个把手缩放,比例锁定
>0truefalse同上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()相册网格模式、大图预览、原图选项齐全
选音频/文档/APKofAudio() / 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 判)
.xmindapplication/zip(xmind 本质是 zip 容器)查询会捞出所有 zip;图标显示成 zip
.mdtext/plain 或 application/octet-stream图标显示成 txt
.mmapplication/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 = "所有文件"
    // ... 更多配置
}
属性类型描述默认值
isHideSelectTabBoolean是否隐藏顶部分类Tabfalse
confirmBtnTextString确定按钮的文本"确定"
isPreviewPageIndexModeBoolean预览页面是否显示页码true
allAlbumNameString“全部”文件夹的显示名称"全部"
previewTextString预览页面的标题"预览"
isShowBottomPreviewTextBoolean是否显示底部预览按钮true
previewSelectTextString预览页面底部“选择”按钮文本"选择"
originalTextString“原图”选项的文本"原图"
isShowOriginalBoolean是否显示“原图”选项true
isOriginalCheckedBoolean“原图”选项是否默认选中false
isShowHomePageSelectedBottomListWidgetBoolean是否显示主页底部已选列表true
isShowSelectedListDeleteIconBoolean是否显示已选列表项的删除按钮false
selectedListDeleteIconResIdInt已选列表项删除按钮的图标资源ID0
selectedListDeleteIconBackgroundColorInt已选列表项删除按钮的背景色Color.TRANSPARENT
atLeastSelectOneToastContentString未选择任何文件时的提示"至少选择一个"
selectMaxNumberOverToastContentString超出最大选择数量时的提示"已达到最大选择数量"
selectTypeMaxToastContentString命中分类型上限时的提示(%1$s=类型名,%2$d=上限)"%1$s最多选择%2$d个"
selectExclusiveConflictToastContentString互斥下点了另一类时的提示(%1$s=当前只能选的类型)"当前只能选择%1$s"
selectRuleNotSatisfiedToastContentString必选未满足时的提示(%1$s=类型名,%2$d=要求数量)"%1$s必须选%2$d个"
cameraEntryIconResIdInt拍照入口的图标(0 = 库内默认)0
cameraEntryVideoIconResIdInt录像入口的图标(0 = 库内默认)0
cameraEntryPhotoTextString「拍照」半边下面的文字"拍照"
cameraEntryVideoTextString「录像」半边下面的文字"录像"
cameraEntryFailedToastContentString相机入口启动失败时的提示"无法启动相机"
cameraEntrySizeLimitToastContentString拍摄产物不符合大小限制时的提示"拍摄的文件不符合大小限制,未加入列表"
folderNickNameMapHashMap<String, String>文件夹名称映射,用于自定义显示名称emptyHashMap()
编辑页 editCancelTextString编辑页顶栏「取消」"取消"
editDoneTextString编辑页顶栏「完成」"完成"
editUndoLabel / editRedoLabelString撤销/重做无障碍描述"撤销" / "重做"
editToolBrushLabel / editToolTextLabel / editToolCropLabel / editToolMosaicLabelString工具名(无障碍)画笔/文字/裁剪/马赛克
editBrushSizeLabelString画笔粗细滑条描述"画笔粗细"
editTextFontModeLabel / editTextBgModeLabelString文字输入底部 T 按钮两种模式描述见源码默认值
editColorDotLabelFormatString颜色点描述格式(%1$d=颜色值)"颜色%1$d"
mosaicPixelLabel / mosaicBlurLabelString马赛克两种效果描述"像素马赛克" / "雾化"
editEraserLabelString橡皮按钮描述"橡皮"
editLoadImageFailedToastContentString图片加载失败提示"图片加载失败"
editSaveFailedToastContentString保存失败提示"保存失败,请重试"
裁剪页 cropRotateLabel / cropMirrorLabelString旋转 / 镜像按钮描述"旋转" / "镜像"
cropResetTextString「还原」文案"还原"
cropCancelLabel / cropConfirmLabelString取消裁剪 / 确认裁剪按钮描述"取消裁剪" / "确认裁剪"


五、常见问题与温馨提示

常见问题

问题处理
编辑了图片,但回调里拿不到"编辑产物"?返回结果里编辑过的条目 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 = 固定比例(1f 1:1、0.5f 1:2、0.75f 3:4、1.777f 16:9…);不设置 = 默认 1:1
  • setAvatarCropResizable(true):裁剪框可拖拽改大小

    • 开关打开后显示 8 个把手,可拖动改变裁剪框大小;默认 false(框固定,只能平移/双指缩放图片)
  • 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 张真机截图,小图展示、可点开大图)