ZBaseUi

Appearance

UploadFile 上传 ​

文件选择上传控件。

何时使用 ​

上传是指将压缩包、图片、视频、文档等通过网页或者上传工具发布到远程服务器上的过程。

  • 当需要上传一个或多个文件时。
  • 当需要对上传的文件进行多种形态的预览时。

代码演示 ​

1. 经典样式 ​

上传
经典样式
默认样式
<template>
  <z-upload-file v-model="fileList" @upload="uploadChange"></z-upload-file>
</template>

<script setup lang="ts">
import { ref } from "vue";
import {uploadEvFn, uploadEvtCe} from "@d7ee/z-base-ui";

const fileList = ref<Array<{name: string, path: string}>>([]);

const uploadChange = (e: uploadEvtCe, fn: uploadEvFn) => {
  // 上传回调，获取文件列表，进行异步上传
  console.log(e.file);
  // 版本 >= 1.0.1单个文件可传入SRC地址，多个文件可通过Array<{name, path}>
  fn("https://xxx.com/img/xxx.png");
};
</script>

2. 已上传的文件列表 ​

上传
已上传的文件列表
使用value设置已上传的内容。
<template>
  <z-upload-file v-model="fileList"></z-upload-file>
</template>

<script setup lang="ts">
import { ref } from "vue";

const fileList = ref<any[]>([{
  name: "xxx.png",
  path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
}, {
  name: "小熊.png",
  path: "http://7dee.com/img/user.png"
}]);
</script>

3. 受控制的上传 ​

上传
受控制的上传
使用num控制上传的数量。当你超过数量时你将通过@reject收到警告回调。
<template>
  <z-upload-file v-model="fileList" :num="2" @reject="errChange"></z-upload-file>
</template>

<script lang="ts" setup>
import {ref} from "vue"

const fileList = ref<any[]>([
  {
    name: "xxx.png",
    path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
  }, {
    name: "小熊.png",
    path: "http://7dee.com/img/user.png"
  }
])

const errChange = (e: any) => {
  console.log(e, "异常消息");
}
</script>

4. 失败的图片上传 ​

上传
无法被预览的链接
当你的列表存在一张无法被访问的图片时，超过请求时间后，它的Border将会变红。
<template>
  <z-upload-file v-model="fileList"></z-upload-file>
</template>

<script lang="ts" setup>
import {ref} from "vue"

const fileList = ref<any[]>([
  {
    name: "xxx.png",
    path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
  }, {
    name: "小熊.png",
    path: "http://xxx.com/img/user.png"
  }
])
</script>

4. list 列表 ​

上传
xxx.png
列表模式
type=list时，预览效果将会以列表呈现。
<template>
  <z-upload-file type="list" v-model="fileList"></z-upload-file>
</template>

<script lang="ts" setup>
import {ref} from "vue"

const fileList = ref<any[]>([
  {
    name: "xxx.png",
    path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
  }
])
</script>

5. list-simple 列表极简 ​

上传
xxx.png
列表极简模式
type=list-simple时，它就会变得非常简洁。
<template>
  <z-upload-file type="list-simple" v-model="fileList"></z-upload-file>
</template>

<script lang="ts" setup>
import {ref} from "vue"

const fileList = ref<any[]>([
  {
    name: "xxx.png",
    path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
  }
])
</script>

6. card-inner 隐藏删除 ​

上传
隐藏外部删除，指向时浮现
type=card-inner时，右下角的删除会被隐藏，只有当你鼠标指向它时才会出现。
<template>
  <z-upload-file type="card-inner" v-model="fileList"></z-upload-file>
</template>

<script lang="ts" setup>
import {ref} from "vue"

const fileList = ref<any[]>([
  {
    name: "xxx.png",
    path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
  }
])
</script>

7. single 单文件上传 ​

上传
单文件模式
type=single时，上传按钮和预览将会叠加在一起。

<template>
  <z-upload-file type="single" v-model="fileList"></z-upload-file>
</template>

<script lang="ts" setup>
import {ref} from "vue"

const fileList = ref<any[]>([
  {
    name: "xxx.png",
    path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
  }
])
</script>

8. slot 自定义上传按钮和预览列表 ​

自定义功能的实现
如果现有的样式不能满足你，或许可以考虑使用自定义插槽，默认插槽用于定义上传按钮，具名插槽fileRender用于定义渲染预览列表，当然你也可以自定义其中的一种。

<template>
  <z-upload-file type="list" v-model="fileList">
    <a-button>自定义上传按钮</a-button>

    <template #fileRender="{files}">
      <img v-for="item in files" :key="item.id" :src="item.path" alt=""/>
    </template>
  </z-upload-file>
</template>

<script lang="ts" setup>
import {ref} from "vue"

const fileList = ref<any[]>([
  {
    name: "xxx.png",
    path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
  }
])
</script>

<style scoped>
img{
  margin-top: 20px;
  width: 50px;
  box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.5);
  border-radius: 50%;
}
</style>

9. 完全受控制的上传 ​

上传
完全受控制的上传
在上传时，你可以选择什么都不做，不调用回调函数也不更新value，以此来拦截上传。

<template>
  <z-upload-file v-model="fileList" @upload="uploadChange"/>
</template>

<script lang="ts" setup>
import {ref} from "vue"
import {uploadEvFn, uploadEvtCe} from "@d7ee/z-base-ui";

const fileList = ref<any[]>([
  {
    name: "xxx.png",
    path: "https://zos.alipayobjects.com/rmsportal/jkjgkEfvpUPVyRjUImniVslZfWPnJuuZ.png"
  }
])

const uploadChange = async (e: uploadEvtCe, fn: uploadEvFn) => {
  // 操作.....
  console.log(e);
  /**
   * @function fn
   * - 对于不满足条件的文件，你可以不向fn或绑定数据进行追加，它就会被拦截
   * - 对于需要异步上传的数据，在上传完成后调用fn返回一个Array<{name: "文件名", path: "文件url地址"}>用于更新文件列表、
   * */
  fn(false);
  // fn([{name: "xx.png", path: "xxxxxx"}]);
}
</script>

10. 拖拽上传 ​

上传
拖拽上传
通过设置drag来允许用户进行拖拽上传，版本>=0.0.12
<template>
  <z-upload-file v-model="fileList" @upload="uploadChange" drag></z-upload-file>
</template>

<script setup lang="ts">
import { ref } from "vue";
import {uploadEvFn, uploadEvtCe} from "@d7ee/z-base-ui";

const fileList = ref<Array<{name: string, path: string}>>([]);

const uploadChange = (e: uploadEvtCe, fn: uploadEvFn) => {
  // 上传回调，获得File数据，可在此处进行异步上传
  console.log(e);
  fn(false);
};
</script>






APi ​

props ​

参数说明类型默认值版本
num上传数量控制number9>= 0.0.8
limit文件大小控制，单位mbnumber10MB>= 0.0.8
accept文件类型约束，用于约束用户能上传的文件，详见acceptstring | string[]*>= 0.0.8
type预览列表效果，支持五种基本样式，详见typestringcard>= 0.0.8
repeat重名校验，启用后不允许出现同名文件booleantrue>= 0.0.8
checksums关闭所有校验规则booleanfalse>= 0.0.8
preview关闭文件预览列表booleanfalse>= 0.0.8
value默认值，通过v-model=""绑定Array<{name: string, path: string}>[]>= 0.0.8
drag拖拽上传booleanfalse>= 0.0.12

props-type ​

类型说明类型版本
card卡片效果，删除在右下角string>= 0.0.8
card-inner卡片效果，删除隐藏在内部，鼠标指向时出现string>= 0.0.8
single单文件上传，适用于只上传一个文件，预览效果和上传按钮重叠string>= 0.0.8
list-simple列表模式，非常简洁string>= 0.0.8
list列表模式string>= 0.0.8

props-accept ​

  • 何时使用：对文件类型有约束条件时
  • 报错信息：除了在控制台打印警告信息外，同时触发reject事件
  • 注意事项：当你想只允许上传jpg格式时，最好同时允许上传jpeg格式，经测试在网上下载到后缀名为jpg的图片，读取到的类型大多为jpeg
  • string：string类型更适合约束单文件类型或范围约束如，accept='png'，accept='image/*'
  • string[]：数组形适合约束不同类型文件，如:accept=['jpg', 'jpeg', 'zip']

自定义插槽 ​

  • 何时使用：当现有样式无法满足需求时使用
  • 插槽携带一个返回值files，为文件数组，通过path可获取到文件的url地址
插槽名说明参数版本
default默认插槽，用于自定义上传按钮files>= 0.0.8
fileRender渲染插槽，用于自定义文件列表的展示形态files>= 0.0.8

自定义上传按钮 ​

vue
<template>
  <z-upload-file>
    <button>我是自定义上传按钮</button>
  </z-upload-file>
</template>

自定义文件预览 ​

vue
<template>
  // 在组件内渲染
  <z-upload-file>
    <template #fileRender="{files}">
      <img v-for="item in files" :key="item.id" :src="item.path"/>
    </template>
  </z-upload-file>

  // 在组件外渲染，使用preview关闭默认效果
  <div>
    <img v-for="item in fileArr" :key="item.id" :src="item.path"/>
  </div>
  <z-upload-file v-model="fileArr" :preview="true"></z-upload-file>
</template>

<script setup lang="ts">
import { ref } from "vue";

const fileArr = ref<any>([]);
</script>

常见问题：我使用了type='single'，进行单个文件上传时如何自定义呢？

示列代码

vue
<template>
	<z-upload-file type="single">
    	<template #default={files}>
            <button v-if="files.length > 0">上传</button>
            <img v-else :src="files[0].path"/>
		</template>
    </z-upload-file>
</template>

事件 ​

事件说明类型版本
upload上传时回调，详见uploadfunction(e, fn)>= 0.0.8
remove删除时回调，详见removefunction(e)>= 0.0.8
reject异常状况时回调，详见rejectfunction(e)>= 0.0.8
removeFile手动删除文件，通过ref获取实列后进行调用，需要传入被删文件的下标，详见removeFilefunction(e)>= 0.1.2

upload ​

选择文件后触发回调，接收一个参数和一个回调函数

  • 参数：{type: 类型, file：文件列表}
  • 回调函数：Array<{name：文件名, path：src}> | {name：文件名, path：src} | string
  • 注意：回调函数中的Object和String类型需要版本 >= 1.0.1

代码演示 ​

vue
<template>
  <z-upload-file @upload="uploadChange"/>
</template>

<script lang="ts" setup>
import {uploadEvFn, uploadEvtCe} from "@d7ee/z-base-ui";

const uploadChange = async (e: uploadEvtCe, fn: uploadEvFn) => {
  console.log(e);
  fn(false); // 阻止上传
  
  // fn([{name: "测试.png", path: "src地址"}]); // 多文件上传或单文件
  // fn("src地址") // 单文件返回
  // fn({name: "测试.png", path: "src地址"}) // 单文件
}
</script>

参数 ​

{
  type: "upload", // 类型
  file: File[], // 本次上传的文件列表
}

remove ​

当有文件从列表被删除时会调用这个函数

remove(e: uploadEvtRm)

代码演示 ​

vue
<template>
  <z-upload-file @remove="uploadRemove"/>
</template>

<script lang="ts" setup>
import {uploadEvtRm} from "@d7ee/z-base-ui";

const uploadRemove = async (e: uploadEvtRm) => {
  console.log(e);
}
</script>

返回值 ​

{
  type: "remove", // 类型
  file: File[], // 被删除的的文件
}

reject ​

上传文件失败或出现其它异常情况时触发该函数

  • 版本 >= 1.0.1，增加 msg 字段，用于直接获取错误信息。

reject(e: uploadEvtRj)

代码演示 ​

vue
<template>
  <z-upload-file @reject="uploadReject"/>
</template>

<script lang="ts" setup>
import {uploadEvtRj} from "@d7ee/z-base-ui";

const uploadReject = async (e: uploadEvtRj) => {
  console.log(e);
}
</script>

返回值: 场景1，通常出现在上传时 ​

{
  type: "reject",
  mgs: "错误原因",
  info: {
    repeatName: [], // 重名文件
    tooBig: [],  // 文件过大，0.0.15以前字段为oversized，你仍然可以使用它
    refuseType: [], // 文件类型不符
  }
}

返回值: 场景2，通常出现在发生其它异常情况时 ​

{
  type: "reject",
  info: "错误原因",
  mgs: "错误原因",
}

removeFile ​

主动删除文件，通过ref获取组件实列，调用removeFile函数，传入待删除文件的下标

removeFile(e: number)

代码演示 ​

vue
<template>
  <z-upload-file ref="rUpload">
    <template #fileRender="{files}">
      <img v-for="(item, index) in files" :key="index" :src="item.path" alt="" @click="removeItem(index)"/>
    </template>
  </z-upload-file>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const rUpload = ref<any>();

// 删除文件
const removeItem = async (e: number) => {
  rUpload.value.removeFile(e);
};
</script>