更新记录

1.0.0（2026-02-11） 下载此版本

平台兼容性

uni-app(4.0)

x-native-uploader 原生文件上传组件

x-native-uploader 是一个跨平台的文件上传组件，专为解决 UniApp 在 App 端文件选择与上传的痛点而设计。它集成了 Native.js 的能力，支持在 Android 和 iOS 上调用原生文件选择器，同时兼容 H5 和小程序平台。

功能特性

• 📱 原生体验: App 端使用 Native.js 调用系统原生文件选择器 (Intent / UIDocumentPicker)，支持选择任意类型文件。
• 🚀 高性能上传: App 端使用 plus.uploader 实现原生上传，支持后台传输、大文件上传，比 WebView AJAX 更稳定。
• 🔄 跨平台兼容: 自动降级处理，H5 使用 uni.chooseFile，小程序使用 uni.chooseMessageFile，一套代码多端运行。
• 📦 多选支持: 支持一次选择多个文件进行批量上传 (Android/iOS/H5/MP)。
• 🛠️ 灵活配置: 支持自定义上传 URL、Header、FormData 以及自定义触发按钮 UI。

引入组件

import xNativeUploader from '@/components/x-native-uploader/x-native-uploader.vue';

export default {
  components: {
    xNativeUploader
  }
}

代码演示

基础用法 (单选)

默认点击按钮选择单个文件并自动上传。

<x-native-uploader
  url="https://your-api.com/upload"
  :header="{ 'Authorization': 'Bearer token' }"
  :formData="{ userId: '123' }"
  @success="onSuccess"
  @fail="onFail"
></x-native-uploader>

多文件上传

设置 multiple 属性开启多选，limit 控制最大选择数量。

<x-native-uploader
  url="https://your-api.com/upload"
  :multiple="true"
  :limit="9"
  fileType="all"
  @success="onSuccess"
  @fail="onFail"
>
  <view class="custom-btn">
    <text>点击批量上传文件</text>
  </view>
</x-native-uploader>

自定义触发按钮

通过默认插槽 (slot) 自定义上传按钮样式。

<x-native-uploader url="...">
  <button type="primary">点击上传</button>
</x-native-uploader>

API

Props

Events

FileObj 数据结构

{
  path: "...",       // 文件本地路径
  name: "...",       // 文件名
  progress: 100,     // 上传进度 (0-100)
  status: "success", // 状态: pending, uploading, success, error
  statusText: "..."  // 状态描述文本
}

注意事项

1. Android 权限: App 端需要 READ_EXTERNAL_STORAGE 和 WRITE_EXTERNAL_STORAGE 权限。
2. iOS 配置: iOS 端无需特殊配置，使用 UIDocumentPickerViewController。
3. H5 跨域: 确保上传接口支持 CORS 跨域请求。
4. 小程序: 微信小程序使用 uni.chooseMessageFile，支持从聊天记录中选择文件。