Uploader 上传

示例

文件上传

设置 type 的值为 file 进入文件上传模式。

Normal size

demo-file1.txt
demo-file2.txt

Small size

demo-file1.txt
demo-file2.txt

<template>
<article>
  <section>
    <h4>Normal size</h4>
    <veui-uploader
      v-model="files"
      action="/api/upload"
    />
  </section>
  <section>
    <h4>Small size</h4>
    <veui-uploader
      v-model="files2"
      action="/api/upload"
      ui="s"
    />
  </section>
</article>
</template>

<script>
import { Uploader } from 'veui'
import { cloneDeep } from 'lodash'

export default {
  components: {
    'veui-uploader': Uploader
  },
  data () {
    let files = [
      {
        name: 'demo-file1.txt',
        src: '/file/demo-file1.txt',
        key: 0
      },
      {
        name: 'demo-file2.txt',
        src: '/file/demo-file2.txt',
        key: 1
      }
    ]
    return {
      files,
      files2: cloneDeep(files)
    }
  }
}
</script>

<style lang="less" scoped>
article {
  display: flex;
}

section {
  width: 45%;
}
</style>

图片上传

设置 type 的值为 image 进入图片上传模式。

Normal size

上传图片
Normal size

Small size

上传图片
Small size

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <h4>Normal size</h4>
    <veui-uploader
      v-model="images"
      type="image"
      action="/api/upload"
    >
      <template #help>
        Normal size
      </template>
    </veui-uploader>
  </section>
  <section>
    <h4>Small size</h4>
    <veui-uploader
      v-model="images2"
      type="image"
      action="/api/upload"
      ui="s"
    >
      <template #help>
        Small size
      </template>
    </veui-uploader>
  </section>
</article>
</template>

<script>
import { Uploader } from 'veui'
import { cloneDeep } from 'lodash'

export default {
  components: {
    'veui-uploader': Uploader
  },
  data () {
    let images = [
      {
        src: '/images/development/uploader/demo-image1.jpg',
        key: 0
      },
      {
        src: '/images/development/uploader/demo-image2.jpg',
        key: 1
      }
    ]
    return {
      images,
      images2: cloneDeep(images)
    }
  }
}
</script>

媒体上传

设置 type 的值为 media 进入媒体上传模式。

Normal size

上传多媒体
Normal size

Small size

上传多媒体
Small size

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <h4>Normal size</h4>
    <veui-uploader
      v-model="media"
      type="media"
      action="/api/upload"
    >
      <template #help>
        Normal size
      </template>
    </veui-uploader>
  </section>
  <section>
    <h4>Small size</h4>
    <veui-uploader
      v-model="media2"
      type="media"
      action="/api/upload"
      ui="s"
    >
      <template #help>
        Small size
      </template>
    </veui-uploader>
  </section>
</article>
</template>

<script>
import { Uploader } from 'veui'
import { cloneDeep } from 'lodash'

export default {
  components: {
    'veui-uploader': Uploader
  },
  data () {
    let media = [
      {
        type: 'image',
        src: '/images/development/uploader/demo-image1.jpg',
        key: 0
      },
      {
        type: 'video',
        src: 'https://nadvideo2.baidu.com/5dafd8544f4f53b27a5f59b0ab780403_1920_1080.mp4',
        poster: 'https://feed-image.baidu.com/0/pic/4dced79d185a16e228652b136f653dcc.jpg',
        key: 1
      }
    ]
    return {
      media,
      media2: cloneDeep(media)
    }
  }
}
</script>

校验

图片格式、大小、数量校验以及使用 validator 自定义校验。

上传图片
请选择jpg、png图片，大小不超过100kb，宽高分别大于200px，最多上传6张图片

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <veui-uploader
      v-model="images"
      type="image"
      action="/api/upload"
      accept="jpg,png"
      :max-count="6"
      max-size="100kb"
      :validator="validator"
    >
      <template #help>
        请选择jpg、png图片，大小不超过100kb，宽高分别大于200px，最多上传6张图片
      </template>
    </veui-uploader>
  </section>
</article>
</template>

<script>
import { Uploader } from 'veui'

export default {
  components: {
    'veui-uploader': Uploader
  },
  data () {
    return {
      images: [
        {
          src: '/images/development/uploader/demo-image1.jpg',
          key: 0
        },
        {
          src: '/images/development/uploader/demo-image2.jpg',
          key: 1
        }
      ],
      validator (file) {
        return new Promise(resolve => {
          let image = new Image()
          image.src = window.URL.createObjectURL(file)
          image.onload = () => {
            resolve({
              valid: image.height > 200 && image.width > 200,
              message: '图片宽高太小'
            })
          }
        })
      }
    }
  }
}
</script>

自定义上传

使用 upload 自定义上传过程，使用 controls 配置浮层操作项。

上传图片
点击图片浮层上的向右箭头按钮改变图片位置

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <veui-uploader
      v-model="images"
      type="image"
      :action="action"
      :controls="controls"
      request-mode="custom"
      :upload="upload"
      @moveright="handleMoveRight"
    >
      <template #help>
        点击图片浮层上的向右箭头按钮改变图片位置
      </template>
    </veui-uploader>
  </section>
</article>
</template>

<script>
import { Uploader } from 'veui'

export default {
  components: {
    'veui-uploader': Uploader
  },
  data () {
    return {
      action: '/upload',
      images: [
        {
          key: 0,
          src: '/images/development/uploader/demo-image1.jpg'
        },
        {
          key: 1,
          src: '/images/development/uploader/demo-image2.jpg'
        }
      ],
      controls (file, defaultControls) {
        if (file.status === 'success') {
          return [
            { name: 'moveright', icon: 'chevron-right', disabled: false },
            ...defaultControls
          ]
        }
        return defaultControls
      },
      upload: (file, { onload, onprogress, onerror }) => {
        let xhr = new XMLHttpRequest()
        file.xhr = xhr

        xhr.upload.onprogress = e => onprogress(e)
        xhr.onload = e => {
          try {
            onload(JSON.parse(xhr.responseText))
          } catch (e) {
            onload({ success: false, message: e })
          }
        }
        xhr.onerror = e => onerror(e)
        let formData = new FormData()
        formData.append('file', file)

        xhr.open('POST', this.action, true)
        xhr.send(formData)

        return () => {
          xhr.abort()
        }
      }
    }
  },
  methods: {
    handleMoveRight (file, index) {
      if (index < this.images.length - 1) {
        let temp = { ...this.images[index] }
        this.$set(this.images, index, this.images[index + 1])
        this.$set(this.images, index + 1, temp)
      }
    }
  }
}
</script>

拖拽排序

设置 sortable 属性来指定上传项目之间可以拖拽排序。

上传图片

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <veui-uploader
      v-model="images"
      sortable
      type="image"
      action="/api/upload"
    />
  </section>
</article>
</template>

<script>
import { Uploader } from 'veui'

export default {
  components: {
    'veui-uploader': Uploader
  },
  data () {
    return {
      images: [
        {
          key: 0,
          src: '/images/development/uploader/demo-image1.jpg'
        },
        {
          key: 1,
          src: '/images/development/uploader/demo-image2.jpg'
        }
      ]
    }
  }
}
</script>

自定义操作栏

设置 controls 属性来指定悬浮到每个上传项时的操作选项。

上传图片

用 controls 自定义的操作，点击会触发同名事件，事件参数为该上传项数据和 status 字段, 即通常是 {src, key, type, status, ...}。

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <veui-uploader
      v-model="images"
      :controls="controls"
      type="image"
      action="/api/upload"
      @star="handleStar"
    />
  </section>
</article>
</template>

<script>
import { Uploader, toast } from 'veui'
import 'veui-theme-dls-icons/star'

export default {
  components: {
    'veui-uploader': Uploader
  },
  data () {
    return {
      images: [
        {
          key: 0,
          src: '/images/development/uploader/demo-image1.jpg'
        },
        {
          key: 1,
          src: '/images/development/uploader/demo-image2.jpg'
        }
      ],
      controls (item, defaultControls) {
        return [
          ...defaultControls,
          {
            name: 'star',
            icon: 'star',
            label: 'star'
          }
        ]
      }
    }
  },
  methods: {
    handleStar () {
      toast.info('You click star!')
    }
  }
}
</script>

自定义上传入口

设置 entries 属性来指定悬浮到继续上传项目时的操作选项。

上传图片

用 entries 自定义的操作，点击会触发同名事件，事件参数为空。

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <veui-uploader
      v-model="images"
      :entries="entries"
      type="image"
      action="/api/upload"
      @star="handleStar"
    />
  </section>
</article>
</template>

<script>
import { Uploader, toast } from 'veui'
import 'veui-theme-dls-icons/star'

export default {
  components: {
    'veui-uploader': Uploader
  },
  data () {
    return {
      images: [
        {
          key: 0,
          src: '/images/development/uploader/demo-image1.jpg'
        },
        {
          key: 1,
          src: '/images/development/uploader/demo-image2.jpg'
        }
      ],
      entries (defaultEntries) {
        return [
          ...defaultEntries,
          {
            name: 'star',
            icon: 'star',
            label: 'star'
          }
        ]
      }
    }
  },
  methods: {
    handleStar () {
      toast.info('You clicked star!')
    }
  }
}
</script>

自定义选择文件

设置 pick 属性来自定义选择文件。

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <veui-uploader
      type="file"
      :pick="pick"
      action="/api/upload"
    />
  </section>
</article>
</template>

<script>
import { Uploader } from 'veui'
import confirm from 'veui/plugins/confirm'
import Vue from 'vue'

Vue.use(confirm)

export default {
  components: {
    'veui-uploader': Uploader
  },
  methods: {
    pick ({ remainingCount }) {
      return this.$confirm('模拟自定义选择文件', '确认').then((ready) => {
        return ready
          ? new File([`count: ${remainingCount}`], 'pick.txt', { type: 'text/plain' })
          : null
      })
    }
  }
}
</script>

帮助文案

设置 help 属性或help 插槽来指定帮助文案。

辅助信息位置：

Help text

demo-file1.txt

Custom help text via `help` slot

demo-file1.txt

在 GitHub 上编辑此示例编辑

<template>
<article>
  <section>
    <div>
      辅助信息位置：
      <veui-radio-button-group
        v-model="helpPosition"
        ui="s"
        :items="availableHelpPositions"
      />
    </div>
    <veui-uploader
      v-model="files"
      class="uploader"
      :help-position="helpPosition"
      help="Help text"
      action="/api/upload"
    />
    <veui-uploader
      v-model="files"
      class="uploader"
      :help-position="helpPosition"
      action="/api/upload"
    >
      <template #help>
        Custom help text via `help` slot
      </template>
    </veui-uploader>
  </section>
</article>
</template>

<script>
import { Uploader, RadioButtonGroup } from 'veui'

const mapper = (value) => ({ label: value, value })

export default {
  components: {
    'veui-uploader': Uploader,
    'veui-radio-button-group': RadioButtonGroup
  },
  data () {
    let files = [
      {
        name: 'demo-file1.txt',
        src: '/file/demo-file1.txt',
        key: 0
      }
    ]
    return {
      files,
      helpPosition: 'side',
      availableHelpPositions: ['side', 'bottom'].map(mapper)
    }
  }
}
</script>

<style lang="less" scoped>
article {
  display: flex;
}

.uploader {
  margin-top: 16px;
}

section {
  width: 45%;
}
</style>

API

属性

属性类型默认值描述

ui

string

预设样式。

值	描述
`s`	小尺寸样式。
`m`	中尺寸样式。

type

string

'file'

上传类型。

值	描述
`file`	文件上传。
`image`	图片上传。
`media`	媒体上传（支持视频和图片）。
`video`	视频上传。

value

Object | Array<Object>

当 multiple 为 true，返回文件对象的数组。另外，当 max-count 被设置为大于 1 的值，则会视为开启了 multiple。

每个文件对象的类型为 {name: string, src: string, ...}，以及在 convert-response 中自定义添加的字段。

key-field string 'key' 用于指定文件对象的唯一 key，作为数据变化时正确处理文件列表顺序的依据。

name string 'file' 原生 <input> 元素的 name。

action string - 上传地址。

headers Object uploader.headers 需要加入 HTTP 请求头的内容。可进行全局统一配置。

with-credentials boolean true 同 XMLHttpRequest 的 withCredentials 属性。

request-mode

string

uploader.requestMode

指定异步上传方式。可进行全局统一配置。

值	描述
`xhr`	通过 `XMLHttpRequest` 上传。
`iframe`	通过 `<iframe>` 上传。
`custom`	自定义上传过程，通过 prop `upload` 方法上传。

iframe-mode

string

uploader.iframeMode

指定在 request-mode 的值为 iframe 的模式下，上传成功后的回调方式。可进行全局统一配置。

值	描述
`postmessage`	通过 `PostMessage` 回调。
`callback`	通过调用 `window` 的 `callback-namespace` 里的回调函数回调。

callback-namespace string uploader.callbackNamespace 在 request-mode 的值为 'iframe' 并且 iframe-mode 的值为 'callback' 的模式下，指定回调函数的命名空间，放在 window 对象下。可进行全局统一配置。

data-type

string

'json'

如果回调的值是文本, 指明文本的解析方式。如果回调的数据是 Object，则 data-type 可以为空。

值	描述
`json`	回调的文本是 JSON。
`text`	回调的文本是普通文本。

convert-response

uploader.convertResponse

将回调数据转换成需要的格式的函数，使组件能够判断上传是否成功以便显示相应结果，参数是回调数据。返回结果的格式要求如下：

字段	类型	描述
`success`	`boolean`	表示上传是否成功。
`name`	`string`	文件的名称。`success` 为 `true` 时必须。
`src`	`string`	文件的地址。`success` 为 `true` 时必须。
`message`	`string`	上传失败时的出错信息。`success` 为 `false` 时必须。
`preview`	`boolean`	上传失败时，是否预览失败的上传项。

还可以给返回结果加上其它自定义的属性，这些自定义属性会被包含在 value 以及 change、success、failure、remove、progress 事件的回调参数 file 中。可进行全局统一配置。

accept string - 与原生 <input> 元素的 accept 属性相同，在浏览器的文件类型筛选后再加一层校验。对于类似 application/msword 这样的 MIME type 与扩展名对不上的情形跳过校验。

max-count number - 最大文件数量。

max-size number | string - 单个文件的最大大小，如果是 number，单位是 byte；如果是 string，支持在数字后面添加单位，单位可以是 b / kb / mb / gb / tb。

validator

function(Object): Object | Promise<Object>

自定义校验逻辑，参数为原生 File 对象。返回结果的格式要求如下：

字段	类型	描述
`valid`	`boolean`	是否通过校验。
`message`	`string`	`valid` 为 `false` 时的错误提示信息。
`preview`	`boolean`	当校验失败时，是否预览失败的上传项。

支持异步校验，返回值可以是一个 resolve 上述返回结果的 Promise。

payload Object - 附带在上传请求中的额外参数。

autoupload boolean true 指定是否在选完文件后立刻上传。

order

string

'asc'

上传文件的显示顺序，按照开始上传的时间排序。

值	描述
`asc`	升序排列。
`desc`	降序排列。

picker-position

string

'after'

图片上传模式下，上传按钮在图片队列中的位置。

值	描述
`before`	上传按钮始终在队列最前面。
`after`	上传按钮始终在队列最后面。
`top`	上传按钮始终在队列上面。
`none`	不展示上传按钮。

upload

function(Object, Object): function

在 request-mode 的值是 'custom' 的情况下自定义上传过程，第一个参数为原生 File 对象，第二个参数为包含与上传过程相关的回调函数的对象，具体字段如下：

字段	类型	描述
`onload`	`function`	上传完成的回调函数，参数内容与 `convert-response` 属性返回值相同。
`onprogress`	`function`	上传进度发生变化的回调函数，参数为 `{ loaded: number, total: number }`，`loaded` 为已上传部分字节数，`total` 为文件总字节数。
`oncancel`	`function`	自定义上传主动取消时对组件进行的回调，无参数。
`onerror`	`function`	上传出错的回调函数，参数为 `{ message: string }`，`message` 为错误提示信息。

如果 upload 返回一个函数，该函数将在用户操作取消或上传组件销毁时被调用，用来中断自定义上传过程。

controls

function(Object, Array<Object>): Array<Object>

图片上传模式下，用来自定义配置图片遮罩浮层上的操作项，参数为 (file: Object, defaultControls: Array<Object>)，file 为文件相关信息，defaultControls 为包含默认的操作项的数组。可根据文件状态的不同，返回包含不同的操作项的数组。每个操作项的具体字段如下：

字段	类型	描述
`name`	`string`	操作项的名称，点击该按钮后会抛出同名的事件，事件的回调参数为 `(file: Object, index: number)`， `file` 为触发事件的文件对象，`index` 为文件在列表中的序号。
`label`	`string`	操作项的文字描述。
`icon`	`string`	操作项使用的图标。
`disabled`	`boolean`	操作项是否被禁用。如果该字段为空，则该操作项的禁用状态跟随组件整体的禁用状态。

multiple boolean false 上传多个文件，当 max-count 是 1，multiple 是 true，那么 value 也是数组。

entries

function(Array<Object>): Array<Object>

控制每个上传文件的操作项，如删除，预览等，会传递默认的操作项数组作为参数，返回实际生效的操作项数组。操作项对象参考 controls 属性的字段详情。

pick

function({remainingCount: number}): Promise<Object>

自定义选择文件逻辑，返回的文件会被上传。

function pick({ remainingCount: number }): Promise<PickedFile | PickedFile[]>

type PickedFile = {
  name: string
  type: string
  src: string
  poster?: string
  alt?: string
  size?: number
}

值	描述
`name`	文件名称。
`type`	文件类型。
`src`	文件地址。
`poster`	视频文件的预览图片。
`alt`	替换文本。
`size`	文件大小。

after-pick function(Array<Object>): void - 选择文件之后的回调。

sortable boolean false 文件列表是否可以排序。

preview-options object {wrap: true, indicator: 'number'} 传递给 Lightbox 的预览选项。

validity-display

'popup' | 'inline'

'popup'

校验信息的展示方式。

值	描述
`popup`	悬浮时浮层展示校验信息。
`inline`	内联显示校验信息。

help string - 帮助文本。

help-position

'side' | 'bottom'

'side'

帮助信息的展示位置。

值	描述
`side`	展示在上传按钮的侧面。
`bottom`	展示在上传按钮的下面。

picker-label string - 上传按钮的文本。

picker-icon string | Object - 上传按钮的图标，参考 Icon 的 name 属性。

插槽

名称描述

upload 图片上传模式下，上传按钮的区域。

help 对文件数量、格式、大小等的提示内容。

file

单个文件的区域，用来定制文件内容。

名称	类型	描述
`name`	`string`	文件的名称。
`src`	`string`	文件的地址。
`status`	`string`	文件的状态。`'success'` 表示上传成功；`'uploading'` 表示正在上传；`'failure'` 表示上传失败。
`index`	`number`	文件在列表中的序号。

file-before 单个文件内容之前的区域。插槽参数与 file 插槽相同。

file-after 单个文件内容之后的区域。插槽参数与 file 插槽相同。

uploading 图片上传模式下，上传中的单个图片的区域。插槽参数与 file 插槽相同。

failure 图片上传模式下，上传失败的单个图片的区域。插槽参数与 file 插槽相同。

事件

名称描述

change

只在上传成功、删除文件时触发，回调参数为 (value)。

名称	类型	描述
`value`	`Object \| Array<Object>`	组件的 `value` 的值。

remove

删除文件时触发，回调参数为 (file, index)。

名称类型描述

file

Object

被删除的文件。

字段	类型	描述
`name`	`string`	文件名称。
`src`	`string`	文件地址。
`status`	`string`	上传状态。`'success'` 表示上传成功；`'uploading'` 表示正在上传；`'failure'` 表示上传失败。

index number 被删除的文件的序号。

同时也包含在 convert-response 中添加的自定义属性。

success 上传成功时触发，回调参数与 remove 事件的回调参数相同。

failure 上传失败时触发，回调参数与 remove 事件的回调参数相同。

invalid

文件校验失败时触发，回调参数为 (validity: Object)。

名称类型描述

file Object 没有通过校验的文件信息，与 remove 事件的回调参数中的 file 相同。如果校验失败的原因是选择的文件数量超过最大数量 max-count 限制，则这个字段为空。

errors

Array<Object>

包含该文件所有校验错误信息的数组，数组的每一项是包含校验失败信息的对象。

名称	类型	描述
`type`	`string`	校验失败的类型，类型枚举值可从 `Uploader.errors` 对象获取，如 `Uploader.errors.SIZE_INVALID`。
`value`	`number \| string \| Object`	没有通过校验的值，根据 `type` 的不同有不同的类型。
`message`	`string`	检验失败的提示信息。

类型	描述	`value` 类型	`value` 描述
`TYPE_INVALID`	文件类型校验失败。	`string`	文件名称。
`SIZE_INVALID`	文件大小校验失败。	`number`	文件大小字节数。
`TOO_MANY_FILES`	选择的文件数超过 `max-count` 限制。	`number`	已选择的文件数。
`CUSTOM_INVALID`	`validator` 自定义校验失败。	`Object`	文件对象，字段同 `remove` 事件回调参数。

statuschange

在所有文件总的状态发生变化时触发，回调参数为组件整体的状态 (status: string)。

值	描述
`empty`	没有选择任何文件上传。
`uploading`	有任一文件正在上传中。
`failure`	有任一文件上传失败。
`success`	所有文件上传成功。

progress

在 request-mode 的值为 'xhr' 的情况下，在上传进度发生变化时触发，回调参数为 (file, index, event)。

名称	类型	描述
`file`	`Object`	与 `remove` 事件的回调参数中的 `file` 相同。
`index`	`number`	正在上传的文件的序号。
`event`	`Event`	上传进度原生事件。

方法

名称描述

名称	描述
`startUpload`	当 autoupload 为 `false` 时，可手动调用此方法来触发上传。 `function startUpload(): void`

startUpload

当 autoupload 为 false 时，可手动调用此方法来触发上传。

function startUpload(): void

全局配置

名称	类型	默认值	描述
`uploader.requestMode`	`string`	`'xhr'`	参见 `request-mode` 属性。
`uploader.iframeMode`	`string`	`'postmessage'`	参见 `iframe-mode` 属性。
`uploader.callbackNamespace`	`string`	`'veuiUploadResult'`	参见 `callback-namespace` 属性。
`uploader.headers`	`Object`	-	参见 `headers` 属性。
`uploader.convertResponse`	`function(Object): Object`	-	参见 `convert-response` 属性。
`uploader.pickerPosition`	`string`	`'after'`	参见 `picker-position` 属性。

图标

名称	描述
`upload`	上传文件。
`add-image`	上传图片。
`clear`	删除。
`success`	上传成功。
`failure`	上传失败。
`loading`	上传中。
`file`	已上传文件。
`alert`	校验失败警告。
`preview`	预览图片。

自定义样式

名称	类型	默认值	描述
`--dls-uploader-file-item-width`	`<length>`	-	当 `type` 属性设置为 `file` 时，文件列表项目的宽度。

在 GitHub 上编辑此页面编辑