ImageUpload 图片上传

ImageUpload 图片上传 的基础用法、公开 API 与示例。

基础示例

使用 mock API 完成图片上传。

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref } from "vue";
import { ImageUpload } from "@/components/page/images-upload";

const value = ref<Array<{ name: string; url: string }>>([]);
const demoProps = {
  api: async () => ({ url: "/notData.png" }),
  onSuccess: (res: unknown) =>
    typeof res === "object" &&
    res !== null &&
    "url" in res &&
    typeof res.url === "string"
      ? res.url
      : undefined,
};
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <ImageUpload v-model="value" v-bind="demoProps" />
    </div>
  </ClientOnly>
</template>

隐藏源代码

单图上传

限制为单张图片并展示上传状态。

示例使用本地演示数据；上传、校验和提交不会连接业务后端。

<script setup lang="ts">
import { ref } from "vue";
import { ImageUpload } from "@/components/page/images-upload";

const value = ref("/notData.png");
const uploadStatus = ref("空闲");

const mockUpload = async () => ({ url: "/notData.png", name: "demo.png" });
</script>

<template>
  <ClientOnly>
    <div class="demo-surface">
      <ImageUpload
        v-model="value"
        :api="mockUpload"
        :limit="1"
        :drag="false"
        width="180px"
        height="120px"
        @upload-status-change="status => (uploadStatus = status.uploading ? '上传中' : '空闲')"
      />
      <p class="upload-tip">当前状态：{{ uploadStatus }}</p>
    </div>
  </ClientOnly>
</template>

<style scoped>
.upload-tip {
  margin: 12px 0 0;
  color: #667085;
}
</style>

隐藏源代码

引入方式

import { ImageUpload } from "@/components/page/images-upload";

Props

参数	说明	类型	默认值	必填
api	上传图片的 api 方法，一般项目上传都是同一个 api 方法，在组件里直接引入即可，非必传	UploadApi	-	否
onSuccess	图片上传响应转换，等待异步返回后解析字符串或带 url 的对象，空结果沿用原响应	UploadSuccessHandler	-	否
drag	是否支持拖拽上传，默认为 true	boolean	true	否
disabled	是否禁用上传组件，默认为 false	boolean	false	否
fileSize	图片大小限制，默认为 5M	number	5	否
fileType	图片类型限制，默认为 ["image/jpeg", "image/png", "image/gif"]	FileTypes[]	["image/jpeg", "image/png", "image/gif"]	否
height	组件高度，默认为 150px	string	"150px"	否
width	组件宽度，默认为 150px	string	"150px"	否
borderRadius	组件边框圆角，默认为 8px	string	"8px"	否
limit	最大图片上传数，默认为 5张	number	5	否
modelValue	组件双向绑定值。	string | ImageFileObject[]	-	是

Events

事件名	说明	回调参数
uploadImg	uploadImg 事件触发时回调。	file: File, callback: SuccessFun
checkValidate	checkValidate 事件触发时回调。	-
upload-status-change	上传状态变化事件	status: UploadStatus
update:modelValue	双向绑定值更新时触发。	value: string | ImageFileObject[]

Slots

插槽名	说明	参数
-	该组件未声明 Slots。	-

Expose

名称	说明	类型
getUploadStatus	暴露 getUploadStatus 给外部调用。	() => uploadStatus.value
isUploading	暴露 isUploading 给外部调用。	() => uploadStatus.value.uploading

Module API

名称	说明	类型
ImageUpload	导出 ImageUpload 供业务侧复用。	useInstall(index)

Types

ImageUploadProps

导出 ImageUploadProps 供业务侧复用。

字段	说明	类型	默认值	必填
api	上传图片的 api 方法，一般项目上传都是同一个 api 方法，在组件里直接引入即可，非必传	UploadApi	-	否
onSuccess	图片上传响应转换，等待异步返回后解析字符串或带 url 的对象，空结果沿用原响应	UploadSuccessHandler	-	否
drag	是否支持拖拽上传，默认为 true	boolean	-	否
disabled	是否禁用上传组件，默认为 false	boolean	-	否
fileSize	图片大小限制，默认为 5M	number	-	否
fileType	图片类型限制，默认为 ["image/jpeg", "image/png", "image/gif"]	FileTypes[]	-	否
height	组件高度，默认为 150px	string	-	否
width	组件宽度，默认为 150px	string	-	否
borderRadius	组件边框圆角，默认为 8px	string	-	否
limit	最大图片上传数，默认为 5张	number	-	否

ImageUploadEmits

导出 ImageUploadEmits 供业务侧复用。

字段	说明	类型	默认值	必填
uploadImg	配置 uploadImg。	[file: File, callback: SuccessFun]	-	是
checkValidate	配置 checkValidate。	[]	-	是
upload-status-change	上传状态变化事件	[status: UploadStatus]	-	是

UploadStatus

导出 UploadStatus 供业务侧复用。

字段	说明	类型	默认值	必填
uploading	是否有文件正在上传	boolean	-	是
uploadingCount	正在上传的文件数量	number	-	是

API 根据当前组件源码生成；同步版本与验证记录见维护说明。