更新记录

0.1.0（2026-11-12）

• 首版提供 Android SAF 授权目录浏览，无需申请全盘存储权限。
• 支持按扩展名过滤、搜索当前目录、按时间/名称/大小排序、刷新及受限多选。
• 选择结果提供文件信息、原始 URI 和应用缓存路径。
• 提供共享 uni-app x 试用工程。

平台兼容性

uni-app x(5.24)

其他

Android 文件选择器

Android UTS API 插件，在用户授权的 SAF 目录内按扩展名过滤、搜索、排序、刷新和多选文件。应用不申请 MANAGE_EXTERNAL_STORAGE 或传统外部存储权限。

接入

将 uni_modules/android-file-picker/ 导入 uni-app x 项目，制作包含本插件的自定义基座后调用：

import { openAndroidFilePicker } from '@/uni_modules/android-file-picker'

openAndroidFilePicker({
  extensions: ['pdf', 'docx', 'xlsx'],
  multiple: true,
  count: 5,
  title: '选择报销附件',
  onSuccess: (files) => {
    files.forEach((file) => {
      console.log(file.name, file.path, file.size)
    })
  },
  onCancel: () => {
    console.log('用户取消选择')
  },
  onError: (message) => {
    console.error(message)
  }
})

首次调用时 Android 系统会要求用户选择一个目录并授权。插件只浏览该目录及其子目录；目录授权会保留以便后续打开。当前列表搜索针对所在目录，进入子目录后重新搜索。文件按扩展名过滤，不匹配类型的文件不会显示。“排序”提供按时间、名称、大小升降序，目录始终排在文件前。多选时在每项前勾选，count 会在选择时强制限制，0 表示不设上限。

成功结果里的 path 是插件从 content:// URI 完整复制到应用缓存的本地路径，可交给 uni.uploadFile 上传；uri 是原始 SAF URI。应用缓存可能被系统清理，应在业务使用后尽快上传，不要把缓存路径当永久文件路径。取消时只触发 onCancel，不会调用 onSuccess。

适用 Android 7.0 及以上，iOS 和鸿蒙不支持。当前版本已通过 HBuilderX 5.34 的 uni-app x 自定义基座在 MuMu Android 12 验证过滤、搜索、多选上限、取消和缓存路径；排序在原生对比 APK 中验证。实体手机和 uni-app Vue 3 尚未验证，发布兼容表仅标记已验证的 uni-app x Android。