更新记录
1.0.0(2026-11-17)
- 首次发布,提供 App 批量文件选择,支持数量限制、超限文件提示和缓存复制。
平台兼容性
uni-app(5.34)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| - | √ | × | × | √ | - | 5.0 | 12 | HarmonyOS NEXT |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| × | × | × | × | × | × | × | × | × | × | × | × |
x-file-choose
App 批量文件选择 UTS 插件,通过系统文件选择器选择本地文件,返回文件名、缓存路径和文件大小。只提供 chooseFiles(options),单选传 count: 1。
授权与支持范围
| 授权 | 价格 | 支持范围 | 交付 |
|---|---|---|---|
| 普通授权版 | 9.90 元 | 包含 Android / iOS / HarmonyOS 实现 | 核心实现加密 |
| 源码授权版 | 99.00 元 | uni-app Vue3 / Android / iOS / HarmonyOS | 提供插件源码,可按市场授权约定修改 |
两种授权包含相同的三端实现,不按平台删减功能;区别是实现源码是否可见、可修改。两种授权均按插件市场规则绑定项目 AppID 和包名,源码授权不代表不限项目使用。
首发面向 HBuilderX 5.34 及以上正式版。Android 原生配置最低 API 21 / Android 5.0,iOS 原生配置最低 iOS 12;宿主运行环境若要求更高版本,以宿主要求为准。HarmonyOS 指 HarmonyOS NEXT 原生应用。
现有实现已在 uni-app Vue3 的 Android / iOS / HarmonyOS 真机上验证批量选择。Vue2、nvue、uni-app x 尚未验证,不作支持承诺。Web / 微信小程序及其他小程序不支持。
打包与试用
- Android / iOS 导入后需制作包含本插件的自定义调试基座。普通授权版及市场试用版使用云端传统打包,不支持安心打包和离线打包。
- 试用版用于自定义调试基座,不用于正式发行。
- 鸿蒙通过 HBuilderX / DevEco Studio 编译运行,需完成宿主项目的鸿蒙签名配置。
- 先在目标工程中确认选择、取消和返回文件路径可用,再购买对应授权。
安装与调用
从插件市场导入,或将插件目录放到项目的 uni_modules/x-file-choose。
// #ifdef APP-PLUS || APP-HARMONY
import { chooseFiles } from '@/uni_modules/x-file-choose'
chooseFiles({
count: 5,
maxSize: 10 * 1024 * 1024,
success: (res) => {
console.log('选中的文件', res.files)
console.log('超过大小上限的文件名', res.oversized)
},
fail: (err) => {
console.log(err.errCode, err.errMsg)
}
})
// #endif
上述示例展示三端统一调用方式。
参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| count | number | 否 | 最多返回的文件数,默认 9,传正整数 |
| maxSize | number | 否 | 单文件字节上限,不传或传 0 不限;超过上限的文件名放入 oversized |
| success | function | 否 | 成功回调,返回 { files, oversized } |
| fail | function | 否 | 失败回调,返回错误对象,没有文件 path |
| complete | function | 否 | 完成回调,成功时返回成功结果,失败时返回错误对象 |
返回结果
| 字段 | 类型 | 说明 |
|---|---|---|
| files | Array | 成功复制到缓存的文件列表 |
| files[].name | string | 文件名,包含原有扩展名 |
| files[].path | string | file:// 开头的应用缓存绝对路径 |
| files[].size | number | 缓存文件大小,单位字节 |
| oversized | string[] | 已识别为超过 maxSize 的文件名 |
插件只负责选择和复制文件,不上传文件、不保存到系统下载目录。需要上传时,由调用方使用返回的路径调用上传接口。
错误码
| errCode | errMsg | 说明 |
|---|---|---|
| 9010001 | 用户取消选择 | 选择器返回取消或空结果;鸿蒙选择器拒绝也映射为此错误 |
| 9010002 | 读取文件失败 | 缓存目录创建失败或文件无法成功复制等读取错误 |
取消也会走 fail,请提供失败回调,避免调用方一直停留在“选择中”。
平台差异与使用边界
- Android 通常长按文件进入多选;iOS / 鸿蒙按系统选择器的多选入口操作,具体界面取决于系统版本和文件提供方。
- 鸿蒙在系统选择器中限制数量。Android 在复制前截取前
count个选择结果;iOS 先复制,再截取前count个成功文件返回,可能产生未返回的缓存文件。 maxSize在复制前按源文件大小判断;取不到源文件大小时放行,不是严格的文件大小安全校验。调用方如有硬性要求,需再检查返回的size,服务端也应独立校验。- 全部文件超过
maxSize时仍调用success,此时files为空,调用方应读取oversized提示。部分文件复制失败会被跳过,成功返回不代表所有选中文件都已复制。 - 每次选择使用独立时间戳目录。同一批次内不要选择同名文件,当前实现未为同批同名文件分配独立路径。
- 等待本次选择结束后再调用下一次选择,不并发调用。
- Android 收到本插件结果后会调用
UTSAndroid.offAppActivityResult()注销全部 ActivityResult 监听。与其他同样注册监听的插件共用时,请在目标工程中确认交互。 - 文件复制需要磁盘空间和时间,大文件或大量文件可能造成等待;不提供复制进度和取消复制接口。
缓存与隐私
选中文件会复制到应用缓存中的 x-file-choose/<时间戳>/ 目录,便于选择后继续填写表单、稍后再上传。缓存不是永久存储,系统可能清理,插件不主动定时清理;需要长期保存或及时释放空间时,由调用方自行处理。
插件通过系统文件选择器获取用户选中文件的临时访问授权,不申请全盘读写权限,不采集数据、不向服务器发送文件内容或文件信息、不包含广告。
iOS 的 utssdk/app-ios/info.plist 包含文件夹访问用途说明、UIFileSharingEnabled 和 LSSupportsOpeningDocumentsInPlace 配置。集成后请核对最终宿主 App 的文件共享行为与隐私声明。
反馈
请通过插件市场评论或 uni-im 反馈,并提供 HBuilderX 版本、系统版本、授权版本、错误信息及复现步骤。不要提供账号凭证或包含敏感内容的文件。

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 1
赞赏 0
下载 12770518
赞赏 1959
赞赏
京公网安备:11010802035340号