更新记录

0.1.3（2026-04-15）

• 新增 utssdk/app-ios/config.json，显式指定 iOS deploymentTarget 为 12.0，避免 UIDocumentPickerViewController.allowsMultipleSelection 在编译期被按低版本 API 拦截
• iOS 调整 chooseFile 内多选日志输出，避免为打印日志再次直接读取 picker.allowsMultipleSelection

0.1.2（2026-03-23）

• 修复 iOS 中系统文件选择弹窗在选中文件后长时间停留、再次确认时可能卡住且后续无法继续 pick 的问题
• iOS 调整 UIDocumentPickerViewController 会话管理，补充 picker / delegate 状态清理，避免异常场景下残留会话锁死后续调用
• iOS 文件选择器改为使用 UIDocumentPickerMode.open，与当前 security-scoped 读取和 copyToCache 流程保持一致

0.1.1（2026-03-23）

• 对齐 iOS / Android / Harmony 成功回调 files 项字段，iOS 与 Harmony 新增返回文件大小 size
• Harmony 在 copyToCache=true 时会在复制过程中累计文件大小，避免重复读取

平台兼容性

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）。

关于 size / path / uri

• size：三端都会尽量返回文件大小；若系统 provider/权限限制导致无法读取，则可能为 null。

• 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 控制台中查看。