更新记录

1.0.0（2026-08-11）

• 首发 x-filepick
• Android SAF + iOS UIDocumentPicker
• 多选 / preset / copyToCache / persistPermission
• 对标 sn-uts-file 并补齐双端与元数据

平台兼容性

uni-app

uni-app x(4.27)

x-filepick

uni-app x 零权限系统文件选择 UTS 插件（Android + iOS）。

对标 sn-uts-file #14309 的「系统选择器 + 零权限」思路，并按业界高星方案补齐双端、多选、元数据与本地副本。

相对 #14309 的差异

通用架构（调研结论）

详见 RESEARCH.md。核心共识：

1. Android：ACTION_OPEN_DOCUMENT（SAF）优于自建文件浏览器；零存储权限
2. iOS：UIDocumentPickerViewController(asCopy: true)
3. content:// / 临时 URL 不可长期持有 → 默认复制到应用 cache，返回 path 供 uni.uploadFile / FFmpeg 等使用

高星参考：react-native-documents/document-picker ~1505⭐、rosuH/AndroidFilePicker ~1068⭐（后者为自建 UI，本插件刻意不采用）。

安装

放入 uni_modules/x-filepick，制作自定义调试基座后运行。

API

chooseFile(options)

import { chooseFile } from '@/uni_modules/x-filepick'

chooseFile({
  preset: 'video',          // all | image | video | audio | pdf | doc
  // mimeTypes: ['application/pdf'],
  // extensions: ['mp4', 'mov'],
  multiple: false,
  count: 9,
  copyToCache: true,
  persistPermission: false, // Android only
  success(res) {
    console.log(res.count, res.files[0].path, res.files[0].uri)
  },
  fail(err) {
    console.log(err.errCode, err.errMsg) // 9040001 = 用户取消
  }
})

getPickedFileInfo / toUploadFile / isSupported / getPluginVersion

见 utssdk/interface.uts。

错误码（904xxxx）

权限与隐私

• 不申请 READ_EXTERNAL_STORAGE / READ_MEDIA_* / 相册权限
• 仅访问用户在系统选择器中主动选中的文件
• 不上传、不采集

注意

1. 改过 Kotlin/Swift 后需重新制作自定义基座
2. 系统文件管理器对 MIME 过滤因 ROM 而异；extensions 会在结果侧再过滤
3. uri（尤其 Android content://）为临时引用；上传/转码请用 copyToCache: true 得到的 path
4. 可与本仓库 x-ffmpeg 配合：选视频 → path → 压缩/截帧

许可

业务代码随项目；无第三方运行时依赖（仅系统 API）。