更新记录

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 调用方式 scx.chooseFile
• 同时支持 Promise 与回调两种调用方式
• 支持文件类型过滤（image/video/audio/all）
• 支持文件后缀名限制
• 支持多选和单选模式
• 支持相册/相机来源指定（image/video，部分平台）

平台兼容性

注：uniapp 项目走 js_sdk/ 实现，uniapp x 项目走 utssdk/ 实现，由 HBuilderX 自动选择。

安装方式

方式一：插件市场安装

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

方式二：手动安装

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

使用方法

基础用法

import scx from '@/uni_modules/scx-choosefile/js_sdk/index.js'

// Promise 方式
async function chooseFile() {
  try {
    const result = await scx.chooseFile({
      count: 10,
      type: 'all'
    })
    console.log('选择成功:', result.tempFiles)
  } catch (err) {
    console.error('选择失败:', err)
  }
}

// 回调方式
scx.chooseFile({
  count: 10,
  type: 'all',
  success: (result) => {
    console.log('选择成功:', result.tempFiles)
  },
  fail: (err) => {
    console.error('选择失败:', err)
  }
})

uniapp x 项目

uniapp x 项目可直接通过 uni.requireNativePlugin 或导入 utssdk 入口使用：

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

chooseFile({ count: 10, type: 'all' }).then(res => {
  console.log(res.tempFiles)
})

参数说明

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

返回值说明

成功时返回 ChooseFileSuccess 对象：

ChooseFileTempFile 字段：

失败时返回 ChooseFileFail 对象：

错误码说明

完整示例

import scx from '@/uni_modules/scx-choosefile/js_sdk/index.js'

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

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

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

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

注意事项

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

2. Android 权限：Android 端使用系统文件选择器（SAF / ACTION_GET_CONTENT），无需在 manifest.json 中声明 READ_EXTERNAL_STORAGE 权限。仅在 uniapp（plus.android 路径）下会主动申请该权限作为兼容性兜底，可被拒绝而不影响选择。

3. iOS 权限：iOS 端使用 UIDocumentPickerViewController，无需在 Info.plist 中添加额外权限说明。如果通过 uni.chooseImage/uni.chooseVideo 走相册路径，则需配置 NSPhotoLibraryUsageDescription。

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

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

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

6. 文件大小：原生实现（Android UTS、iOS UTS、plus.android）当前返回 size: 0，如需精确大小请通过 uni.getFileInfo 等接口查询。

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

技术架构

                        scx.chooseFile
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
  uniapp 项目              uniapp x 项目       微信小程序 / H5
  (js_sdk/)               (utssdk/)           (js_sdk/)
        │                     │
   ┌────┴────┐          ┌─────┼─────┐
   ▼         ▼          ▼     ▼     ▼
 Android   iOS        Android iOS   鸿蒙
 (plus     (uni.     (UTS    (UTS  (UTS
  .android) choose*)  原生)   原生)  原生)

目录结构

uni_modules/scx-choosefile/
├── js_sdk/                         # uniapp / 小程序 / H5 端入口
│   ├── platform/
│   │   ├── h5.js                   # H5 实现
│   │   ├── mp-weixin.js            # 微信小程序实现
│   │   ├── app.js                  # App Android（plus.android）实现
│   │   ├── app-ios.js              # App iOS（uni.chooseImage/Video + plus.io）实现
│   │   └── app-harmony.js          # 鸿蒙 next（uni.chooseFile）实现
│   ├── index.js                    # 入口（条件编译分发）
│   └── index.d.ts                  # TypeScript 类型定义
├── utssdk/                         # uniapp x 端入口
│   ├── app-android/
│   │   └── index.uts               # Android 原生实现（Intent + SAF）
│   ├── app-ios/
│   │   └── index.uts               # iOS 原生实现（UIDocumentPickerViewController）
│   ├── app-harmony/
│   │   └── index.uts               # 鸿蒙原生实现（filePicker）
│   ├── chooseFile.uts              # UTS 入口（条件编译分发）
│   ├── interface.uts               # UTS 类型定义
│   └── config.json                 # UTS 插件配置
├── package.json                    # 插件配置
├── platform.json                   # 平台支持声明
└── README.md                       # 使用文档

更新日志

v1.0.0

• 初始版本
• 支持 H5、微信小程序、Android、iOS、鸿蒙 next 平台
• 提供统一的 scx.chooseFile API

许可证

MIT License