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 原生文件状态回调。
单图尺寸、替换与图片预览
可操作示例查看代码
<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
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
method | Fast 修改 | 上传 HTTP 方法。 | String | FastpostELpost |
showFileList | Fast 修改 | 是否显示文件列表。 | Boolean | FastfalseELtrue |
accept | Fast 修改 | 允许选择的文件类型,格式与原生 input accept 属性一致。 | String | Fast运行时生成EL"" |
fileList | Fast 修改 | 上传文件列表的双向绑定值。 | Array | Fast[]EL[] |
listType | Fast 修改 | 上传文件列表样式。 | String | FastpictureELtext |
httpRequest | Fast 修改 | 自定义上传请求实现,优先级最高。 | Function | Fast—EL— |
limit | Fast 修改 | 允许上传或选择的最大数量。 | Number | Fast—EL— |
beforeUpload | Fast 修改 | 上传前的校验回调。 | Function | Fast—EL— |
modelValue | Fast 新增 | v-model 绑定值。 | String | — |
maxSize | Fast 新增 | 文件大小上限,单位 KB。 | String / Number | 2048 |
uploadApi | Fast 新增 | Fast 上传函数。 | Function | — |
uploadUrl | Fast 新增 | Fast 内置上传请求地址。 | String | — |
width | Fast 新增 | 组件宽度。 | String / Number | 150 |
height | Fast 新增 | 组件高度。 | String / Number | 150 |
action | EL 原生 | 上传请求地址。 | String | # |
headers | EL 原生 | 上传请求头。 | Object | — |
data | EL 原生 | 组件数据。 | Object / Function / Promise | — |
multiple | EL 原生 | 是否允许多选。 | Boolean | false |
name | EL 原生 | 图标名称、CSS 类名或外部 SVG 地址。 | String | file |
drag | EL 原生 | 是否启用拖拽上传。 | Boolean | false |
withCredentials | EL 原生 | 跨域上传请求是否携带 Cookie 等凭据。 | Boolean | false |
autoUpload | EL 原生 | 选择文件后是否立即上传。 | Boolean | true |
disabled | EL 原生 | 是否禁用组件或当前选项。 | Boolean | false |
directory | EL 原生 | 是否允许选择文件夹。启用后只能选文件夹,内部文件会展开为文件列表。 | Boolean | false |
beforeRemove | EL 原生 | 移除上传文件前的回调。 | Function | — |
onRemove | EL 原生 | 从文件列表移除文件时执行的回调。 | Function | — |
onChange | EL 原生 | 选择文件、上传成功或上传失败时执行的回调。 | Function | — |
onPreview | EL 原生 | 点击已上传文件时执行的回调。 | Function | — |
onSuccess | EL 原生 | 文件上传成功时执行的回调。 | Function | — |
onProgress | EL 原生 | 文件上传进度变化时执行的回调。 | Function | — |
onError | EL 原生 | 文件上传失败时执行的回调。 | Function | — |
onExceed | EL 原生 | 选择的文件数量超过限制时执行的回调。 | Function | — |
crossorigin | EL 原生 | 预览图片的原生 crossorigin 属性。 | String | — |
Events 事件
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
update:modelValue | Fast 新增 | 更新 v-model。 | — |
update:fileList | Fast 新增 | 更新上传文件列表。 | — |
Slots 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
default | EL 原生 | 组件默认内容插槽。 | — |
trigger | EL 原生 · 未透传 | 自定义打开文件选择器的触发内容。 | — |
tip | EL 原生 · 未透传 | 自定义上传提示说明。 | — |
file | EL 原生 · 未透传 | 自定义上传文件条目内容。 | { file: UploadFile, index: number } |
实例成员
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
abort | EL 原生 | 中止指定文件或全部文件的上传请求。 | — |
submit | EL 原生 | 手动提交处于 ready 状态的上传文件。 | — |
clearFiles | EL 原生 | 清空上传文件列表,可指定文件状态。 | — |
handleStart | EL 原生 | 将原始文件加入上传队列。 | — |
handleRemove | EL 原生 | 从上传列表移除指定文件。 | — |
loading | Fast 新增 | Fast 业务加载状态。 | — |
fileList | Fast 新增 | 当前上传文件列表。 | — |
preview | Fast 新增 | 打开指定上传图片的预览。 | — |
previewList | Fast 新增 | 当前可预览图片地址列表。 | — |
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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
file | UploadFile | undefined | 否 | 需要取消或移除的上传文件;省略时取消全部请求。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
states | UploadStatus[] | undefined | 否 | 需要清除的上传状态集合。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
rawFile | UploadRawFile | 是 | 浏览器选择的原始文件,并带有 Element Plus 上传 uid。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
file | UploadRawFile | UploadFile | 是 | 需要取消或移除的上传文件;省略时取消全部请求。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
