跳到正文

FaUpload 文件上传 ​

保留 ElUpload 的拖拽、文件列表、手动提交、自定义请求和回调能力,并统一文件类型、大小、数量、模型同步、表单校验和团队提示。拖拽与非拖拽的默认上传框使用一致的边框和提示样式;上传区域不会强制设置宽度或最小高度,可通过调用方样式和插槽控制实际尺寸。边框颜色沿用 Element Plus 主题。

上传后的 URL 通过 v-model 或 update:modelValue 获取;onChange(uploadFile, uploadFiles) 保持 Element Plus 原生文件状态回调,不用于返回 URL。

自动上传会在请求前校验文件类型和大小;手动上传会在选择文件时完成相同校验。通过 URL 初始化文件列表时,文件名取 URL 最后一个路径段,并忽略查询参数和片段。

拖拽上传、类型与大小校验、uploadApi

可操作示例
查看代码
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>

手动提交、清空列表与 Expose

可操作示例
查看代码
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>

禁用状态与基础样式

可操作示例
查看代码
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>

传输优先级 ​

  1. 显式传入的 Element Plus httpRequest。
  2. Fast uploadApi(formData)。
  3. Fast uploadUrl。
  4. 非默认值的原生 action。

Fast 内置传输默认使用 POST。浏览器会为 FormData 自动生成包含 boundary 的 Content-Type,不应手动写死 multipart/form-data。

FaUpload 完整 API

Props 属性

EL 默认值取自导入 Fast 前的 Element Plus。 2.14.7

属性来源说明类型默认值
methodFast 修改上传 HTTP 方法。StringFastpostELpost
dragFast 修改是否启用拖拽上传。BooleanFasttrueELfalse
fileListFast 修改上传文件列表的双向绑定值。ArrayFast[]EL[]
httpRequestFast 修改自定义上传请求实现,优先级最高。FunctionFast—EL—
limitFast 修改允许上传或选择的最大数量。NumberFast1EL—
beforeUploadFast 修改上传前的校验回调。FunctionFast—EL—
modelValueFast 新增v-model 绑定值。String / Array—
maxSizeFast 新增文件大小上限,单位 KB。String / Number5120
uploadApiFast 新增Fast 上传函数。Function—
uploadUrlFast 新增Fast 内置上传请求地址。String—
actionEL 原生上传请求地址。String#
headersEL 原生上传请求头。Object—
dataEL 原生组件数据。Object / Function / Promise—
multipleEL 原生是否允许多选。Booleanfalse
nameEL 原生图标名称、CSS 类名或外部 SVG 地址。Stringfile
withCredentialsEL 原生跨域上传请求是否携带 Cookie 等凭据。Booleanfalse
showFileListEL 原生是否显示文件列表。Booleantrue
acceptEL 原生允许选择的文件类型,格式与原生 input accept 属性一致。String""
autoUploadEL 原生选择文件后是否立即上传。Booleantrue
listTypeEL 原生上传文件列表样式。Stringtext
disabledEL 原生是否禁用组件或当前选项。Booleanfalse
directoryEL 原生是否允许选择文件夹。启用后只能选文件夹,内部文件会展开为文件列表。Booleanfalse
beforeRemoveEL 原生移除上传文件前的回调。Function—
onRemoveEL 原生从文件列表移除文件时执行的回调。Function—
onChangeEL 原生选择文件、上传成功或上传失败时执行的回调。Function—
onPreviewEL 原生点击已上传文件时执行的回调。Function—
onSuccessEL 原生文件上传成功时执行的回调。Function—
onProgressEL 原生文件上传进度变化时执行的回调。Function—
onErrorEL 原生文件上传失败时执行的回调。Function—
onExceedEL 原生选择的文件数量超过限制时执行的回调。Function—
crossoriginEL 原生预览图片的原生 crossorigin 属性。String—

Events 事件

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

Slots 插槽

名称来源说明参数 / 类型
defaultEL 原生组件默认内容插槽。—
triggerEL 原生自定义打开文件选择器的触发内容。—
tipEL 原生自定义上传提示说明。—
fileEL 原生自定义上传文件条目内容。{ file: UploadFile, index: number }

实例成员

名称来源说明参数 / 类型
abortEL 原生中止指定文件或全部文件的上传请求。—
submitEL 原生手动提交处于 ready 状态的上传文件。—
clearFilesEL 原生清空上传文件列表,可指定文件状态。—
handleStartEL 原生将原始文件加入上传队列。—
handleRemoveEL 原生从上传列表移除指定文件。—
loadingFast 新增Fast 业务加载状态。—
fileListFast 新增当前上传文件列表。—

FaUpload 实例方法 ​

以下代码为调用片段。行、选项和字段应对应实际数据。

abort 取消 ​

取消上传请求

签名 ​

ts
abort(file?: UploadFile): void;

示例 ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</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>

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。

submit 上传 ​

手动上传文件列表

签名 ​

ts
submit(): void;

示例 ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</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>

输入: 无参数。

返回: void。

clearFiles 清空文件 ​

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

签名 ​

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

示例 ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</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>

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。

handleStart 加入文件 ​

手动选择文件

签名 ​

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

示例 ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</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>

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。

handleRemove 移除文件 ​

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

签名 ​

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

示例 ​

vue
<template>
	<FaUpload ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</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>

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。