FaUploadImage 单图上传

单图上传，固定使用单文件模式，支持固定宽高、替换、删除、预览和 string | null 模型。默认关闭拖拽上传；需要拖拽时可显式设置 drag。在手动上传模式下，选择文件时会立即校验文件类型和大小。width、height 只控制图片框尺寸；提示文字使用外层可用宽度并位于图片框下方，不计入 height。加载遮罩只覆盖图片框，边框颜色沿用 Element Plus 主题。

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

单图尺寸、替换与图片预览

查看代码

Vue

<template>
	<FaUploadImage v-model="image" :upload-api="uploadApi" :width="220" :height="140" />
</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 image = ref<string | null>(createImage("封面图", "#409eff"));
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>

FaUploadImage 完整 API

Props 属性 (33)

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

属性	来源	说明	类型	默认值
method	Fast 修改	上传 HTTP 方法。	String	FastpostELpost
showFileList	Fast 修改	是否显示文件列表。	Boolean	FastfalseELtrue
accept	Fast 修改	允许选择的文件类型，格式与原生 input accept 属性一致。	String	Fast运行时生成EL""
fileList	Fast 修改	上传文件列表的双向绑定值。	Array	Fast[]EL[]
listType	Fast 修改	上传文件列表样式。	String	FastpictureELtext
httpRequest	Fast 修改	自定义上传请求实现，优先级最高。	Function	Fast—EL—
limit	Fast 修改	允许上传或选择的最大数量。	Number	Fast—EL—
beforeUpload	Fast 修改	上传前的校验回调。	Function	Fast—EL—
modelValue	Fast 新增	v-model 绑定值。	String	—
maxSize	Fast 新增	文件大小上限，单位 KB。	String / Number	2048
uploadApi	Fast 新增	Fast 上传函数。	Function	—
uploadUrl	Fast 新增	Fast 内置上传请求地址。	String	—
width	Fast 新增	组件宽度。	String / Number	150
height	Fast 新增	组件高度。	String / Number	150
action	EL 原生	上传请求地址。	String	#
headers	EL 原生	上传请求头。	Object	—
data	EL 原生	组件数据。	Object / Function / Promise	—
multiple	EL 原生	是否允许多选。	Boolean	false
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
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 新增	当前可预览图片地址列表。	—

FaUploadImage 实例方法

abort 取消

取消上传请求

签名

abort(file?: UploadFile): void;

示例

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

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

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

输入

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

返回

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

submit 上传

手动上传文件列表

签名

submit(): void;

示例

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

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

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

输入

该方法没有输入参数。

返回

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

clearFiles 清空文件

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

签名

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

示例

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

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

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

输入

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

返回

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

handleStart 加入文件

手动选择文件

签名

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

示例

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

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

const componentRef = ref<InstanceType<typeof FaUploadImage>>();
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>
	<FaUploadImage ref="componentRef" />
</template>

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

const componentRef = ref<InstanceType<typeof FaUploadImage>>();
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	没有返回值。