更新记录

1.0.3（2026-04-13） 下载此版本

文档

• readme.md：新增章节「选择结果与 uni.uploadFile」，说明与上传 API 的衔接：tempFilePath 作为 filePath、uni.uploadFile 的 name（表单字段名）与插件返回的 files[i].name（真实文件名）的区别；file://（常见 iOS）与 content://（常见 Android）路径注意点；多选时需对 files 逐项调用 uni.uploadFile；附最小示例（含路径规范化示例函数）。

仓库内关联说明（非插件包内文件）

• docs/m-choose-file修复文档.md：补充对外契约索引、readme 与选后上传的交叉引用；新增方案节 4.5（文档与 uni.uploadFile）；实施步骤、回归清单、验收标准、版本建议与上述文档对齐。

1.0.2（2025-11-14） 下载此版本

1、增加根据文件类型筛选功能，不同平台存在差异

1.0.1（2025-11-14） 下载此版本

1、修复鸿蒙报错问题

平台兼容性

uni-app(4.83)

uni-app x(4.83)

m-choose-file

uni-app UTS 插件，用于在 APP 平台选择文件。

平台支持

• ✅ Android
• ✅ iOS
• ✅ HarmonyOS
• ❌ 其他平台（会返回错误）

安装

将插件放置在 uni_modules 目录下即可。

使用方法

导入插件

import { onChooseFile } from '@/uni_modules/m-choose-file'

基本用法

// 选择单个文件
onChooseFile({
  maxSelectNumber: 1
})
  .then((res) => {
    if(res.files.length){
      console.log('选择的文件:', res.files)
    }
  })
  .catch((err) => {
    console.error('选择失败:', err)
  })

选择多个文件

// 选择多个文件（最多5个）
onChooseFile({
  maxSelectNumber: 5
})
  .then((res) => {
    if(res.files.length){
      console.log('选择的文件:', res.files)
    }
  })
  .catch((err) => {
    console.error('选择失败:', err)
  })

按文件类型过滤

// 只选择图片文件
onChooseFile({
  maxSelectNumber: 1,
  fileTypes: ['image']
})
  .then((res) => {
    if(res.files.length){
      console.log('选择的图片:', res.files)
    }
  })
  .catch((err) => {
    console.error('选择失败:', err)
  })

// 选择图片或视频
onChooseFile({
  maxSelectNumber: 5,
  fileTypes: ['image', 'video']
})
  .then((res) => {
    if(res.files.length){
      console.log('选择的文件:', res.files)
    }
  })
  .catch((err) => {
    console.error('选择失败:', err)
  })

// 选择文档文件
onChooseFile({
  maxSelectNumber: 1,
  fileTypes: ['doc']
})
  .then((res) => {
    if(res.files.length){
      console.log('选择的文档:', res.files)
    }
  })
  .catch((err) => {
    console.error('选择失败:', err)
  })

参数说明

fileTypes 支持的类型

注意：

• fileTypes 可以传入多个类型，例如 ['image', 'video'] 表示同时支持图片和视频
• 当传入 ['all'] 或不传入 fileTypes 时，不限制文件类型
• 针对ios/harmony/android的文件限制代码结构不一样，选择限制可能存在偏差
• 本插件不返回文件内容的 base64，仅返回 tempFilePath 与元数据；历史参数 useBase64 已从类型与实现中移除，请自行按需读取文件再编码

返回值

{
  files: [
    {
      tempFilePath: string,  // 文件临时路径
      name: string,          // 文件名
      type: string,          // 文件 MIME 类型
      size: number           // 文件大小（字节）
    }
  ]
}

错误码

失败时 Promise 进入 catch，参数为对象 { errCode: number, errMsg: string }（与 uni_modules/m-choose-file/index.js 中 M_CHOOSE_FILE_ERR 一致）。

完整示例

<template>
  <button @click="chooseFile">选择文件</button>
</template>

<script setup>
import { onChooseFile } from '@/uni_modules/m-choose-file'

const chooseFile = () => {
  onChooseFile({
    maxSelectNumber: 1
  })
    .then((res) => {
      if(res.files.length){
        console.log('选择的文件:', res.files)
        uni.showToast({ title: '选择成功', icon: 'success' })
      }
    })
    .catch((err) => {
      console.error('选择失败:', err)
      uni.showToast({ title: '选择失败', icon: 'none' })
    })
}
</script>

选择结果与 uni.uploadFile

本插件只返回本地路径与元数据，上传需自行调用 uni.uploadFile。

filePath 从哪里来

uni.uploadFile 的必填项 filePath，对应本插件返回的 tempFilePath（每个选中文件一项）。

name 指什么（易混点）

uni.uploadFile 里的 name 是后端接收文件的表单字段名（例如 "file"、"upload"），由接口约定决定；不是磁盘上的文件名。插件返回的 files[i].name 是真实文件名，若接口要求在 formData 里再传一份文件名，可自行增加字段，例如 formData: { fileName: f.name }。

路径与平台

• file:// 开头（常见于 iOS 文档等）：部分环境下对 uni.uploadFile 更稳妥的做法是去掉 file:// 前缀，并对路径做 decodeURI 后再传入 filePath（保留失败时再退回原字符串）。
• content://（常见于 Android）：一般原样作为 filePath 传入，不要强行改写成 file 路径。

多文件

uni.uploadFile 单次只传一个文件。maxSelectNumber > 1 时，对 res.files 逐项调用 uni.uploadFile（可串行或自行控制并发），每次使用对应项的 tempFilePath。

最小示例

import { onChooseFile } from '@/uni_modules/m-choose-file'

function normalizeUploadFilePath(uri) {
  if (uri == null || typeof uri !== 'string') return uri
  if (uri.indexOf('file://') === 0) {
    try {
      return decodeURI(uri.replace(/^file:\/\//, ''))
    } catch (e) {
      return uri.replace(/^file:\/\//, '')
    }
  }
  return uri
}

onChooseFile({ maxSelectNumber: 1 })
  .then((res) => {
    const f = res.files[0]
    if (!f) return
    uni.uploadFile({
      url: 'https://example.com/upload',
      filePath: normalizeUploadFilePath(f.tempFilePath),
      name: 'file',
      header: {},
      formData: {},
      success(uploadRes) {
        // uploadRes.data 多为字符串，需 JSON.parse 再处理
      },
      fail(err) {
        console.error(err.errMsg)
      },
    })
  })

开发文档

• UTS 语法
• UTS API插件
• UTS uni-app兼容模式组件
• UTS 标准模式组件
• Hello UTS