更新记录

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

• 首个发布版本：跨端通用文件上传组件
• 支持 APP（Android / iOS / 鸿蒙）、H5、小程序
• APP 端提供「拍照 / 相册选择图片 / 选择文件」统一选择入口：
  • accept="all" → 拍照 / 相册选择图片 / 选择文件
  • accept="image" → 拍照 / 从相册选择
  • 其它类型 → 直接调起原生文件选择器
• 鸿蒙端基于 DocumentViewPicker 原生选文件（复制到应用沙盒后回传本地路径）
• UI 与逻辑彻底解耦：支持 #default / #item 作用域插槽自定义
• 内置能力：上传队列、进度回显、失败重试、文件大小 / 数量限制、手动接管上传（autoUpload=false）

平台兼容性

uni-app(4.57)

uni-app x(5.05)

其他

jq-upload（跨端文件上传组件）

📦 更新记录

1.0.0（2026-10-13）

跨端通用上传组件首个发布版本（详见 changelog.md）

🌐 平台兼容性

uni-app（5.12）

uni-app x（5.12）

其他

🎯 核心特性

• UI 与逻辑彻底解耦：使用 Vue3 作用域插槽 (Scope Slot) 进行 UI 控制，如果不传插槽，默认提供极简的回显和上传按钮。
• 匹配所有平台：APP + H5 + 小程序，其中 APP 端 Android / iOS / 鸿蒙 均已适配。
• APP 端统一选择入口：
  • accept="all"：弹出「拍照 / 相册选择图片 / 选择文件」；
  • accept="image"：弹出「拍照 / 从相册选择」；
  • 其它类型：直接调起原生文件选择器。
• 鸿蒙原生文件选择：基于 DocumentViewPicker 选择文件并复制到应用沙盒后回传本地路径。

💻 基本用法

1. 使用默认 UI

<template>
  <jq-upload
    v-model="fileList"
    action="https://xxx.com/api/upload"
    :headers="{ token: '123' }"
    @success="handleSuccess"
  />
</template>

<script setup>
import { ref } from "vue";
const fileList = ref([]);
const handleSuccess = ({ file, response }) => {
  console.log("上传成功", response);
};
</script>

2. 自定义 UI

通过 #item 和 #default 插槽渲染。

<template>
  <jq-upload v-model="fileList" action="https://xxxx.com/api/upload" accept="image">
    <!-- 1. 定制文件列表展示 -->
    <template #item="{ file, index, deleteItem }">
      <view class="my-custom-file">
        <image :src="file.url" mode="aspectFill"></image>
        <text>进度: {{ file.progress }}%</text>
        <button size="mini" @click="deleteItem">删除</button>
      </view>
    </template>

    <!-- 2. 定制触发上传按钮 -->
    <template #default="{ disabled, triggerPick }">
      <button :disabled="disabled" type="primary" @click="triggerPick">点击上传图片</button>
    </template>
  </jq-upload>
</template>

3. 完全手动控制上传 (复杂业务逻辑)

当你的业务有极其复杂的上传流程（如需要先算 MD5、处理秒传逻辑、或者分片上传）时，可以关闭自动上传，通过监听 @change 手动接管。

<template>
  <jq-upload v-model="fileList" :autoUpload="false" @change="onChange">
    <!-- 这里同样可以像上面一样完全自定义 UI -->
  </jq-upload>
</template>

<script setup>
import { ref } from "vue";

const fileList = ref([]);

const onChange = (newList) => {
  // 找出刚刚由 jq-upload 加入队列，状态为 pending 的新文件
  const pendingFiles = newList.filter((f) => f.status === "pending");

  pendingFiles.forEach(async (file) => {
    // 1. 手动标记为上传中，UI 也会跟着转圈圈
    file.status = "uploading";

    // 2. 走你自己的复杂上传逻辑 (比如 uni.uploadFile 或者云储存 SDK)
    try {
      const res = await myCustomUploadLogic(file.url);
      file.status = "success";
      file.url = res.serverUrl; // 回填服务器地址
    } catch (err) {
      file.status = "failed";
    }
  });
};
</script>

🛠 参数说明 (Props)

说明：v-model 对应组件内部 modelValue；当 autoUpload=false 时需自行监听 @change 并处理上传，action 可不填。

⚡ 事件说明 (Events)

🧩 插槽说明 (Slots)

🔧 Expose 暴露方法

如果希望在外部利用 ref 使用：

• triggerPick(): 主动调起底层设备的文件选择弹窗。
• deleteItem(index): 手动删除指定索引的文件。
• retryUpload(index): 重试指定索引的失败文件。
• startUploadAll(): 手动批量上传所有待上传/失败文件。
• fileList: 当前文件列表（响应式）。
• hasPending: 是否存在待上传/失败文件（响应式）。