更新记录

1.2.3（2026-07-27）

-优化加密包安全语法

1.2.2（2026-07-25）

-优化Android 鸿蒙 和IOS的交互体验以及更能增强，以及配置更新

1.2.1（2026-07-25）

-优化Android 鸿蒙 和IOS的交互体验以及更能增强

平台兼容性

uni-app(4.18)

uni-app x(4.18)

其他

ly028-filepicker

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

统一前端 API：extensions + maxCount 即可。Android 提供自定义选取页（含系统相册快捷入口）；iOS / 鸿蒙按扩展名自动走相册或系统文件选择器。

点击下载体验

扫码体验

平台支持

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

三端行为说明（重要）

前端同一套 pickFiles 参数；不要为 iOS/鸿蒙单独传平台参数。

快速开始

1. 安装

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

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

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

推荐使用 JS 封装（已兼容 App Android / iOS / 鸿蒙）：

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

// Android：自定义分组页；iOS/鸿蒙：按 extensions 进相册或文件
const ret = await LyFilePicker.pickFiles({
  browseMode: LyFilePicker.BROWSE_GROUP, // 仅 Android 有效
  maxCount: 10,
  extensions: 'png,jpg,pdf,docx,zip',
  sortType: 3 // 仅 Android 有效
})

if (ret.cancelled) {
  console.log('用户取消')
} else if (ret.ok && ret.data) {
  // 上传请优先使用 absolutePath（本地可读路径）
  ret.data.forEach((f) => console.log(f.name, f.absolutePath, f.sizeText))
}

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（仅 Android）

API

pickFiles(options) → Promise<LyPickResult>（js_sdk）

sortType（仅 Android）

返回结果 LyPickResult

返回 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',
    btnAlbum: 'Album', // Android 顶栏相册按钮
    selectedCount: 'Selected %1$s / %2$s',
    searchHint: 'Search file name',
    groupImages: 'Images',
    groupVideos: 'Videos',
    groupAudio: 'Audio',
    groupDocuments: 'Documents',
    groupArchives: 'Archives',
    groupApps: 'Apps'
  }
})

manifest 权限建议

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

• READ_EXTERNAL_STORAGE（Android 12 及以下）
• READ_MEDIA_IMAGES / READ_MEDIA_VIDEO / READ_MEDIA_AUDIO（Android 13+）
• Android 11+ 若需扫描更多目录，可能还需引导「所有文件访问」权限（插件内会提示）

iOS：相册选用系统 PHPicker，一般无需额外相册权限声明；Files 由系统授权。

HarmonyOS：读取用户所选文件 / 相册，按 module.json5 申请媒体与文件相关能力。

常见问题

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

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

Q：iOS / 鸿蒙为何不是同款自定义 UI？
A：系统沙盒限制。两端使用系统相册 + 系统文件选择器，回调字段与 Android 对齐；browseMode / groups / sortType / theme 仅 Android 生效。

Q：iOS / 鸿蒙怎么选相册里的照片和视频？
A：extensions 只含图片/视频时会直接进系统相册；与文档混合或未限制类型时，会先弹出「相册 / 文件」菜单。

Q：Android 顶栏「相册」什么时候出现？
A：当 extensions 包含任意图片或视频扩展名时显示。点选后进系统相册，确认后直接返回结果，无需再点「完成」。

Q：相册返回的路径和列表里不一样？
A：上传请统一用 absolutePath。Android 系统相册结果已拷贝为应用缓存下的本地路径；contentUri 仅为原始 URI 参考字段。

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

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

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

Q：Android 选择页顶部有白条、与顶栏颜色不一致？
A：1.1.4+ 已默认沉浸式状态栏。请更新插件并重新制作自定义基座或云打包。若 theme.headerGradientStart 很浅，可改用较深顶栏色以保证状态栏图标对比度。

更新日志

见 changelog.md

点击下载体验

扫码体验