FaUpload

Retains ElUpload drag-and-drop, file lists, manual submission, custom requests and callbacks. Adds consistent type, size and count validation, model synchronization, form validation and messages. Drag and non-drag modes share border and hint styles. The upload area does not force a width or minimum height; use styles and slots to control dimensions. Borders use the Element Plus theme.

Uploaded URLs are returned through v-model / update:modelValue. onChange(uploadFile, uploadFiles) remains the native file-state callback and does not return URLs. Automatic uploads validate type and size before sending; manual uploads validate when selecting a file. Initial file names use the final URL path segment, excluding query and fragment.

View code

<template>
	<ElForm :model="form" label-width="88px" style="max-width: 620px">
		<ElFormItem label="证件照" prop="credentialPhoto" required>
			<div class="demo-stack" style="width: 100%">
				<FaUpload
					v-model="form.credentialPhoto"
					:upload-api="uploadApi"
					accept=".jpg,.jpeg,.png,image/jpeg,image/png"
					:max-size="2048"
					style="width: min(100%, 280px)"
				>
					<template #tip>
						<div class="el-upload__tip">仅允许 JPG/PNG，大小不超过 2 MB；示例使用本地 Object URL，不发送网络请求。</div>
					</template>
				</FaUpload>
				<span class="demo-value">模型值：{{ form.credentialPhoto ?? "尚未上传" }}</span>
			</div>
		</ElFormItem>
	</ElForm>
</template>

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

const form = reactive<{ credentialPhoto: string | null }>({
	credentialPhoto: null,
});
const uploadApi = async (formData: FormData): Promise<string> => {
	await new Promise<void>((resolve) => {
		window.setTimeout(resolve, 500);
	});
	const file = formData.get("file");
	if (!(file instanceof File)) throw new TypeError("未找到上传文件");
	return URL.createObjectURL(file);
};
</script>

View code

<template>
	<div class="demo-stack">
		<FaUpload ref="uploadRef" v-model="fileUrl" :upload-api="uploadApi" :auto-upload="false" :drag="false" show-file-list>
			<ElButton type="primary">选择文件</ElButton>
			<template #tip>选择后通过 Expose 手动提交。</template>
		</FaUpload>
		<div class="demo-row">
			<ElButton type="success" @click="uploadRef?.submit?.()">开始上传</ElButton>
			<ElButton @click="uploadRef?.clearFiles?.()">清空列表</ElButton>
		</div>
	</div>
</template>

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

interface UploadExpose {
	clearFiles?: () => void;
	submit?: () => void;
}

const uploadRef = useTemplateRef<UploadExpose>("uploadRef");
const fileUrl = ref<string | null>(null);
const uploadApi = async (formData: FormData): Promise<string> => {
	await new Promise<void>((resolve) => {
		window.setTimeout(resolve, 350);
	});
	const file = formData.get("file");
	if (!(file instanceof File)) throw new TypeError("未找到上传文件");
	return URL.createObjectURL(file);
};
</script>

View code

<template>
	<div class="demo-row" style="align-items: flex-start">
		<FaUpload v-model="file" disabled>
			<ElButton type="primary" disabled>选择文件</ElButton>
			<template #tip>示例禁用真实上传，请在项目中配置 uploadApi 或 uploadUrl。</template>
		</FaUpload>
		<FaUploadImage v-model="image" disabled :width="180" :height="120" />
	</div>
</template>

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

const file = ref<string | string[] | null>(null);
const image = ref<string | null>(null);
</script>

Transport precedence

An explicit Element Plus httpRequest.
Fast uploadApi(formData).
Fast uploadUrl.
A non-default native action.

Fast transports default to POST. The browser generates the FormData Content-Type with its boundary; do not hardcode multipart/form-data.

FaUpload Complete API

Props (31)

Fast and Element Plus 2.14.6 props are merged below. Fast changes appear first; native props that are not forwarded remain visible for compatibility review.

Property	Source	Description	Type	Default
`method`	Fast override	Upload HTTP method.	`String`	Fast`post`EL`post`
`drag`	Fast override	whether to activate drag and drop mode.	`Boolean`	Fast`true`EL`false`
`fileList`	Fast override	Two-way upload file-list model.	`Array`	Fast`[]`EL`[]`
`httpRequest`	Fast override	Custom upload implementation; highest priority.	`Function`	Fast`—`EL`—`
`limit`	Fast override	Maximum files to upload or select.	`Number`	Fast`1`EL`—`
`beforeUpload`	Fast override	Validation callback before upload.	`Function`	Fast`—`EL`—`
`modelValue`	Fast addition	v-model value.	`String / Array`	`—`
`maxSize`	Fast addition	Maximum file size in KB.	`String / Number`	`5120`
`uploadApi`	Fast addition	Fast upload function.	`Function`	`—`
`uploadUrl`	Fast addition	Built-in Fast upload URL.	`String`	`—`
`action`	EL native	Upload request URL.	`String`	`#`
`headers`	EL native	Upload request headers.	`Object`	`—`
`data`	EL native	Component data.	`Object / Function / Promise`	`—`
`multiple`	EL native	Allow multiple selection.	`Boolean`	`false`
`name`	EL native	Icon name, CSS class, or external SVG URL.	`String`	`file`
`withCredentials`	EL native	whether cookies are sent.	`Boolean`	`false`
`showFileList`	EL native	Show file list.	`Boolean`	`true`
`accept`	EL native	Accepted file types, using native input accept syntax.	`String`	`""`
`autoUpload`	EL native	Upload immediately after file selection.	`Boolean`	`true`
`listType`	EL native	Upload file-list style.	`String`	`text`
`disabled`	EL native	Disable the component or current option.	`Boolean`	`false`
`directory`	EL native	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 native	Callback before removing an uploaded file.	`Function`	`—`
`onRemove`	EL native	hook function when files are removed.	`Function`	`—`
`onChange`	EL native	hook function when select file or upload file success or upload file fail.	`Function`	`—`
`onPreview`	EL native	hook function when clicking the uploaded files.	`Function`	`—`
`onSuccess`	EL native	hook function when uploaded successfully.	`Function`	`—`
`onProgress`	EL native	hook function when some progress occurs.	`Function`	`—`
`onError`	EL native	hook function when some errors occurs.	`Function`	`—`
`onExceed`	EL native	hook function when limit is exceeded.	`Function`	`—`
`crossorigin`	EL native	native attribute crossorigin.	`String`	`—`

Events（2）

Name	Source	Description	Parameters / type
`update:modelValue`	Fast addition	Updates v-model.	`—`
`update:fileList`	Fast addition	Updates the upload file list.	`—`

Slots（4）

Name	Source	Description	Parameters / type
`default`	EL native	Default component content.	`—`
`trigger`	EL native	Custom file-picker trigger.	`—`
`tip`	EL native	Custom upload hints.	`—`
`file`	EL native	Custom upload file-item content.	`{ file: UploadFile, index: number }`

Expose（7）

Name	Source	Description	Parameters / type
`abort`	EL native	Aborts uploads for one or all files.	`—`
`submit`	EL native	Submits upload files in ready state.	`—`
`clearFiles`	EL native	Clears upload files, optionally by status.	`—`
`handleStart`	EL native	Adds a raw file to the upload queue.	`—`
`handleRemove`	EL native	Removes a file from the upload list.	`—`
`loading`	Fast addition	Fast business loading state.	`—`
`fileList`	Fast addition	Current upload file list.	`—`

FaUpload instance methods

`abort` Abort

Aborts upload requests.

Signature

abort(file?: UploadFile): void;

Example

vue

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

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

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

Input

Input	Type	Required / default	Description
`file`	`UploadFile \| undefined`	Optional	Upload file to abort or remove; omit to abort all requests.

Returns

Value	Type	Description
`result`	`void`	No return value.

`submit` Submit

Manually submits the file list.

Signature

submit(): void;

Example

vue

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

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

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

Input

This method has no input parameters.

Returns

Value	Type	Description
`result`	`void`	No return value.

`clearFiles` Clear

Clears the uploaded-file list; do not call inside before-upload.

Signature

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

Example

vue

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

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

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

Input

Input	Type	Required / default	Description
`states`	`UploadStatus[] \| undefined`	Optional	Upload statuses to clear.

Returns

Value	Type	Description
`result`	`void`	No return value.

`handleStart` Queue

Manually starts handling a selected file.

Signature

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

Example

vue

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

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

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

Input

Input	Type	Required / default	Description
`rawFile`	`UploadRawFile`	Required	Browser-selected raw file with an Element Plus upload uid.

Returns

Value	Type	Description
`result`	`void`	No return value.

`handleRemove` Remove

Manually removes a file; file and rawFile have been merged.

Signature

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

Example

vue

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

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

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

Input

Input	Type	Required / default	Description
`file`	`UploadRawFile \| UploadFile`	Required	Upload file to abort or remove; omit to abort all requests.

Returns

Value	Type	Description
`result`	`void`	No return value.

FaUpload

Mock File

Manual Submit

Basic

Transport precedence

FaUpload Complete API

FaUpload instance methods

`abort` Abort

Signature

Example

Input

Returns

`submit` Submit

Signature

Example

Input

Returns

`clearFiles` Clear

Signature

Example

Input

Returns

`handleStart` Queue

Signature

Example

Input

Returns

`handleRemove` Remove

Signature

Example

Input

Returns

FaUpload ​

Transport precedence ​

FaUpload Complete API

FaUpload instance methods ​

abort Abort ​

Signature ​

Example ​

Input ​

Returns ​

submit Submit ​

Signature ​

Example ​

Input ​

Returns ​

clearFiles Clear ​

Signature ​

Example ​

Input ​

Returns ​

handleStart Queue ​

Signature ​

Example ​

Input ​

Returns ​

handleRemove Remove ​

Signature ​

Example ​

Input ​

Returns ​

FaUpload

Transport precedence

FaUpload instance methods

`abort` Abort

Signature

Example

Input

Returns

`submit` Submit

Signature

Example

Input

Returns

`clearFiles` Clear

Signature

Example

Input

Returns

`handleStart` Queue

Signature

Example

Input

Returns

`handleRemove` Remove

Signature

Example

Input

Returns