更新记录

1.1.8（2026-05-31）

-优化

1.1.7（2026-05-30）

-鸿蒙优化

1.1.6（2026-05-29）

-IOS端进行调试优化

平台兼容性

uni-app(4.18)

uni-app x(4.18)

其他

ly028-filepicker

uni-app / uni-app x UTS 原生文件选择插件：目录层级浏览、扩展名分类、类型分组；单选/多选、搜索、排序、已选清单、图片预览；支持 Android 11/12/13+、iOS、HarmonyOS。

提供原生文件选择能力，支持主题、文案、分组与排序等常用配置，便于接入与国际化。

点击下载体验

扫码体验

平台支持

• 环境：uni-app 建议 HBuilderX 3.7.2+；uni-app x 建议 HBuilderX 4.0+（鸿蒙建议 4.31+）
• 调试：原生 UTS 插件必须进入 自定义调试基座 或 正式云打包包体 才能运行；普通标准基座不包含本插件原生代码

快速开始

1. 安装

在 DCloud 插件市场 搜索 ly028-filepicker，导入到项目 uni_modules 后：

1. 在插件详情页 试用/购买 并绑定当前 AppID 工程
2. manifest.json 配置 AppID
3. 制作自定义调试基座 → 运行到自定义基座（真机）

2. uni-app 调用（Vue2/Vue3）

import LyFilePicker from '@/uni_modules/ly028-filepicker/js_sdk/index.js'

// 类型分组多选（默认，效果接近「文件分类」场景）
const ret = await LyFilePicker.pickFiles({
  browseMode: LyFilePicker.BROWSE_GROUP,
  maxCount: 10,
  extensions: 'png,jpg,pdf,docx,zip',
  sortType: 3
})

if (ret.ok && ret.data) {
  console.log('已选', ret.data)
}

3. uni-app x / UTS 直接调用

import { pickFiles } from '@/uni_modules/ly028-filepicker'

pickFiles({
  browseMode: 2,
  maxCount: 9,
  extensions: 'png,jpg,jpeg,pdf,docx,zip'
}, (ret) => {
  if (ret.ok) {
    console.log(ret.data)
  }
})

4. 浏览模式 browseMode

API

pickFiles(options) → Promise<LyPickResult>

sortType

返回 data[] 单项

UTS 直接调用

import { pickFiles } from '@/uni_modules/ly028-filepicker'

pickFiles({ browseMode: 0, maxCount: 5 }, (ret) => {
  console.log(ret)
})

国际化示例

仅 Android 自定义页面生效；iOS / HarmonyOS 使用系统 UI，自动跟随设备语言。

LyFilePicker.pickFiles({
  strings: {
    title: 'Select files',
    btnConfirm: 'Done',
    btnCancel: 'Cancel',
    selectedCount: 'Selected %1$s / %2$s',
    searchHint: 'Search file name'
  }
})

manifest 权限建议

Android（按 targetSdk 自动适配，建议在 manifest 勾选）：

• READ_EXTERNAL_STORAGE（Android 12 及以下）
• READ_MEDIA_IMAGES / READ_MEDIA_VIDEO / READ_MEDIA_AUDIO（Android 13+）

iOS：无需额外声明，用户通过系统选择器授权。

HarmonyOS：读取用户所选文件，按 module.json5 申请。

常见问题

Q：没有弹出选择页？
A：是否使用 自定义调试基座；是否在真机 App 环境（非 H5）。

Q：Android 11/12 列表为空？
A：确认已授权存储/媒体权限；部分机型需将文件放在 Download、Documents 或相册目录。

Q：iOS 为何不是同款 UI？
A：苹果沙盒限制，iOS 使用 UIDocumentPicker 系统界面，回调字段与 Android 对齐。

Q：大相册下加载很久或进入后自动关闭？
A：多见于图片数量极多（数千张以上）的设备。1.0.7+ 已将过滤/排序移至后台线程，并分页展示列表、限制缩略图并发解码。请更新插件后 重新制作自定义调试基座或云打包。仍异常时请提供机型、Android 版本、browseMode 及 adb logcat 中 ly028 / AndroidRuntime 相关日志。

Q：如何减轻扫描压力？
A：尽量指定 extensions、使用 browseMode=1 分类模式或缩小 groups 中 fileTypes，避免在「图片」分组下扫描全部相册。

Q：iOS / 鸿蒙为何没有目录浏览、分组 Tab？
A：系统沙盒限制，这两端使用系统文档选择器，仅支持 extensions、maxCount 等过滤；browseMode / groups / sortType / strings / theme 在 Android 自定义页生效。

Q：连续快速点击选文件没反应？
A：1.0.7+ 已防止重复打开选择器；请等待上一次选择结束（完成/取消）后再调用 pickFiles。

Q：Android 选择页顶部有白条、与顶栏颜色不一致？
A：1.1.4+ 已默认沉浸式状态栏，顶栏背景会延伸至状态栏区域。请更新插件并重新制作自定义基座或云打包。若 theme.headerGradientStart 为很浅的色，系统状态栏图标可能对比度不足，可改用较深顶栏色。

更新日志

见 changelog.md

点击下载体验

扫码体验