更新记录

1.0.1（2026-08-16） 下载此版本

逻辑优化

1.0.0（2026-08-13） 下载此版本

初始版本

平台兼容性

uni-app(4.41)

uni-app x(4.81)

scx-choosefile

uni-app 文件选择插件，同时支持 uniapp 和 uniapp x，覆盖 Android、iOS、鸿蒙 next、Web 和微信小程序。

功能特性

• 同时支持 uniapp 与 uniapp x 双框架
• 覆盖 H5 / 微信小程序 / Android / iOS / 鸿蒙 next 五端
• 统一 API 调用方式 chooseFile
• 同时支持 Promise 与回调两种调用方式
• 回调契约全平台统一：fail/complete 回调的 err 均为 { errCode, errMsg }，取消时 errCode === 1101001，调用方无需关心平台差异
• 支持文件类型过滤（image/video/audio/all）
• 支持文件后缀名限制
• 支持多选和单选模式
• 支持相册/相机来源指定（image/video，部分平台）
• Android 13+ 图片/视频选择支持 Photo Picker，UI 层面原生限制数量
• iOS 图片/视频走系统相册（PHPicker），文件走系统文件选择器

平台兼容性

所有平台统一走 utssdk/ 实现，由 HBuilderX 自动编译为目标平台代码。

iOS 版本要求：iOS 14.0 及以上（插件的 deploymentTarget 为 14.0，因为 iOS 14+ 的 UTType API 才能提供相册/视频库选择体验；iOS 14 以下版本无法编译该插件）。

安装方式

方式一：插件市场安装

在 DCloud 插件市场搜索 scx-choosefile，点击安装即可。

方式二：手动安装

将 uni_modules/scx-choosefile 目录复制到项目的 uni_modules 目录下。

使用方法

基础用法

import { chooseFile } from '@/uni_modules/scx-choosefile'

// Promise 方式
async function selectFile() {
  try {
    const result = await chooseFile({
      count: 10,
      type: 'all'
    })
    console.log('选择成功:', result.tempFiles)
  } catch (err) {
    // 说明：Promise reject 的值在非 iOS 平台为 { errCode, errMsg } 对象；
    // iOS 平台为 Error 对象（message 为 JSON 字符串，含 errCode/errMsg）。
    // 取消判断建议使用回调方式（见下方），或对 err.message 做 /cancel|取消/ 匹配
    console.error('选择失败:', err)
  }
}

// 回调方式（推荐）：fail 回调的 err 为 { errCode, errMsg }，全平台一致
chooseFile({
  count: 10,
  type: 'all',
  success: (result) => {
    console.log('选择成功:', result.tempFiles)
  },
  fail: (err) => {
    if (err.errCode === 1101001) {
      console.log('已取消')
    } else {
      console.error('选择失败:', err.errMsg)
    }
  }
})

参数说明

sourceType 平台支持见上方"平台兼容性"表格，不支持的平台会静默忽略。

返回值说明

成功时返回 ChooseFileSuccess 对象：

ChooseFileTempFile 字段：

失败时 fail/complete 回调返回 ChooseFileFail 对象（全平台统一）：

Promise 方式注意：iOS 平台 UTS 插件 Promise reject 的值为 Error 对象（其 message 为 JSON 字符串，含 errCode/errMsg），与回调方式（fail 参数）的对象形态不同；若需要统一的取消判断，请优先使用 success/fail/complete 回调方式。

错误码说明

完整示例

import { chooseFile } from '@/uni_modules/scx-choosefile'

// 选择图片（仅相册，不弹拍摄选项）
async function chooseImage() {
  const result = await chooseFile({
    count: 9,
    type: 'image',
    sourceType: ['album']
  })
  console.log('选择了', result.tempFiles.length, '张图片')
}

// 选择视频（仅相册）
async function chooseVideo() {
  const result = await chooseFile({
    count: 5,
    type: 'video',
    sourceType: ['album']
  })
  console.log('选择了', result.tempFiles.length, '个视频')
}

// 选择指定格式文件
async function chooseDocument() {
  const result = await chooseFile({
    count: 5,
    type: 'all',
    extension: ['pdf', 'doc', 'docx', 'xlsx']
  })
  console.log('选择了', result.tempFiles.length, '个文档')
}

// 单选文件
async function chooseSingle() {
  const result = await chooseFile({
    count: 1,
    type: 'all'
  })
  console.log('选择了:', result.tempFiles[0].name)
}

注意事项

1. 微信小程序限制：微信小程序端使用 uni.chooseMessageFile 实现，仅能选择微信会话中的文件，无法访问手机本地文件系统。sourceType 在该端不生效。

2. Android 权限：Android 端使用系统文件选择器（SAF / ACTION_GET_CONTENT），无需在 manifest.json 中声明 READ_EXTERNAL_STORAGE 权限。

3. iOS 权限：iOS 端使用 PHPicker 与 UIDocumentPickerViewController，均无需在 Info.plist 中添加额外权限说明。

4. 鸿蒙权限：鸿蒙端使用 filePicker.select，无需在 module.json5 中配置文件访问权限。

5. 文件路径格式：各平台返回的 path 格式不同：

   • H5：blob: 协议
   • 微信小程序：wxfile:// 协议
   • Android：通常为 content:// 协议
   • iOS：通常为 file:// 协议
   • 鸿蒙：通常为 file://docs/... URI

6. 文件大小：iOS/Android 原生实现会通过系统接口计算真实文件大小；Web/小程序由浏览器/微信提供。若个别文件仍为 0，可调用 uni.getFileInfo 二次确认。

7. 并发调用：UTS Android/iOS 实现做了单例保护，上一次选择未结束前再次调用会立即返回 errCode: 1101010。

8. 数量限制策略：image/video 在 UI 层原生限制数量（chooseMedia / Photo Picker / PHPicker）；audio/all/extension 等系统选择器无法在 UI 层限制，按"选多少返回多少"处理，不截断不报错。

9. iOS 文件路径为临时文件：iOS 返回的 path 是系统生成的临时文件（PHPicker 临时目录 / UIDocumentPicker 的 Inbox），App 退出或系统清理后可能失效，适合"选中即读取/上传"场景；需要长期持有文件时，请在业务侧用 uni.saveFile 等接口复制到持久目录。

10. iOS 取消识别：iOS 打开选择器直接返回时，PHPicker 空结果与 UIDocumentPicker 取消均按 errCode: 1101001（用户取消）处理，与其它平台行为一致。

技术架构

                        chooseFile
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
     Android               iOS                  鸿蒙 next
   (UTS → Kotlin)     (UTS → Swift)        (UTS → ArkTS)
   chooseMedia /       PHPicker +           picker.*ViewPicker
   ACTION_OPEN_        UIDocumentPicker
   DOCUMENT / GET_     (hybrid.swift)
   CONTENT

        ┌─────────────────────┐
        ▼                     ▼
       H5                微信小程序
   (UTS → JS)          (UTS → JS)
   <input type=file>   chooseMessageFile

所有平台统一通过 utssdk/ 目录实现，HBuilderX 根据目标平台自动编译。

目录结构

uni_modules/scx-choosefile/
├── index.js                       # 普通 uni-app 统一入口（条件编译分发 + App 平台 JS 兜底）
├── package.json                   # 插件配置
├── platform.json                  # 平台支持声明
├── README.md                      # 使用文档
└── utssdk/                        # UTS 插件实现（所有平台统一）
    ├── index.uts                  # 跨平台兜底入口（仅 re-export 类型声明）
    ├── interface.uts              # 对外类型定义与统一契约
    ├── config.json                # UTS 插件配置
    ├── app-android/
    │   └── index.uts              # Android 实现（chooseMedia / OPEN_DOCUMENT / GET_CONTENT）
    ├── app-ios/
    │   ├── index.uts              # iOS UTS 入口（PHPicker / UIDocumentPicker 路由）
    │   ├── hybrid.swift           # iOS 原生实现（Swift，与 index.uts 混编）
    │   └── config.json            # iOS 部署版本等配置（deploymentTarget 14.0）
    ├── app-harmony/
    │   └── index.uts              # 鸿蒙实现（picker.PhotoViewPicker / AudioViewPicker / DocumentViewPicker）
    ├── web/
    │   └── index.js               # H5 实现（<input type="file">）
    └── mp-weixin/
        └── index.js               # 微信小程序实现（chooseMessageFile）

更新日志

v1.0.0

• 初始版本
• 支持 H5、微信小程序、Android、iOS、鸿蒙 next 平台
• 提供统一的 chooseFile API
• 统一 UTS 插件架构，所有平台通过 utssdk/ 实现

许可证

MIT License