更新记录

1.0.1（2026-05-17）

优化性能

1.0.0（2026-05-17）

• 首发：Android / iOS / HarmonyOS 文件选择 UTS 插件
• Android：自定义选取界面（靛紫渐变顶栏 + 胶囊分组），支持目录浏览、扩展名分类、类型分组
• Android 11/12：MediaStore + 目录扫描，适配 Scoped Storage
• 单选/多选、数量限制、搜索、排序、已选清单、图片预览
• 可配置 extensions、groups、strings（国际化）、theme、sortType
• iOS / 鸿蒙：系统文档选择器，统一回调结构

平台兼容性

uni-app(3.7.7)

uni-app x(4.0)

其他

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 插件必须进入 自定义调试基座 或 正式云打包包体 才能运行；普通标准基座不包含本插件原生代码
• 定价：插件市场 10 元；源码授权 50 元

快速开始

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

国际化示例

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 对齐。

更新日志

见 changelog.md