更新记录

0.1.0（2026-01-23）

首次提交。注意 文件多选数量仅仅 harmony 支持，Android 不支持文件类型的选择

平台兼容性

uni-app(4.0)

uni-app x(4.0)

q-native-file-picker

UTS 插件：使用系统原生 UI 打开文件选择器（Android / iOS / Harmony Next）。

平台说明

• App-Android：使用系统 ACTION_OPEN_DOCUMENT（Storage Access Framework）
• App-iOS：使用 UIDocumentPickerViewController
• App-Harmony Next：使用 @ohos.file.picker DocumentViewPicker
• Web/H5：进入 API 直接 toast 提示并返回 9012002

UTS 插件改动需要重新编译/重新打包基座后生效。

API

import { chooseFile } from "@/uni_modules/q-native-file-picker";

chooseFile({
  multiple: false,
  copyToCache: true,
  success: (res) => console.log(res),
  fail: (err) => console.log(err)
})

options

• multiple：是否多选（默认 false）
• maxCount：多选最大数量（<=0 或不传表示不限制；仅 multiple=true 生效；iOS 系统选择器不支持 UI 侧限制数量，插件会在回调结果中截断/过滤）
• fileTypes：文件类型过滤（扩展名数组，不含点，如 ["pdf","png"]；等价于 extensions，优先级更高；Android 会尽量从扩展名推导 MIME 以限制系统选择器，但依然可能被用户选到其它类型，最终会在结果侧过滤）
• mimeTypes：MIME 过滤（主要用于 Android，如 ["image/*","application/pdf"]；系统选择器过滤能力因 ROM/文件管理器不同而存在差异，插件会在结果侧做二次过滤；若过滤后为空会走 fail 回调并返回 9012005）
• copyToCache：是否复制到缓存目录（默认 true）

多选示例

chooseFile({
  multiple: true,
  maxCount: 3,
  fileTypes: ["pdf", "png", "jpg"],
  copyToCache: true,
  success: (res) => console.log(res),
  fail: (err) => console.log(err)
})

返回值

• files: 归一化后的文件数组（每项包含 name / size / mimeType / uri / path）。

关于 path 与 uri

• uri：系统返回的原始标识（Android 常为 content://...，iOS/Harmony 可能为 file://... 或其它 scheme）。
• path：当 copyToCache=true 时为插件复制到应用缓存/临时目录后的真实路径（更适合交给 uni.uploadFile）。

源码结构与实现原理

本文档以“API 使用说明”为主；若你需要了解各端技术实现方案（Android/iOS/Harmony/Web）与源码走向，请阅读：

• implementation.md（维护者/二次开发者向，包含各端实现细节与关键注意事项）

iOS 调试日志

• iOS 侧关键日志统一以 "[q-native-file-picker][iOS]" 开头，可在真机运行日志/Xcode 控制台中查看。