FaUploadImages 多图上传

多图上传，默认启用多文件模式，支持数量限制、预览列表、删除和 string[] | null 模型；清空后的模型值为 []。在手动上传模式下，选择文件时会立即校验文件类型和大小。拖拽与非拖拽使用一致的新增图片卡片布局；图片卡片尺寸和边框颜色沿用 Element Plus 默认值，调用方可通过对应 CSS Variables 自定义。

上传后的 URL 数组通过 v-model 获取，onChange(uploadFile, uploadFiles) 保持 Element Plus 原生文件状态回调。

多图上传、数量限制、预览与删除

查看代码

Vue

<template>
	<FaUploadImages v-model="images" :upload-api="uploadApi" :limit="5" />
</template>

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

const createImage = (text: string, color: string): string =>
	`data:image/svg+xml;charset=UTF-8,${encodeURIComponent(
		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 200"><rect width="320" height="200" rx="18" fill="${color}"/><text x="160" y="115" text-anchor="middle" font-size="38" fill="white">${text}</text></svg>`
	)}`;
const images = ref<string[] | null>([createImage("图 1", "#67c23a"), createImage("图 2", "#e6a23c")]);
const uploadApi = (formData: FormData): Promise<string> => {
	const file = formData.get("file");
	if (!(file instanceof File)) return Promise.reject(new TypeError("未找到上传图片"));
	try {
		return Promise.resolve(URL.createObjectURL(file));
	} catch (error) {
		return Promise.reject(error);
	}
};
</script>

FaUploadImages 完整 API

Props 属性 (31)

Fast 与 Element Plus 2.14.6 的属性已合并展示；Fast 修改项优先排列，未透传的原生属性保留用于兼容性核对。

属性	来源	说明	类型	默认值
method	Fast 修改	上传 HTTP 方法。	String	FastpostELpost
multiple	Fast 修改	是否允许多选。	Boolean	FasttrueELfalse
accept	Fast 修改	允许选择的文件类型，格式与原生 input accept 属性一致。	String	Fast运行时生成EL""
fileList	Fast 修改	上传文件列表的双向绑定值。	Array	Fast[]EL[]
listType	Fast 修改	上传文件列表样式。	String	Fastpicture-cardELtext
httpRequest	Fast 修改	自定义上传请求实现，优先级最高。	Function	Fast—EL—
limit	Fast 修改	允许上传或选择的最大数量。	Number	Fast9EL—
beforeUpload	Fast 修改	上传前的校验回调。	Function	Fast—EL—
modelValue	Fast 新增	v-model 绑定值。	Array	—
maxSize	Fast 新增	文件大小上限，单位 KB。	String / Number	2048
uploadApi	Fast 新增	Fast 上传函数。	Function	—
uploadUrl	Fast 新增	Fast 内置上传请求地址。	String	—
action	EL 原生	上传请求地址。	String	#
headers	EL 原生	上传请求头。	Object	—
data	EL 原生	组件数据。	Object / Function / Promise	—
name	EL 原生	图标名称、CSS 类名或外部 SVG 地址。	String	file
drag	EL 原生	whether to activate drag and drop mode.	Boolean	false
withCredentials	EL 原生	whether cookies are sent.	Boolean	false
showFileList	EL 原生	是否显示文件列表。	Boolean	true
autoUpload	EL 原生	选择文件后是否立即上传。	Boolean	true
disabled	EL 原生	是否禁用组件或当前选项。	Boolean	false
directory	EL 原生	whether to support uploading directory. After enabling it, only folders can be selected, and after selecting a folder, the files within the folder will be flattened.	Boolean	false
beforeRemove	EL 原生	移除上传文件前的回调。	Function	—
onRemove	EL 原生	hook function when files are removed.	Function	—
onChange	EL 原生	hook function when select file or upload file success or upload file fail.	Function	—
onPreview	EL 原生	hook function when clicking the uploaded files.	Function	—
onSuccess	EL 原生	hook function when uploaded successfully.	Function	—
onProgress	EL 原生	hook function when some progress occurs.	Function	—
onError	EL 原生	hook function when some errors occurs.	Function	—
onExceed	EL 原生	hook function when limit is exceeded.	Function	—
crossorigin	EL 原生	native attribute crossorigin.	String	—

Events 事件（2）

名称	来源	说明	参数 / 类型
update:modelValue	Fast 新增	更新 v-model。	—
update:fileList	Fast 新增	更新上传文件列表。	—

Slots 插槽（4）

名称	来源	说明	参数 / 类型
default	EL 原生	组件默认内容插槽。	—
trigger	EL 原生 · 未透传	content which triggers file dialog.	—
tip	EL 原生 · 未透传	content of tips.	—
file	EL 原生 · 未透传	content of thumbnail template.	{ file: UploadFile, index: number }

Expose 暴露（9）

名称	来源	说明	参数 / 类型
abort	EL 原生	中止指定文件或全部文件的上传请求。	—
submit	EL 原生	手动提交处于 ready 状态的上传文件。	—
clearFiles	EL 原生	清空上传文件列表，可指定文件状态。	—
handleStart	EL 原生	将原始文件加入上传队列。	—
handleRemove	EL 原生	从上传列表移除指定文件。	—
loading	Fast 新增	Fast 业务加载状态。	—
fileList	Fast 新增	当前上传文件列表。	—
preview	Fast 新增	打开指定上传图片的预览。	—
previewList	Fast 新增	当前可预览图片地址列表。	—

FaUploadImages 实例方法

abort 取消

取消上传请求

签名

abort(file?: UploadFile): void;

示例

<template>
	<FaUploadImages ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImages } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
componentRef.value?.abort(undefined);
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
file	UploadFile | undefined	否	需要取消或移除的上传文件；省略时取消全部请求。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

submit 上传

手动上传文件列表

签名

submit(): void;

示例

<template>
	<FaUploadImages ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImages } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
componentRef.value?.submit();
</script>

输入

该方法没有输入参数。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

clearFiles 清空文件

清空已上传的文件列表（该方法不支持在 before-upload 中调用）

签名

clearFiles(states?: import("element-plus").UploadStatus[]): void;

示例

<template>
	<FaUploadImages ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImages } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
componentRef.value?.clearFiles(["success"]);
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
states	UploadStatus[] | undefined	否	需要清除的上传状态集合。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

handleStart 加入文件

手动选择文件

签名

handleStart(rawFile: import("element-plus").UploadRawFile): void;

示例

<template>
	<FaUploadImages ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImages } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
const rawFile = Object.assign(new File(["Fast"], "fast.txt", { type: "text/plain" }), { uid: Date.now() });
componentRef.value?.handleStart(rawFile);
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
rawFile	UploadRawFile	是	浏览器选择的原始文件，并带有 Element Plus 上传 uid。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

handleRemove 移除文件

手动移除文件。file 和 rawFile 已被合并。

签名

handleRemove(file: UploadFile | import("element-plus").UploadRawFile): void;

示例

<template>
	<FaUploadImages ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImages } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
const rawFile = Object.assign(new File(["Fast"], "fast.txt", { type: "text/plain" }), { uid: Date.now() });
componentRef.value?.handleRemove(rawFile);
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
file	UploadRawFile | UploadFile	是	需要取消或移除的上传文件；省略时取消全部请求。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。