Skip to content

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.

Mock File

Interactive example
View code
Vue
<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>

Manual Submit

Interactive example
View code
Vue
<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>

Basic

Interactive example
View code
Vue
<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 ​

  1. An explicit Element Plus httpRequest.
  2. Fast uploadApi(formData).
  3. Fast uploadUrl.
  4. 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

EL defaults refer to Element Plus before Fast is imported. 2.14.7

PropertySourceDescriptionTypeDefault
methodFast overrideUpload HTTP method.StringFastpostELpost
dragFast overridewhether to activate drag and drop mode.BooleanFasttrueELfalse
fileListFast overrideTwo-way upload file-list model.ArrayFast[]EL[]
httpRequestFast overrideCustom upload implementation; highest priority.FunctionFast—EL—
limitFast overrideMaximum files to upload or select.NumberFast1EL—
beforeUploadFast overrideValidation callback before upload.FunctionFast—EL—
modelValueFast additionv-model value.String / Array—
maxSizeFast additionMaximum file size in KB.String / Number5120
uploadApiFast additionFast upload function.Function—
uploadUrlFast additionBuilt-in Fast upload URL.String—
actionEL nativeUpload request URL.String#
headersEL nativeUpload request headers.Object—
dataEL nativeComponent data.Object / Function / Promise—
multipleEL nativeAllow multiple selection.Booleanfalse
nameEL nativeIcon name, CSS class, or external SVG URL.Stringfile
withCredentialsEL nativewhether cookies are sent.Booleanfalse
showFileListEL nativeShow file list.Booleantrue
acceptEL nativeAccepted file types, using native input accept syntax.String""
autoUploadEL nativeUpload immediately after file selection.Booleantrue
listTypeEL nativeUpload file-list style.Stringtext
disabledEL nativeDisable the component or current option.Booleanfalse
directoryEL nativewhether 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.Booleanfalse
beforeRemoveEL nativeCallback before removing an uploaded file.Function—
onRemoveEL nativehook function when files are removed.Function—
onChangeEL nativehook function when select file or upload file success or upload file fail.Function—
onPreviewEL nativehook function when clicking the uploaded files.Function—
onSuccessEL nativehook function when uploaded successfully.Function—
onProgressEL nativehook function when some progress occurs.Function—
onErrorEL nativehook function when some errors occurs.Function—
onExceedEL nativehook function when limit is exceeded.Function—
crossoriginEL nativenative attribute crossorigin.String—

Events

NameSourceDescriptionParameters / type
update:modelValueFast additionUpdates v-model.—
update:fileListFast additionUpdates the upload file list.—

Slots

NameSourceDescriptionParameters / type
defaultEL nativeDefault component content.—
triggerEL nativeCustom file-picker trigger.—
tipEL nativeCustom upload hints.—
fileEL nativeCustom upload file-item content.{ file: UploadFile, index: number }

Exposes

NameSourceDescriptionParameters / type
abortEL nativeAborts uploads for one or all files.—
submitEL nativeSubmits upload files in ready state.—
clearFilesEL nativeClears upload files, optionally by status.—
handleStartEL nativeAdds a raw file to the upload queue.—
handleRemoveEL nativeRemoves a file from the upload list.—
loadingFast additionFast business loading state.—
fileListFast additionCurrent upload file list.—

FaUpload instance methods ​

These are call snippets. Use rows, options and fields from your actual data.

abort Abort ​

Aborts upload requests.

Signature ​

ts
abort(file?: UploadFile): void;

Example ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
fileUploadFile | undefinedOptionalUpload file to abort or remove; omit to abort all requests.

Returns ​

ValueTypeDescription
resultvoidNo return value.

submit Submit ​

Manually submits the file list.

Signature ​

ts
submit(): void;

Example ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input: No parameters.

Returns: void.

clearFiles Clear ​

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

Signature ​

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

Example ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
statesUploadStatus[] | undefinedOptionalUpload statuses to clear.

Returns ​

ValueTypeDescription
resultvoidNo return value.

handleStart Queue ​

Manually starts handling a selected file.

Signature ​

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

Example ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</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() });
function handleExample() {
	componentRef.value?.handleStart(rawFile);
}
</script>

Input ​

InputTypeRequired / defaultDescription
rawFileUploadRawFileRequiredBrowser-selected raw file with an Element Plus upload uid.

Returns ​

ValueTypeDescription
resultvoidNo return value.

handleRemove Remove ​

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

Signature ​

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

Example ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</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() });
function handleExample() {
	componentRef.value?.handleRemove(rawFile);
}
</script>

Input ​

InputTypeRequired / defaultDescription
fileUploadRawFile | UploadFileRequiredUpload file to abort or remove; omit to abort all requests.

Returns ​

ValueTypeDescription
resultvoidNo return value.