Upload 上传

基于 Element Plus el-upload 的二次封装，支持多种列表展示模式、文件预览、懒加载预览、删除回调等业务场景。

懒加载预览

上传接口只返回 id，通过 previewUrl 按需获取预览 URL，删除时调用 deleteUrl 删除服务端文件。

支持 .jpg,.png,.gif,.pdf,.doc,.docx,.mp4 格式，最多 10 个文件

<template>
  <HxUpload
    v-model="fileIds"
    action="/api/upload"
    :accept="accept"
    :limit="10"
    :multiple="true"
    :response-mapper="(res) => res.data.id"
    :preview-url="'/api/upload/preview'"
    :delete-url="'/api/upload'"
    :show-download="true"
    list-type="file-preview"
    placeholder="上传附件"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { HxUpload } from '@whhx/ui'

const fileIds = ref<string[]>([])
const accept = '.jpg,.png,.gif,.pdf,.doc,.docx,.mp4'
</script>

modelValueType - 值类型切换

通过 modelValueType 控制 v-model emit 的值类型：array 发送数组（默认），string 发送逗号分隔字符串。

modelValueType="array"（默认）

v-model 绑定为数组，响应式更新

支持 .jpg,.png,.gif,.pdf,.doc,.docx,.mp4 格式，最多 5 个文件

v-model (fileIds): []

modelValueType="string"

v-model 绑定为逗号分隔字符串，适用于后端接口直接接收字符串场景

支持 .jpg,.png,.gif,.pdf,.doc,.docx,.mp4 格式，最多 5 个文件

v-model (fileIdsStr):

<template>
  <div class="hx-upload-model-value-type-demo">
    <!-- array 模式（默认） -->
    <div class="demo-block">
      <h4 class="demo-sub-title">modelValueType="array"（默认）</h4>
      <p class="demo-desc">v-model 绑定为数组，响应式更新</p>
      <HxUpload
        v-model="fileIds"
        action="/api/upload"
        :accept="accept"
        :limit="5"
        :multiple="true"
        :response-mapper="(res) => res.data.id"
        :preview-url="'/api/upload/preview'"
        :delete-url="'/api/upload'"
        list-type="file-preview"
        placeholder="上传附件"
      />
      <div class="demo-code">v-model (fileIds): {{ fileIds }}</div>
    </div>

    <!-- string 模式 -->
    <div class="demo-block">
      <h4 class="demo-sub-title">modelValueType="string"</h4>
      <p class="demo-desc">v-model 绑定为逗号分隔字符串，适用于后端接口直接接收字符串场景</p>
      <HxUpload
        v-model="fileIdsStr"
        action="/api/upload"
        :accept="accept"
        :limit="5"
        :multiple="true"
        :response-mapper="(res) => res.data.id"
        :preview-url="'/api/upload/preview'"
        :delete-url="'/api/upload'"
        model-value-type="string"
        list-type="file-preview"
        placeholder="上传附件"
      />
      <div class="demo-code">v-model (fileIdsStr): {{ fileIdsStr }}</div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { HxUpload } from '@whhx/ui'

const fileIds = ref<string[]>([])
const fileIdsStr = ref<string>('')
const accept = '.jpg,.png,.gif,.pdf,.doc,.docx,.mp4'
</script>

<style scoped>
.demo-block {
	background: var(--el-bg-color);
	border: 1px solid var(--el-border-color);
	border-radius: 8px;
	padding: 20px;
	margin-bottom: 16px;
}

.demo-sub-title {
	font-size: 15px;
	font-weight: 600;
	color: var(--el-text-color-primary);
	margin: 0 0 8px;
}

.demo-desc {
	font-size: 13px;
	color: var(--el-text-color-regular);
	margin: 0 0 12px;
}

.demo-code {
	background: var(--el-fill-color-lightest);
	padding: 12px 16px;
	border-radius: 6px;
	font-size: 13px;
	color: var(--el-text-color-regular);
	word-break: break-all;
	margin-top: 12px;
}
</style>

API

Props

参数名	说明	类型	默认值
v-model	上传文件后绑定到表单的值	string | string[]	-
modelValueType	v-model emit 的值类型：array 发送数组，string 发送逗号分隔字符串	'string' | 'array'	'array'
action	上传地址	string	-
accept	接受的文件类型	string	-
limit	最大上传数量	number	-
multiple	是否支持多文件	boolean	-
disabled	是否禁用	boolean	-
listType	列表展示类型：text / picture / picture-card / file-preview	string	'file-preview'
autoUpload	是否自动上传（无 action 时关闭）	boolean	true
placeholder	上传按钮占位文本	string	-
responseMapper	从服务端响应中提取要存储的值（如 fileId）	(response, file) => any	-
valueMapper	从 file 对象提取值的映射函数	(file, response?) => any	-
previewUrl	根据 fileId 获取文件预览信息的接口（listType=file-preview 时使用）	string	-
deleteUrl	根据 fileId 删除文件的接口（file-preview 模式）	string	-
showDownload	是否显示下载按钮（file-preview 模式）	boolean	true
removable	是否显示删除按钮（file-preview 模式）	boolean	-
removeConfirmTitle	删除确认框标题（file-preview 模式）	string	-
removeConfirmMessage	删除确认框内容（file-preview 模式）	string	-
itemWidth	卡片宽度（file-preview 模式）	string | number	-
itemHeight	卡片高度（file-preview 模式）	string | number	-
fileRender	自定义文件列表项渲染	(file, actions) => VNode	-
filePreviewRender	自定义文件预览渲染	(file, actions) => VNode	-
componentProps	额外的 el-upload props	Record<string, any>	-

Slots

插槽名	说明	作用域变量
default	默认插槽，渲染上传触发器	-
file	自定义文件列表项（listType 非 file-preview 时生效）	{ file, remove }
tip	提示信息区域	-

事件

事件名	说明	参数
success	上传成功时触发	(response, file, fileList) => void
update:modelValue	文件列表变化时触发（file-preview 模式）	(value: string | string[])