更新记录

1.2.0（2026-07-09）

初始版本

平台兼容性

uni-app

uni-app x

nk-file-picker 文件选择器

一个基于 UTS 开发的原生文件选择插件，可以让用户选择手机上各种类型的文件并返回本地临时路径，方便后续上传或处理。

• ✅ 支持类型：图片 / 视频 / 音频 / PDF / Word / Excel / PPT / 纯文本 / 压缩包 / 常用文档 / 全部类型
• ✅ 支持自定义文件后缀白名单（如 dwg、psd）
• ✅ 支持多选
• ✅ 同时兼容 Android 与 iOS
• ✅ 返回的临时路径可直接用于 uni.uploadFile

平台说明：Android 使用系统「存储访问框架 SAF」(ACTION_OPEN_DOCUMENT)，iOS 使用系统文件选择器 UIDocumentPickerViewController，均为系统原生选择界面，无需额外后台权限。

一、引入插件

// 组合式写法
import { chooseFile } from '@/uni_modules/nk-file-picker'

或直接使用（UTS 插件会自动注册到 uni 命名空间视配置而定，推荐使用上面的 import 写法）。

二、API

chooseFile(options)

选择一个或多个文件。

options 参数

ChooseFileType 可选值

success 返回结果 ChooseFileSuccess

ChooseFileItem

错误码

三、使用示例

1. 选择任意类型文件

import { chooseFile } from '@/uni_modules/nk-file-picker'

chooseFile({
  success: (res) => {
    console.log('选择成功', res.tempFiles)
  },
  fail: (err) => {
    console.log('选择失败', err.errCode, err.errMsg)
  }
})

2. 只选择图片或视频

chooseFile({
  types: ['image', 'video'],
  success: (res) => {
    console.log(res.tempFilePaths)
  }
})

3. 选择常用文档（PDF / Word / Excel / PPT / txt）

chooseFile({
  types: ['document'],
  success: (res) => {
    res.tempFiles.forEach((f) => {
      console.log(f.name, f.extension, f.size)
    })
  }
})

4. 多选（最多 9 个）

chooseFile({
  types: ['image'],
  count: 9,
  success: (res) => {
    console.log('共选择了', res.tempFiles.length, '个文件')
  }
})

5. 自定义后缀

chooseFile({
  extensions: ['dwg', 'psd'],
  success: (res) => {
    console.log(res.tempFiles)
  }
})

6. 选择后上传

chooseFile({
  types: ['document'],
  success: (res) => {
    const file = res.tempFiles[0]
    uni.uploadFile({
      url: 'https://your-server.com/upload',
      filePath: file.tempFilePath,
      name: 'file',
      success: (uploadRes) => {
        console.log('上传成功', uploadRes)
      }
    })
  }
})

四、注意事项

1. 本插件为 UTS 原生插件，仅在 App（Android / iOS）平台生效，需使用自定义基座运行/打包。
2. count > 1 时开启多选：
   • iOS 系统文件选择器多选为「单击打勾」。
   • Android 在只选图片/视频（types 仅含 image/video）且系统为 Android 13(API 33)+ 时，自动使用系统相册选择器 Photo Picker，多选为「单击打勾」；其它类型（PDF/Word/压缩包等）走系统文件管理器（SAF），其多选需长按进入多选模式，这是系统交互限制，非插件问题。
3. iOS 会将所选文件复制到 uniapp 沙盒的 _doc/uniapp_temp/ 目录，返回相对路径，plus.io 可直接访问。
4. Android 会将所选文件复制到应用外部缓存目录，返回绝对路径。

五、开发文档

• UTS 语法
• UTS API 插件
• Hello UTS

六、更新日志

1.2.0

• Android 端优化多选体验：只选图片/视频且系统为 Android 13+ 时，自动使用系统相册选择器 Photo Picker（单击即勾选多选）

1.1.0

• 由「仅支持 PDF」升级为「支持选择各种类型文件」
• 新增 chooseFile API，支持 types 分类、自定义后缀、多选
• 返回结构升级为 tempFiles / tempFilePaths

1.0.0

• 初始版本，支持选择 PDF 文件