跳到正文

FaUploadImage 单图上传 ​

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

自 2.0.28 起可自定义 trigger、tip 和 file 插槽。开启 show-file-list 后,#file 接收 { file, index }。点击内置预览时也会调用 onPreview(file)。

上传后的 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 属性

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

属性来源说明类型默认值
methodFast 修改上传 HTTP 方法。StringFastpostELpost
showFileListFast 修改是否显示文件列表。BooleanFastfalseELtrue
acceptFast 修改允许选择的文件类型,格式与原生 input accept 属性一致。StringFast运行时生成EL""
fileListFast 修改上传文件列表的双向绑定值。ArrayFast[]EL[]
listTypeFast 修改上传文件列表样式。StringFastpictureELtext
httpRequestFast 修改自定义上传请求实现,优先级最高。FunctionFast—EL—
limitFast 修改允许上传或选择的最大数量。NumberFast—EL—
beforeUploadFast 修改上传前的校验回调。FunctionFast—EL—
modelValueFast 新增v-model 绑定值。String—
maxSizeFast 新增文件大小上限,单位 KB。String / Number2048
uploadApiFast 新增Fast 上传函数。Function—
uploadUrlFast 新增Fast 内置上传请求地址。String—
widthFast 新增组件宽度。String / Number150
heightFast 新增组件高度。String / Number150
actionEL 原生上传请求地址。String#
headersEL 原生上传请求头。Object—
dataEL 原生组件数据。Object / Function / Promise—
multipleEL 原生是否允许多选。Booleanfalse
nameEL 原生图标名称、CSS 类名或外部 SVG 地址。Stringfile
dragEL 原生是否启用拖拽上传。Booleanfalse
withCredentialsEL 原生跨域上传请求是否携带 Cookie 等凭据。Booleanfalse
autoUploadEL 原生选择文件后是否立即上传。Booleantrue
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 新增当前上传文件列表。—
previewFast 新增打开指定上传图片的预览。—
previewListFast 新增当前可预览图片地址列表。—

FaUploadImage 实例方法 ​

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

abort 取消 ​

取消上传请求

签名 ​

ts
abort(file?: UploadFile): void;

示例 ​

vue
<template>
	<FaUploadImage ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</button>
</template>

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

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

输入 ​

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

返回 ​

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

submit 上传 ​

手动上传文件列表

签名 ​

ts
submit(): void;

示例 ​

vue
<template>
	<FaUploadImage ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</button>
</template>

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

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

输入: 无参数。

返回: void。

clearFiles 清空文件 ​

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

签名 ​

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

示例 ​

vue
<template>
	<FaUploadImage ref="componentRef" />
	<button type="button" @click="handleExample">调用方法</button>
</template>

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

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

输入 ​

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

返回 ​

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

handleStart 加入文件 ​

手动选择文件

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

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