Uploader 图片上传

介绍

用于将本地的图片上传至服务器，并在上传过程中展示预览图和上传进度。

基础用法

通过 v-model 属性设置图片数据。

<vd-uploader v-model="files" />

const files = ref([
  'http://vital-design.cn/ui/static/exh-1.jpg',
  'http://vital-design.cn/ui/static/exh-2.jpg',
]);

多选上传

通过 multiple 属性开启/关闭多选模式。

<vd-uploader v-model="files" :multiple="true" />

const files = ref([
  'http://vital-design.cn/ui/static/exh-1.jpg',
  'http://vital-design.cn/ui/static/exh-2.jpg',
]);

限制上传数量

通过 limit 属性限制上传数量。

<vd-uploader v-model="files" :limit="3" />

const files = ref([
  'http://vital-design.cn/ui/static/exh-1.jpg',
  'http://vital-design.cn/ui/static/exh-2.jpg',
]);

搭配裁切组件

通过 after-choose 在选图之后、写入列表之前异步处理图片（如裁切、压缩）。入参为 (paths, files)，可返回新的 paths；返回 false 取消本次选择。

下面示例用 showPopup + ImageCropper 逐张裁切。ImageCropper 基于 canvas 导出静态图，GIF 动图裁切后会丢失动画，因此示例用 getFileSuffix 跳过 .gif，直接保留原路径；其它格式进入裁切，取消则跳过该张：

<vd-uploader v-model="files" :after-choose="afterChoose" />

<vd-popup
  name="cropper"
  position="bottom"
  round
  title="裁切图片"
  title-align="center"
  :close-on-click-overlay="false"
>
  <vd-image-cropper
    ref="cropperRef"
    :src="cropper.src"
    height="60vh"
  />

  <vd-button @click="closePopup('cropper')">取消</vd-button>
  <vd-button type="primary" @click="onCropConfirm">完成</vd-button>
</vd-popup>

import type { UploaderAfterChoose, ImageCropperInstance } from 'vital-design';
import { showPopup, closePopup } from 'vital-design';
import { getFileSuffix } from '@vital-design/shared';

const cropperRef = ref<ImageCropperInstance>();

const cropper = reactive({
  src: '',
  path: '',
});

async function onCropConfirm() {
  const path = await cropperRef.value?.crop();

  cropper.path = path || '';
  closePopup('cropper');
}

const afterChoose: UploaderAfterChoose = async (paths) => {
  const next: string[] = [];

  for (const src of paths) {
    const suffix = getFileSuffix(src);

    // GIF 跳过裁切，避免动画丢失
    if (suffix !== 'gif') {
      cropper.src = src;
      cropper.path = '';
      await showPopup({ name: 'cropper' });
    } else {
      cropper.path = src;
    }

    if (!cropper.path) {
      continue;
    }

    next.push(cropper.path);
  }

  return next;
};

上传状态

文件上传完毕后会触发 after-read 回调函数，可获取到对应的 file 对象，通过 status 属性设置上传状态，支持 uploading、deleting、failed、done 状态。

<vd-uploader
  v-model="files"
  :multiple="true"
  :after-read="afterRead"
/>

import { UploaderFileItem } from 'vital-design';
import { timeout, randomId, toArray } from '@vital-design/shared';

const images = [
  'http://vital-design.cn/ui/static/exh-1.jpg',
  'http://vital-design.cn/ui/static/exh-2.jpg',
  'http://vital-design.cn/ui/static/exh-3.jpg',
];

const files = ref<UploaderFileItem[]>([
  { url: images[0], status: 'uploading', message: '上传中...' },
  { url: images[1], status: 'failed', message: '上传失败' },
  { url: images[2] }
]);

const afterRead: UploaderAfterRead = async (files) => {
  files = toArray(files);

  for (const file of files) {
    if (!file.id) {
      file.id = randomId();
    }

    file.status = 'uploading';
    file.percentage = 0;

    // 模拟请求上传
    let rate = 0;
    while (rate < 100) {
      await timeout(300);
      const add = Math.random() * 8;
      rate = Math.min(rate + add, 100);
      file.percentage = rate.toFixed(2);
    }

    file.status = 'done';
    file.percentage = '';
  }
}

允许排序

通过 sortable 属性开启/关闭排序功能。

<vd-uploader v-model="files" :sortable="true" />

const files = ref([
  'http://vital-design.cn/ui/static/exh-1.jpg',
  'http://vital-design.cn/ui/static/exh-2.jpg',
]);

一行展示列数

通过 columns 属性设置一行展示的列数。

<vd-uploader v-model="files" :columns="4" />

const files = ref([
  'http://vital-design.cn/ui/static/exh-1.jpg',
  'http://vital-design.cn/ui/static/exh-2.jpg',
]);

删除状态

通过 before-delete 属性设置删除状态，支持 Promise。

<vd-uploader v-model="files" :before-delete="beforeDelete" />
<vd-dialog name="page" />

const files = ref([
  'http://vital-design.cn/ui/static/exh-1.jpg',
  'http://vital-design.cn/ui/static/exh-2.jpg',
]);

const beforeDelete: UploaderBeforeDelete = async (file, index) => {
  try {
    await showDialog({
      title: '提示',
      message: '是否确认删除?',
      showCancelButton: true,
      name: 'page',
    });

    console.log('确认删除');
    await timeout(1000);
  } catch (error) {
    console.log('取消删除');
    return false;
  }
}

只读状态

通过 readonly 属性设置只读状态。

<vd-uploader v-model="files" readonly />

const files = ref([
  'http://vital-design.cn/ui/static/exh-1.jpg',
  'http://vital-design.cn/ui/static/exh-2.jpg',
]);

API

Props

参数	说明	类型	默认值
v-model	选中值	(string | UploaderFileItem)[]	-
multiple	是否允许多选	boolean	-
limit	最大上传数量	string | number	-
size-type	上传图片尺寸类型	UploaderSizeType[]	['original', 'compressed']
source-type	上传图片源类型	UploaderSourceType[]	['camera', 'album']
crop	图像裁剪参数，设置后 size-type 失效	UploaderCrop	-
preview	是否展示图片预览	boolean	true
preview-name	指定图片预览组件标识名称	string	-
reupload	是否开启覆盖上传	boolean	-
deletable	是否展示删除按钮	boolean	true
disabled	是否禁用	boolean	-
readonly	是否只读	boolean	-
icon	上传区域的图标	IconsName	pic
text	上传区域的文字	string	-
image-mode	图片裁剪、缩放的模式	ImageMode	scaleToFill
before-read	读取文件前的回调函数，支持 Promise	UploaderBeforeRead	-
after-choose	选择图片后的回调函数，支持 Promise；返回新 paths 或 false	UploaderAfterChoose	-
after-read	读取文件后的回调函数	UploaderAfterRead	-
before-delete	删除文件前的回调函数，支持 Promise	UploaderBeforeDelete	-

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Events

事件名	说明	回调参数
click	点击时触发	MouseEvent
update:model-value	文件列表更新时触发	UploaderFileItem[]
click-view	点击视图时触发	UploaderOnClickViewEvent
sort-start	排序开始时触发	UploaderOnSortStartEvent
sort-change	排序改变时触发	UploaderOnSortChangeEvent
sort-end	排序结束时触发	UploaderOnSortEndEvent

Slots

名称	说明
image	图片
trigger	触发按钮

Expose

方法名	说明	参数	返回值
upload	触发上传	index?: number	Promise<void>
reupload	触发重新上传	index: number	-
delete	删除文件	index: number	Promise<void>

类型定义

组件导出以下类型定义：

import type {
  UploaderFileItem,
  UploaderChooseFile,
  UploaderBeforeRead,
  UploaderAfterChoose,
  UploaderAfterRead,
  UploaderBeforeDelete,
  UploaderOnClickViewEvent,
  UploaderOnSortStartEvent,
  UploaderOnSortChangeEvent,
  UploaderOnSortEndEvent,
  UploaderExpose,
  UploaderInstance,
} from 'vital-design';