更新记录

1.0.0（2026-06-07） 下载此版本

v1.0.0 (2026-06-07)

• ✨ 初始版本发布

平台兼容性

uni-app(5.0)

📖 简介

`aura-upload-cloud` 是一个专为 uniCloud 设计的文件上传组件，支持图片、视频、音频等多种文件类型，提供网格/列表两种展示模式，开箱即用。

✨ 特性

• 📸 多类型支持 - 图片、视频、音频、文件
• ☁️ uniCloud 云存储 - 自动上传到云存储空间
• 🎨 双布局模式 - 网格布局（图片/视频）/ 列表布局（音频/文件）
• 📱 多端兼容 - 支持 App、H5、各小程序平台
• 🔄 上传进度 - 实时显示上传进度
• 🖼️ 在线预览 - 图片预览、视频播放、音频播放
• 🔁 失败重试 - 上传失败自动重试
• 🗑️ 删除回调 - 支持自定义删除逻辑
• ⚙️ 高度可配置 - 丰富的配置选项

📦 安装

通过插件市场安装

1. 在 DCloud 插件市场搜索 `aura-upload-cloud`
2. 点击「使用 HBuilderX 导入插件」
3. 选择你的项目，点击确定

准备工作

确保你的项目已满足以下条件：

✅ 已启用 uniCloud 并关联服务空间

✅ 已配置云存储权限

✅ HBuilderX 版本 >= 3.1.0

🚀 快速开始

基础用法

<template>
  <view>
    <!-- 图片上传（网格布局） -->
    <aura-upload-cloud
      v-model="images"
      upload-dir="avatar"
      file-type="image"
      :max-count="9"
      :columns="4"
    />

    <!-- 已上传的文件ID列表 -->
    <view>已上传：{{ images.length }} 张图片</view>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const images = ref([])
</script>

视频上传

<template>
  <aura-upload-cloud
    v-model="videos"
    upload-dir="videos"
    file-type="video"
    :max-count="3"
  />
</template>

<script setup>
import { ref } from 'vue'

const videos = ref([])
</script>

音频上传

<template>
  <aura-upload-cloud
    v-model="audios"
    upload-dir="audios"
    file-type="audio"
    :max-count="5"
  />
</template>

<script setup>
import { ref } from 'vue'

const audios = ref([])
</script>

📋 API

Props

准备工作

确保你的项目已满足以下条件：

✅ 已启用 uniCloud 并关联服务空间

✅ 已配置云存储权限

✅ HBuilderX 版本 >= 3.1.0

🚀 快速开始

基础用法

<template>
  <view>
    <!-- 图片上传（网格布局） -->
    <aura-upload-cloud
      v-model="images"
      upload-dir="avatar"
      file-type="image"
      :max-count="9"
      :columns="4"
    />

    <!-- 已上传的文件ID列表 -->
    <view>已上传：{{ images.length }} 张图片</view>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const images = ref([])
</script>

视频上传

<template>
  <aura-upload-cloud
    v-model="videos"
    upload-dir="videos"
    file-type="video"
    :max-count="3"
  />
</template>

<script setup>
import { ref } from 'vue'

const videos = ref([])
</script>

音频上传

<template>
  <aura-upload-cloud
    v-model="audios"
    upload-dir="audios"
    file-type="audio"
    :max-count="5"
  />
</template>

<script setup>
import { ref } from 'vue'

const audios = ref([])
</script>

📋 API

Props

Events

Methods

通过 ref 调用组件方法：

💡 高级用法

自定义删除逻辑

<template>
  <aura-upload-cloud
    v-model="files"
    @remove="handleRemove"
  />
</template>

<script setup>
const handleRemove = async ({ fileID }) => {
  // 调用你自己的云函数删除
    // 云函数实例
<!--    const removeCloudFile = async (fileIDs = []) => {
        if (!Array.isArray(fileIDs) || !fileIDs.length) return null

        return uniCloud.deleteFile({
            fileList: fileIDs
        })
    } -->

  // 云方法
  const res = await uniCloud.callFunction({
    name: 'removeCloudFile',
    data: { fileID }
  })
  // 或云对象
<!--    const contentObjCo = uniCloud.importObject('my-content')
    contentObjCo.removeCloudFile(fileIDs) -->

  if (res.code === 0) {
    uni.showToast({ title: '删除成功' })
  }
}
</script>

上传前校验

<template>
  <aura-upload-cloud
    v-model="files"
    :before-upload="validateFile"
  />
</template>

<script setup>
const validateFile = (file) => {
  // 文件大小校验
  if (file.size > 5 * 1024 * 1024) {
    uni.showToast({ title: '文件不能超过5MB', icon: 'none' })
    return false
  }

  // 文件类型校验
  const ext = file.name.split('.').pop()
  if (!['jpg', 'png', 'jpeg'].includes(ext)) {
    uni.showToast({ title: '只支持 JPG/PNG 格式', icon: 'none' })
    return false
  }

  return true
}
</script>

自定义文件名

<template>
  <aura-upload-cloud
    v-model="files"
    :custom-file-name="generateFileName"
  />
</template>

<script setup>
const generateFileName = (file, ext) => {
  // 返回自定义的文件名
  const timestamp = Date.now()
  const userId = uni.getStorageSync('userId')
  return \`${userId}/${timestamp}.${ext}\`
}
</script>

手动上传控制

<template>
  <view>
    <aura-upload-cloud
      ref="uploadRef"
      v-model="files"
      :auto-upload="false"
    />
    <button @click="handleUpload">开始上传</button>
    <button @click="handleClear">清空所有</button>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const uploadRef = ref(null)
const files = ref([])

const handleUpload = () => {
  uploadRef.value?.uploadWaitingFiles()
}

const handleClear = () => {
  uploadRef.value?.clearAll()
}
</script>

🔧 注意事项

• uniCloud 配置
  确保项目已关联 uniCloud 服务空间，云存储需要开通并配置权限。
• 小程序配置
  需要在后台配置 uploadFile 合法域名，开发者工具中关闭「不校验合法域名」选项。
• H5 配置
  需要在 uniCloud Web 控制台配置安全域名，跨域问题请检查服务端配置。

📝 更新日志

v1.0.0 (2026-06-07)

• ✨ 初始版本发布
• 🎉 支持图片、视频、音频上传
• 🎨 支持网格/列表双布局
• 📱 支持多平台（App、H5、小程序）
• 🔄 支持上传进度显示
• 🖼️ 支持图片/视频预览
• 🎵 支持音频在线播放
• 🔁 支持失败重试
• 🗑️ 支持删除回调