FastDotNet
导航
仓库

简体中文

English

简体中文

English

Appearance

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 属性 (31)

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

属性来源说明类型默认值
methodFast 修改上传 HTTP 方法。StringFastpostELpost
dragFast 修改whether to activate drag and drop mode.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 原生whether cookies are sent.Booleanfalse
showFileListEL 原生是否显示文件列表。Booleantrue
acceptEL 原生允许选择的文件类型，格式与原生 input accept 属性一致。String""
autoUploadEL 原生选择文件后是否立即上传。Booleantrue
listTypeEL 原生上传文件列表样式。Stringtext
disabledEL 原生是否禁用组件或当前选项。Booleanfalse
directoryEL 原生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.Booleanfalse
beforeRemoveEL 原生移除上传文件前的回调。Function—
onRemoveEL 原生hook function when files are removed.Function—
onChangeEL 原生hook function when select file or upload file success or upload file fail.Function—
onPreviewEL 原生hook function when clicking the uploaded files.Function—
onSuccessEL 原生hook function when uploaded successfully.Function—
onProgressEL 原生hook function when some progress occurs.Function—
onErrorEL 原生hook function when some errors occurs.Function—
onExceedEL 原生hook function when limit is exceeded.Function—
crossoriginEL 原生native attribute crossorigin.String—
Events 事件（2）
名称来源说明参数 / 类型
update:modelValueFast 新增更新 v-model。—
update:fileListFast 新增更新上传文件列表。—
Slots 插槽（4）
名称来源说明参数 / 类型
defaultEL 原生组件默认内容插槽。—
triggerEL 原生自定义打开文件选择器的触发内容。—
tipEL 原生自定义上传提示说明。—
fileEL 原生自定义上传文件条目内容。{ file: UploadFile, index: number }
Expose 暴露（7）
名称来源说明参数 / 类型
abortEL 原生中止指定文件或全部文件的上传请求。—
submitEL 原生手动提交处于 ready 状态的上传文件。—
clearFilesEL 原生清空上传文件列表，可指定文件状态。—
handleStartEL 原生将原始文件加入上传队列。—
handleRemoveEL 原生从上传列表移除指定文件。—
loadingFast 新增Fast 业务加载状态。—
fileListFast 新增当前上传文件列表。—

FaUpload 实例方法 ​

abort 取消 ​

取消上传请求

签名 ​

ts
abort(file?: UploadFile): void;

示例 ​

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>

输入 ​

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

返回 ​

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

submit 上传 ​

手动上传文件列表

签名 ​

ts
submit(): void;

示例 ​

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>

输入 ​

该方法没有输入参数。

返回 ​

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

clearFiles 清空文件 ​

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

签名 ​

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

示例 ​

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>

输入 ​

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

返回 ​

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

handleStart 加入文件 ​

手动选择文件

签名 ​

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

示例 ​

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>

输入 ​

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

返回 ​

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

handleRemove 移除文件 ​

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

签名 ​

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

示例 ​

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>

输入 ​

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

返回 ​

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