更新记录

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 编译运行,需完成宿主项目的鸿蒙签名配置。
  • 先在目标工程中确认选择、取消和返回文件路径可用,再购买对应授权。

参考:DCloud UTS 插件发布与授权说明。

安装与调用

从插件市场导入,或将插件目录放到项目的 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 版本、系统版本、授权版本、错误信息及复现步骤。不要提供账号凭证或包含敏感内容的文件。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

通过系统文件选择器获取用户选中文件的临时访问授权,并复制到应用缓存,不申请全盘读写权限。iOS 包含文件夹用途说明及文件共享配置,详见使用说明。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据,不向服务器发送文件内容或文件信息。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无