Thanks to visit codestin.com
Credit goes to github.com

Skip to content

pichsy/filepicker

Repository files navigation

图库选择器

最新版本

  • 用了很多,都没有丝滑的选择效果的开源库,滑动选择丝滑。闲来没事,随手写一个吧。
  • 图库选择,文件选择
  • 仿华为相册滑动选择手势逻辑,
  • 微信选择库样式风格
  • 支持多选,限制数量,不限制数量。
  • 使用场景,多用于 视频剪辑选择库,相册管理选择库。那去玩吧。

好不好用,直接安装。

依赖库,都是常用库,强烈建议 项目使用。

  • 下面的这个三方库,本maven仓库中的aar都过滤掉了。建议自己从下面引用,防止库冲突。

最新版本

  1. **filepicker **

  2. **xwidget **

  3. **BRV **

  4. **BasePopup **

  5. androidx.media3 这里建议使用1.7.1 稳定版

  6. glide

dependencies {
    // 基础组件库 (必须)
    implementation("com.gitee.pichs:filepicker:4.3.0")

    // 基础组件库 (必须)
    implementation("com.gitee.pichs:xwidget:5.5.0")

    // 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")
}

动图效果

img2.gif

FilePicker 文件选择器 - 使用文档

FilePicker 是一个支持图片、视频、文件选择的轻量级文件选择器,支持自定义配置、选中列表管理、回调返回选中数据。


快速入口

  • 支持 Activity 和 Fragment 调用
  • 支持多选、最大数量控制、文件大小限制
  • 支持返回原图选项
  • 支持 UI 文案与界面定制

基本用法

1. Activity 中启动

FilePicker.with(this) // this: FragmentActivity
    .setSelectType(FilePicker.ofImage()) // 选择类型,图片、视频、全部
    .setMaxSelectNumber(9) // 最大选择数量
    .setOnSelectCallback { isUseOriginal, list ->
        // 选择完成回调
        println("是否使用原图: $isUseOriginal")
        list.forEach {
            println("文件路径: ${it.path}")
        }
    }
    .start()

2. Fragment 中启动

FilePicker.with(this) // this: Fragment
    .setSelectType(FilePicker.ofAll())
    .setMaxSelectNumber(5)
    .setMaxFileSize(50 * 1024 * 1024) // 50MB
    .setMinFileSize(10 * 1024) // 10KB
    .setSelectedList(existingList) // 已选列表(MediaEntity对象)
    .setOnSelectCallback { isUseOriginal, list ->
        println("是否使用原图: $isUseOriginal")
    }
    .start()

选择类型

注意:选择图片、视频、音频时,申请读写权限即可。选择其他文件类型(如文档、APK、压缩包等)必须申请文件管理权限,否则无法获取数据。

方法 说明
FilePicker.ofImage() 只选择图片
FilePicker.ofVideo() 只选择视频
FilePicker.ofAudio() 只选择音频
FilePicker.ofAll() 图片、视频均可选择
FilePicker.ofAllWithGif() 图片、视频、Gif均可选择
FilePicker.ofGif() 只选择Gif
FilePicker.ofDocument() 选择所有文档类型
FilePicker.ofPdf() 只选择PDF文件
FilePicker.ofDoc() 只选择Doc/Docx文件
FilePicker.ofPpt() 只选择Ppt/Pptx文件
FilePicker.ofExcel() 只选择Xls/Xlsx文件
FilePicker.ofTxt() 只选择Txt文件
FilePicker.ofApk() 只选择Apk文件
FilePicker.ofZipAll() 选择所有压缩包类型
FilePicker.ofZip() 只选择Zip文件
FilePicker.ofRar() 只选择Rar文件
FilePicker.of7Z() 只选择7z文件
FilePicker.ofTar() 只选择Tar文件
FilePicker.ofGz() 只选择Gz文件
FilePicker.ofBz2() 只选择Bz2文件
FilePicker.ofIso() 只选择Iso文件

常用配置参数

配置方法 说明 默认值
setSelectType(type: String) 选择类型:图片、视频、全部等 全部
setMaxSelectNumber(number: Int) 最大可选数量,0为不限制 0
setMaxFileSize(size: Long) 文件最大大小(字节) 不限制
setMinFileSize(size: Long) 文件最小大小(字节) 1
setSelectedList(list: MutableList<MediaEntity>) 已选择的文件列表,初始化用 空列表
setSelectedPathList(list: List<String>) 已选择的文件路径列表,自动转换为 MediaEntity 空列表
setSingleClickEnable(enable: Boolean) 单击立即返回,仅在 maxSelectNumber=1 时有效 false
setSlideChooseEnable(enable: Boolean) 是否启用滑动选择 true
setUiConfig(config: FilePickerUIConfig) 界面文案与UI配置 默认配置
setOnSelectCallback(callback: OnSelectCallback) 选择完成回调 必填

回调说明

fun interface OnSelectCallback {
    fun onCallback(isUseOriginal: Boolean, list: MutableList<MediaEntity>)
}
  • isUseOriginal: 是否选择了“原图”
  • list: 最终选择的文件列表

工具方法

方法 说明
FilePicker.convertToPathList(list: MutableList<MediaEntity>) 将选中的 MediaEntity 转换为路径列表
FilePicker.convertToEntityList(list: List<String>) 路径列表转换为 MediaEntity 列表

UI 文案自定义

通过 FilePickerUIConfig 配置界面显示:

val config = FilePickerUIConfig(
    confirmBtnText = "完成",
    previewText = "预览文件",
    isShowOriginal = true,
    originalText = "原图查看",
    atLeastSelectOneToastContent = "请至少选择一项"
)

FilePicker.with(this)
    .setUiConfig(config)
    .setMaxSelectNumber(3)
    .setOnSelectCallback { isUseOriginal, list -> }
    .start()

注意事项

  • 必须在 FragmentActivityFragment 中调用
  • setOnSelectCallback 为必填,否则无法接收结果
  • 已选列表支持预填充,避免重复选择
  • 支持多次调用,内部通过单例模式管理

典型示例

    FilePicker.with(this)
    .setSelectType(FilePicker.ofImage())
    .setMaxSelectNumber(5)
    .setMinFileSize(1024) // 最小1KB
    .setMaxFileSize(10 * 1024 * 1024) // 最大10MB
    .setOnSelectCallback { isUseOriginal, list ->
        val paths = FilePicker.convertToPathList(list)
        println("选中文件路径: $paths")
    }
    .start()

三、UIConfig解释

字段名 类型 默认值 说明
isHideSelectTab Boolean false ofAll() 时是否隐藏顶部的 "图片/视频" 切换Tab
confirmBtnText String "确定" 确认按钮文本,默认 "确定"
isPreviewPageIndexMode Boolean true 预览页面是否显示选中索引。true 显示序号,false 显示对号 ✅
allAlbumName String "全部" 文件夹选择弹窗中,"全部"相册的名称
previewText String "预览" 预览页面标题文本
isShowBottomPreviewText Boolean true 是否显示底部 "预览" 按钮
previewSelectText String "选择" 预览页面的选择按钮文本
originalText String "原图" 原图选项的文本内容
isShowOriginal Boolean true 是否显示原图选项
isOriginalChecked Boolean false 原图选项是否默认勾选
isShowSelectedListDeleteIcon Boolean false 是否展示选中列表中的删除按钮
selectedListDeleteIconBackgroundColor Int "#FA4B3A" 选中列表中删除按钮的背景颜色
atLeastSelectOneToastContent String "至少选择一个" 最少选择一个文件时的提示文本
selectMaxNumberOverToastContent String "已达到最大选择数量" 达到最大选择数量限制时的提示文本


## !!!温馨提示: 如果UI效果与你的需求差距较大,强烈建议下载源码,自己修改一下。fork代码,自己改。!!!

结束语

FilePicker 旨在提供简洁、灵活、可定制的文件选择功能,广泛适用于相册、文件管理、视频选择等场景。

如需深入定制或遇到问题,欢迎补充需求,我可以帮您生成对应的开发指导。

特别鸣谢

本项目在开发过程中参考和使用了以下优秀的开源项目,特此致谢:

  • xwidget - 提供了超级方便的基础组件。
  • BRV —— 便捷的 RecyclerView 适配器库
  • BasePopup —— 强大的弹窗库
  • Glide —— 高效的图片加载库
  • androidx.media3 —— 官方视频播放组件

感谢你们的无私奉献,让开发变得更加高效和有趣!

升级日志

4.3.0 (预计)

  • 新增:支持更多文件类型选择,如文档(audio, pdf, doc, ppt, excel, txt)、APK、各类压缩包等。
  • 新增setSingleClickEnable(boolean) API,支持单选模式下单击立即返回。
  • 新增setSlideChooseEnable(boolean) API,可禁用滑动选择手势。
  • 新增FilePickerUIConfig 中增加 isHideSelectTaballAlbumNameisShowBottomPreviewText 等UI配置项。

4.2.0

  • 修复maxFileSize默认值:目前改为Long.MAX_VALUE .

4.1.0

  • 适配手机底部导航栏,为屏幕内虚拟三键的情况。