Upload 文件上传

使用指南

用于上传文件。

代码演示

查看代码

<template>
  <div class="list">
    <p>基本使用</p>
    <h3-upload
      v-model="data"
      :action="action"
      accept="image/*"
      multiple
      @fileClick="showImageViewer"
    />
    <p>定制化</p>
    <h3-upload v-model="data" :action="action">
      <template #list="{files, removeFile}">
        <div
          v-for="file in files"
          :key="file.uid"
          class="custom-item"
          @click="showImageViewer(file, files)"
        >
          <div
            :style="{
              backgroundImage: `url(${file.category === 'image' ? file.base64 || file.url : file.categoryIcon})`,
            }"
            class="custom-item__icon"
          ></div>
          <div class="custom-item__content">
            <span class="custom-item__content-name">{{ file.name }}</span>
            <span class="custom-item__content-size">{{ (file.size / 1024).toFixed(2) }}kb</span>
          </div>
          <h3-icon type="delete-o" size="20" @click.stop="removeFile(file)" />
          <div
            v-if="file.status === 'uploading'"
            :style="{width: `${file.progress}%`}"
            class="custom-item__progress"
          ></div>
        </div>
      </template>
      <div class="custom-item__btn">
        上传附件
      </div>
    </h3-upload>
    <p>上传数量: 5</p>
    <h3-upload
      :action="action"
      :limit="5"
      accept="image/*"
      multiple
      @fileClick="showImageViewer"
      @exceed="exceed"
    />
    <p>上传格式: png</p>
    <h3-upload
      :action="action"
      :format="['png']"
      accept="image/*"
      multiple
      @fileClick="showImageViewer"
      @mismatch="mismatch"
    />
    <p>上传格式: 函数</p>
    <h3-upload
      :action="action"
      :format="
        (file) => {
          const ext = file.name.split('.').pop().toLocaleLowerCase();
          return ext === 'png';
        }
      "
      accept="image/*"
      multiple
      @fileClick="showImageViewer"
      @mismatch="mismatch"
    />
    <p>上传大小: 1024KB</p>
    <h3-upload
      :action="action"
      :maxSize="1024 * 1024"
      accept="image/*"
      multiple
      @fileClick="showImageViewer"
      @oversize="oversize"
    />
    <p>自主控制</p>
    <h3-upload
      ref="upload"
      :action="action"
      :auto="false"
      multiple
      accept="image/*"
      @fileClick="showImageViewer"
    />
    <br />
    <div>
      <h3-button
        inline
        type="primary"
        style="margin: 10px 10px;"
        @click="start"
      >
        上传
      </h3-button>
      <h3-button
        inline
        type="primary"
        style="margin: 10px 10px;"
        @click="pause"
      >
        停止
      </h3-button>
      <h3-button
        inline
        style="margin: 10px 10px;"
        type="primary"
        @click="retry"
      >
        失败再次尝试
      </h3-button>
    </div>
  </div>
</template>

<script>
import H3Upload from '@/components/h3-upload/';
import H3Button from '@/components/h3-button/';
import H3Icon from '@/components/h3-icon';
export default {
  name: 'UploadDemo',
  components: {
    H3Upload,
    H3Button,
    H3Icon,
  },
  data () {
    return {
      data: [
        {
          name: '头像.png',
          category: 'image',
          url: 'https://picsum.photos/id/61/400/300',
          size: 1024 * 512,
        },
        // {
        //   name: '头像.png',
        //   category: 'image',
        //   url: 'https://i.loli.net/2020/04/15/OoNUklVKqeicTfR.jpg',
        //   size: 1024 * 1024,
        // },
        // {
        //   name: '头像.png',
        //   category: 'image',
        //   url: 'https://i.loli.net/2020/04/15/4NQGM6wfBuJRrSp.jpg',
        //   size: 1024 * 1024,
        // },
      ],
      action: {
        target: 'https://api.imgbb.com/1/upload',
        fileName: 'image',
        data: {
          key: '4ea73a7601146bc20bd21f565a5d6c3f',
        },
      },
      format: ['png'],
    };
  },
  beforeDestroy () {
    this.$imageviewer.hide();
  },
  methods: {
    showImageViewer (file, files) {
      if (file.category !== 'image') {
        return;
      }
      const _files = files.filter((_file) => _file.category === 'image');
      this.$imageviewer.show({
        index: _files.findIndex((_file) => _file.uid === file.uid),
        // images: _files.map(_file => `${_file.url}?t=${Date.now()}`),
        images: _files.map((_file) => _file.url),
      });
    },
    exceed (currFiles, files, limit) {
      this.$toast.show(`只允许上传${limit}个文件`);
    },
    // eslint-disable-next-line no-unused-vars
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    mismatch (mismatchFiles, currFiles, format) {
      // format 可能是数组 也可能是函数
      this.$toast.show(`只允许上传${this.format.join(',')}后缀的文件`);
    },
    oversize (oversizeFiles, currFiles, maxSize) {
      this.$toast.show(`只允许上传${maxSize / 1024}KB大小的文件`);
    },
    start () {
      this.$refs.upload.start();
    },
    pause () {
      this.$refs.upload.pause();
    },
    retry () {
      this.$refs.upload.retry();
    },
  },
};
</script>

<style lang="less">
.list {
  background-color: #fff;
  padding: 0 8px;
  p {
    font-weight: 600;
    font-size: 16px;
    padding: 15px;
  }
}
.custom-item {
  width: 100%;
  border-bottom: 1px solid #d8d8d8;
  padding: 12px 8px;
  display: flex;
  align-items: center;
  position: relative;
  &__icon {
    width: 48px;
    height: 48px;
    background-color: #f4f8fc;
    background-position: center;
    background-repeat: no-repeat;
    background-size: cover;
    border-radius: 8px;
    flex-shrink: 0;
  }
  &__content {
    flex: 1;
    display: flex;
    flex-direction: column;
    margin: 0 8px;
    &-name {
      font-size: 16px;
      color: #333;
      margin-bottom: 8px;
      word-wrap: break-word;
      word-break: break-all;
    }
    &-size {
      font-size: 12px;
      color: #999;
    }
  }
  &__progress {
    height: 4px;
    width: 0;
    left: 0;
    bottom: 0;
    background: #107ff0;
    position: absolute;
    will-change: width;
    transition: width 200ms linear;
  }
  &__btn {
    flex-shrink: 0;
    margin-top: 10px;
    width: calc(100vw - 16px);
    height: 50px;
    border-radius: 2px;
    border: 1px dashed #d3d6dc;
    display: flex;
    justify-content: center;
    align-items: center;
    font-size: 18px;
    color: rgba(16, 127, 240, 1);
  }
}
</style>

与h3-mobile-vue组件的区别以及迁移

旧组件库upload组件与field组件耦合在一起，应单独抽出一个组件，同时优化了upload组件，增加了新的特性和功能。

若要做迁移请参考

1. 弃用的props:
2. 替换的props:
3. 新增的props:
4. 弃用原来所有的事件

API

• 本文中所有的原始文件对象统称为原始文件，而经过包装后的文件对象称为文件对象，这个文件对象的结构如下

属性	说明	类型	prop:value 必填项
uid	uid	string	否
name	文件名	string	是，应带文件后缀，若无文件后缀，请设置 category
type	文件原始类型	number	否
size	文件大小	number	否
category	文件类别 image video audio document word excel ppt pdf archive exe unknown	number	否
categoryIcon	文件类别缩略图	string	否
url	文件 url，通过 URL.createObjectURL 获得，或者是 prop:value 传入的url	string	是
status	文件状态，ready, uploading, success, error, finish	string	否
progress	文件上传进度，整数 0~100	number	否
file	原始文件或者 prop:value 传入的对象	File | object	否
base64	文件转成base64字符串，仅仅在prop:base64非否时产生	string	否
result	响应内容，上传成功或失败后产生	any	否

Prop

属性	说明	类型	默认值
value	value，v-model绑定值，子配置项可参考 文件对象 结构中 prop:value 必填项描述	array	无
action	上传行为配置项，最少包含上传目标的 URL 地址	string | object	无
request	上传请求函数，参数 file: 文件对象, action: 处理过的prop:action, callback: 回调函数对象 {onSuccess, onError, onProgress}	function	内置上传函数
accept	允许上传的文件类型，详细说明	string	'*'
multiple	是否允许多选	boolean	false
parallelCount	并行上传文件数量	number	5
limit	上传文件限制数量	string |number	-
format	匹配的文件后缀的数组，例如['png','jpeg','jpg']；或者是返回boolean的函数，若为返回true则为匹配，false为不匹配，参数是原始文件	array| function	[]
maxSize	文件最大尺寸，单位为 byte	string |number	-
capture	图片选取模式，可选值为camera(直接调起摄像头)，Android系统存在兼容性问题	string	''
disabled	是否禁用	boolean	false
deletable	是否可删除	boolean	true
uploadIcon	默认的上传按钮icon	string	plus-o
processFile	添加文件到列表时触发文件处理函数，请返回处理后的文件对象；若返回false可终止文件读取；若返回Promise 请在成功回调返回处理后的文件对象；参数是文件对象	function	-
thumbnail	图片类型是否展示实际图片缩略图而非文件类别缩略图	boolean	true
customize	是否自定义触发选择文件而非使用浏览器默认调用，若为 true 请监听 event:select 事件及调用实例方法 addFiles	boolean	false
base64	是否将文件转成base64字符串，若为true则所有类型的文件都会被转换，若为数组，则只对指定的文件类型category做转换，例如 ['image']	boolean|array	false

• action 子配置项

如果 action 是字符串，则会被处理成 { target: action }。

参数	说明	类型	默认值
target	上传目标 URL，如果为函数，则传入当前文件对象调用得到目标 URL	string | function	-
fileName	上传文件时文件的参数名	string	'file'
prop	上传的时候使用文件对象的 prop 属性所对应的值	string	'file'
headers	自定义请求头，如果为函数，则传入当前文件对象调用得到 headers	object | function	{}
data	上传需要附加数据，如果为函数，则传入当前文件对象调用得到 data	object | function	{}
withCredentials	标准的 CORS 请求是不会带上 cookie 的，如果想要带的话需要设置 withCredentials 为 true	boolean	false
timeout	请求超时时间	number	0
handleResult	处理返回结果的函数，返回值会赋值到文件对象的result	(target, xhr) => any	-

• callback 子配置项

函数名	说明	参数
onSuccess	当成功时调用	function
onError	当失败时调用	function
onProgress	当加载时能获取上传进度时调用	function

Event

事件名	说明	参数
input	文件列表改变时触发，v-model绑定事件	value:文件对象[]
exceed	上传文件数量超过限制时触发	selectFiles:文件对象[]，当前选中的文件，files:文件对象[]，当前文件列表数据，limit:number 上传文件限制数量
mismatch	上传文件匹配后缀类型错误时触发	mismatchFiles:文件对象[]，格式匹配错误文件，selectFiles:文件对象[]，当前选中的文件，format:array 文件格式数组
oversize	上传文件大小超过限制时触发	oversizeFiles:文件对象[]，超过大小限制的文件，selectFiles:文件对象[]，当前选中的文件，maxSize:number 文件最大尺寸
success	文件上传成功时触发	response: 响应内容，file:文件对象，对应的文件
progress	文件上传过程有进度时触发	percent: 进度[0 - 100]，file:文件对象，对应的文件
error	文件上传失败时触发	err: 错误对象或描述，file:文件对象，对应的文件
removed	文件被移除后触发	file:文件对象，被移除的文件，files:文件对象[]，当前文件列表数据
fileClick	文件列表项被点击触发	file:文件对象，被点击的文件，files:文件对象[]，当前文件列表数据
select	自定义选择文件时触发	-

Function

• 实例方法

方法名	说明	参数
start	开始上传	-
pause	暂停上传	-
retry	重试上传	-
removeFile	删除文件	文件对象
addFiles	添加文件	原始文件[]

Slots

参数	说明	SlotProps
default	上传按钮插槽	-
list	文件列表插槽	{ files: 文件列表, removeFile: 移除文件事件 }