FileUpload 文件上传

点击 / 拖拽 / 粘贴选文件；业务在 on-change 中自行上传云端；支持 oss-base 远程回显。

基础用法

本地维护文件列表，组件不负责云端上传。

<script setup lang="ts">
import { ref } from 'vue'
import { RdFileUpload, type UploadFileItem } from '@rd-element/ui'

const files = ref<UploadFileItem[]>([])
</script>

<template>
  <RdFileUpload v-model="files" hint="支持拖拽、粘贴，最多 5 个文件" />
</template>

云端上传钩子

添加文件后 status 为 ready，组件触发 change 事件；业务上传完成后回写 success / fail 与 url（状态变化会再次触发 change）。旧版 on-change prop 仍可用，但已标记为 deprecated，下一主版本移除，建议迁移到 change 事件。

<script setup lang="ts">
import { ref } from 'vue'
import { RdFileUpload, type UploadFile } from '@rd-element/ui'

const files = ref<UploadFile[]>([])

async function handleUploadChange(file: UploadFile, fileList: UploadFile[]) {
  if (file.status !== 'ready' || !file.file) return
  file.status = 'uploading'
  files.value = [...fileList]
  try {
    // 业务自行上传 OSS，此处 mock
    await new Promise((r) => setTimeout(r, 600))
    file.status = 'success'
    file.url = 'https://example.com/mock/' + encodeURIComponent(file.name)
    file.fileUrl = '//crm-test/mock/' + encodeURIComponent(file.name)
  } catch {
    file.status = 'fail'
  }
  files.value = [...files.value]
}
</script>

<template>
  <RdFileUpload
    v-model="files"
    :on-change="handleUploadChange"
    hint="选文件后走 on-change 自行上传"
  />
</template>

远程回显

无本地 File 时，用 fileUrl / url + oss-base 拼展示地址；已是 http(s):// 全链接则不再拼接。

• 微信图片_20260327145152_105_2.jpg106.5 KB · 点击缩略图预览
• 已是全链接示例.png2.0 KB · 点击缩略图预览

<script setup lang="ts">
import { ref } from 'vue'
import { RdFileUpload, type UploadFileItem } from '@rd-element/ui'

const OSS_BASE = 'https://sz-dev-crm.oss-cn-shenzhen.aliyuncs.com'

const files = ref<UploadFileItem[]>([
  {
    uid: '0a0eab5c94d68b9fe49e9e2dbf01f3c6b39d91f4',
    name: '微信图片_20260327145152_105_2.jpg',
    size: 109006,
    type: 'image/jpeg',
    status: 'success',
    fileUrl: '//crm-test/2026/07/20/0a0eab5c94d68b9fe49e9e2dbf01f3c6b39d91f4.jpg',
    fileName: '微信图片_20260327145152_105_2.jpg',
    fileSha1: '0a0eab5c94d68b9fe49e9e2dbf01f3c6b39d91f4',
    fileSize: '109006',
    fileSuffix: 'jpg',
  },
])
</script>

<template>
  <RdFileUpload v-model="files" :oss-base="OSS_BASE" :max-count="10" />
</template>

自定义上传和文件列表插槽

upload 和 file-list 两个作用域插槽分别接管上传入口与文件列表。组件会把文件数据、状态和常用交互方法作为作用域参数传入；未传入任一插槽时仍使用对应的内置 UI。隐藏的文件选择 input 仍由组件维护，业务按钮调用 open() 即可打开选择器。

下面的示例用 change 模拟业务上传：选中文件后先显示“上传中”和进度，700ms 后回写为“已上传”；实际项目中将这段 mock 逻辑替换为自己的上传 API 即可。

上传合同附件支持 PDF、Word、Excel 和图片，单个文件不超过 10 MB

选择文件后，附件会显示在这里

<script setup lang="ts">
import { ref } from 'vue'
import { FileText, Trash2, UploadCloud } from '@lucide/vue'
import { RdFileUpload, type UploadFileItem } from '@rd-element/ui'

const files = ref<UploadFileItem[]>([])

function statusText(status: UploadFileItem['status']) {
  if (status === 'uploading') return '上传中'
  if (status === 'success') return '已上传'
  if (status === 'fail') return '上传失败'
  return '待上传'
}

function statusType(status: UploadFileItem['status']) {
  if (status === 'success') return 'success'
  if (status === 'fail') return 'danger'
  if (status === 'uploading') return 'warning'
  return 'info'
}

function handleChange(fileList: UploadFileItem[]) {
  const pending = fileList.filter((file) => file.status === 'ready' && file.file)
  if (!pending.length) return

  pending.forEach((file) => {
    file.status = 'uploading'
    file.percent = 35
  })
  files.value = [...fileList]

  window.setTimeout(() => {
    pending.forEach((file) => {
      file.status = 'success'
      file.percent = 100
    })
    files.value = [...files.value]
  }, 700)
}
</script>

<template>
  <RdFileUpload v-model="files" :max-count="3" @change="handleChange">
    <template #upload="{ canSelect, open, dragOver }">
      <div class="upload-entry" :class="{ 'is-dragover': dragOver }">
        <UploadCloud :size="20" />
        <span>
          <strong>{{ dragOver ? '松开鼠标即可上传' : '上传合同附件' }}</strong>
          <small>支持 PDF、Word、Excel 和图片，单个文件不超过 10 MB</small>
        </span>
        <el-button type="primary" :disabled="!canSelect" @click="open">选择文件</el-button>
      </div>
    </template>
    <template #file-list="{ files, remove, displayName, displaySize, getPreviewUrl, isImageFile }">
      <p v-if="!files.length" class="empty-hint">选择文件后，附件会显示在这里</p>
      <ul v-else class="file-list">
        <li v-for="file in files" :key="file.uid" class="file-list__item">
          <el-image
            v-if="isImageFile(file) && getPreviewUrl(file)"
            :src="getPreviewUrl(file)"
            :preview-src-list="[getPreviewUrl(file)]"
            fit="cover"
            preview-teleported
          />
          <FileText v-else :size="18" />
          <span class="file-list__main">
            <strong>{{ displayName(file) }}</strong>
            <span>{{ displaySize(file) }} <el-tag size="small" :type="statusType(file.status)">{{ statusText(file.status) }}</el-tag></span>
            <el-progress v-if="file.status === 'uploading'" :percentage="file.percent ?? 0" :show-text="false" />
          </span>
          <el-button text type="danger" aria-label="删除文件" @click="remove(file.uid)">
            <Trash2 :size="15" />
          </el-button>
        </li>
      </ul>
    </template>
  </RdFileUpload>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { FileText, Trash2, UploadCloud } from '@lucide/vue'
import { RdFileUpload, type UploadFileItem } from '@rd-element/ui'

const files = ref<UploadFileItem[]>([])

function statusText(status: UploadFileItem['status']) {
  if (status === 'uploading') return '上传中'
  if (status === 'success') return '已上传'
  if (status === 'fail') return '上传失败'
  return '待上传'
}

function statusType(status: UploadFileItem['status']) {
  if (status === 'success') return 'success'
  if (status === 'fail') return 'danger'
  if (status === 'uploading') return 'warning'
  return 'info'
}
</script>

<template>
  <RdFileUpload v-model="files">
    <template #upload="{ canSelect, open, dragOver }">
      <div class="upload-entry" :class="{ 'is-dragover': dragOver }">
        <UploadCloud :size="20" />
        <span>
          <strong>{{ dragOver ? '松开鼠标即可上传' : '上传合同附件' }}</strong>
          <small>支持 PDF、Word、Excel 和图片，单个文件不超过 10 MB</small>
        </span>
        <el-button type="primary" :disabled="!canSelect" @click="open">选择文件</el-button>
      </div>
    </template>
    <template #file-list="{ files, remove, displayName, displaySize, getPreviewUrl, isImageFile }">
      <p v-if="!files.length" class="empty-hint">选择文件后，附件会显示在这里</p>
      <ul v-else class="file-list">
        <li v-for="file in files" :key="file.uid" class="file-list__item">
          <el-image
            v-if="isImageFile(file) && getPreviewUrl(file)"
            :src="getPreviewUrl(file)"
            :preview-src-list="[getPreviewUrl(file)]"
            fit="cover"
            preview-teleported
          />
          <FileText v-else :size="18" />
          <span class="file-list__main">
            <strong>{{ displayName(file) }}</strong>
            <span>{{ displaySize(file) }} <el-tag size="small" :type="statusType(file.status)">{{ statusText(file.status) }}</el-tag></span>
            <el-progress v-if="file.status === 'uploading'" :percentage="file.percent ?? 0" :show-text="false" />
          </span>
          <el-button text type="danger" aria-label="删除文件" @click="remove(file.uid)">
            <Trash2 :size="15" />
          </el-button>
        </li>
      </ul>
    </template>
  </RdFileUpload>
</template>

两个插槽的作用域参数类型均为导出的 RdFileUploadSlotProps。

API

Attributes

属性名	说明	类型	默认值
v-model	文件列表（UploadFileItem[]）	UploadFileItem[]	[]
accept	accept 属性	string	常见文档/图片
multiple	多文件	boolean	true
maxCount	最大文件数	number	5
maxSizeMb	单文件大小上限 MB	number	10
hint	底部提示文案	string	自动生成
onChange	文件状态钩子：添加（ready）、变为 success / fail 时调用；业务在此上传云端并回写 status / url	(file, files) => void	—
ossBase	OSS 域名或前缀；fileUrl/url 已是 http(s) 全链接时不再拼接	string	''

Events

事件名	说明	类型
update:modelValue	文件列表变更	(files: UploadFileItem[]) => void
change	文件列表整表变更	(files: UploadFileItem[]) => void

Slots

插槽名	说明
upload	接管上传入口、图标和提示；未提供时使用内置 fallback。参数类型为 RdFileUploadSlotProps。
file-list	接管文件列表、预览和操作按钮；未提供时使用内置 fallback。参数类型为 RdFileUploadSlotProps。

UploadFileItem

字段	说明	类型
uid	唯一键	string
name / size / type	展示用元数据	string / number / string
file	本地新选才有；纯回显可无	File?
status	ready | uploading | success | fail	string?
url	完整可访问地址	string?
fileUrl	相对或绝对 path	string?
fileName / fileSha1 / fileSize / fileSuffix	远程透传字段	可选
percent / response	进度与原始响应	可选

类型别名：UploadFile、UploadFiles。