Tuniao UI

Appearance

ImageUpload 图片上传 ​

该组件用于图片上传。

平台差异说明 ​

AppH5微信小程序支付宝小程序百度小程序头条小程序QQ小程序
√√√兼容中兼容中兼容中兼容中

基本使用 ​

  • 可以通过设置fileList参数(对象数组)，显示预置的图片。其中元素的url属性为图片路径。
  • 设置action参数为后端服务器地址，注意H5在浏览器可能会有跨域限制。
vue
<template>
  <tn-image-upload :action="action" :fileList="fileList"></tn-image-upload>
</template>

<script>
  export default {
    data() {
      return {
        // 演示地址，请勿直接使用
        action: 'http://www.example.com/upload_image',
        fileList: [{
          url: 'http://www.example.com/tuniao.jpg',
        }]
      }
    }
  }
</script>

设置为手动上传 ​

组件默认为自动上传，可以设置autoUpload为false，然后通过ref调用组件的upload方法，手动上传图片。

vue
<template>
  <tn-image-upload ref="imageUpload" :action="action" :autoUpload="false"></tn-image-upload>
  <tn-button @click="upload">上传</tn-button>
</template>

<script>
  export default {
    data() {
      return {
        // 演示地址，请勿直接使用
        action: 'http://www.example.com/upload_image',
      }
    },
    methods: {
      upload() {
        this.$refs.imageUpload.upload()
      }
    }
  }
</script>

获取上传的图片列表 ​

图片选择或者上传成功后，会保存在组件内部的lists数组中，数组元素为对象，有如下属性：

  • url: 图片地址
  • error：组件内部使用，不应根据此值判断上传是否成功，而应根据progress属性
  • progress：如果值为100，表示图片上传成功
  • response：上传成功后，服务器返回的数据，这是最有用的了

为了获得上传的文件列表，可以在提交表单时，通过ref获取组件内部的lists文件数组，历遍元素筛选出progress为100的文件

vue
<template>
  <tn-image-upload ref="imageUpload" :action="action" :autoUpload="false"></tn-image-upload>
  <tn-button @click="upload">上传</tn-button>
  <tn-button @click="submit">提交</tn-button>
</template>

<script>
  export default {
    data() {
      return {
        // 演示地址，请勿直接使用
        action: 'http://www.example.com/upload_image',
      }
    },
    methods: {
      upload() {
        this.$refs.imageUpload.upload()
      },
      submit() {
        let files = [];
        // 通过filter，筛选出上传进度为100的文件(因为某些上传失败的文件，进度值不为100，这个是可选的操作)
        files = this.$refs.imageUpload.lists.filter(val => {
          return val.progress == 100
        })
        // 如果您不需要进行太多的处理，直接如下即可
        // files = this.$refs.uUpload.lists
        console.log(files)
      }
    }
  }
</script>

限制图片数量和大小 ​

  • 通过maxCount可以设置最多可以选择的图片的数量，默认限制9张。
  • 通过maxSize设置单张图片最大的大小，单位为B(byte)，默认10MB。
vue
<tn-image-upload :maxSize="5 * 1024 * 1024" maxCount="6"></tn-image-upload>

报错提示 ​

在以下几种情况，组件会默认通过toast提示用户信息，可以把showTips设置为false取消默认的提示，这时可以通过API 中的各种事件，进行自定义的个性化提示

  • 超出允许的最大上传数量
  • 图片大小超出最大允许大小
  • 上传图片出错
  • 移除图片
vue
<tn-image-upload :showTips="false"></tn-image-upload>

上传前的钩子 ​

通过设置beforeUpload的参数来设置上传前的钩子函数(参数不需要加括号)，回调方法会返回两个参数：

  • index——即当前上传文件在上传列表中的索引
  • lists——当前所有的文件列表

此回调可以返回一个promise、true，或者false，下面分别阐述三者的处理情况：

  • false——如果返回false，将会跳过当前文件，继续上传下一张图片(如果有)，并且再次执行beforeUpload钩子
  • true——如果返回true，会随即上传当前文件，上传成功后，继续上传下一张图片(如果有)，并且再次执行beforeUpload钩子
  • promise——如果返回的是一个promise，如果进入then回调，就会和返回true的情况一样，如果进入catch回调，就会和返回false的情况一样

移除前的钩子 ​

通过设置beforeRemove的参数来设置上传前的钩子函数(参数不需要加括号)，回调方法会返回两个参数：

  • index——即当前上传文件在上传列表中的索引
  • lists——当前所有的文件列表

此回调可以返回一个promise、true，或者false，下面分别阐述三者的处理情况：

  • false——如果返回false，会终止移除操作
  • true——如果返回true，会执行移除操作
  • promise——如果返回的是一个promise，如果进入then回调，就会和返回true的情况一样，如果进入catch回调，就会和返回false的情况一样

1.普通返回 ​

vue
<template>
  <tn-image-upload :beforeUpload="beforeUpload"></tn-image-upload>
</template>

<script>
  export default {
    methods: {
      beforeUpload(index, list) {
        // 只上传偶数索引的文件
        if (index % 2 == 0) return true
        else return false
      }
    }
  }
</script>

2.返回Promise ​

vue
<template>
  <tn-image-upload :beforeUpload="beforeUpload"></tn-image-upload>
</template>

<script>
  export default {
    methods: {
      beforeUpload(index, list) {
        return new Promise((resolve, reject) => {
          // 只上传偶数索引的文件
          if (index % 2 == 0) resolve()
          else reject()
        })
      }
    }
  }
</script>

自定义图片列表和上传按钮 ​

  • 自定义上传图片按钮 ​

配置customBtn为true，并将自定义按钮的插槽名称设置为addBtn。

vue
<template>
  <tn-image-upload :customBtn="true">
    <view slot="addBtn" class="tn-image-upload__custom-btn" hover-class="tn-hover-class" hover-stay-time="150">
      <view>选择图片</view>
    </view>
  </tn-image-upload>
</template>

<style lang="scss" scoped="">
  .tn-image-upload__custom-btn {
    background-color: #E6E6E6;
    width: 100%;
    height: 180rpx;
    display: flex;
    align-items: center;
    justify-content: center;
    border-radius: 30rpx;
  }
</style>
  • 自定义上传图片列表 ​

配置showUploadList为false来去除内置的默认图片预览列表。然后通过事件来获取上传文件的列表。

注意：这里需要区分H5和其他端的情况，在H5下可以通过插槽来传递数据。

vue
<template>
  <tn-image-upload ref="imageUpload" :showUploadList="false" @on-list-change="listChange">
    <!-- #ifdef MP-WEIXIN -->
    <view>
      <view v-for="(item,index) in lists" :key="index" class="tn-image-upload__item">
        <image class="tn-image-upload__item__image" :src="item.url || item.path" mode="aspectFill"></image>
      </view>
    </view>
    <!-- #endif -->
    <!-- #ifdef H5 -->
    <template v-slot:file="data">
      <view v-for="(item,index) in data.file" :key="index" class="tn-image-upload__item">
        <image class="tn-image-upload__item__image" :src="item.url || item.path" mode="aspectFill"></image>
      </view>
    </template>
    <!-- #endif -->
  </tn-image-upload>
</template>

<script>
  export default {
    data() {
      return {
        lists: []
      }
    },
    methods: {
      listChange(lists, index) {
        console.log('上传文件列表发生改变', lists, index);
        this.lists = lists
      }
    }
  }
</script>

<style lang="scss" scoped="">
  .tn-image-upload__item {
    width: 100%;
    height: 180rpx;
    border-radius: 30rpx;
    margin-bottom: 20rpx;

    &__image {
      width: 100%;
      height: 180rpx;
      border-radius: 30rpx;
    }
  }
</style>

API ​

Props ​

属性名说明类型默认值可选值
index标记多个图片上传组件的标识Number|String--
action上传图片地址String--
isUniCloudUniCloud上传Booleanfalsetrue
fileList默认显示的上传列表，必须有url属性Array--
disabled禁止上传Booleanfalsetrue
autoUpload自动上传，选择完图片后触发Booleantruefalse
multiple允许选择多张图片Booleantruefalse
maxCount最大允许上传数量Number9-
maxSize单张图片的最大大小(byte)Number10 * 1024 * 1024-
name上传文件的字段名Stringfile-
header上传图片时携带的头部信息Object--
formData上传图片时携带的参数Object--
sizeType选择上传图片的尺寸，具体参考uni文档Array['original','compressed']-
sourceType选择上传图片的来源，具体参考uni文档Array['album','camera']-
showUploadList显示组件自带的图片预览功能Booleantruefalse
imageMode预览图片的裁剪模式，可选值请参考uni的image属性StringaspectFill-
previewFullImage点击图片时进行全屏预览Booleantruefalse
showProgress显示上传进度Booleantruefalse
deleteable显示删除按钮Booleantruefalse
deleteIcon删除按钮的图标，仅可以使用TuniaoUI内置的图标Stringclose-
deleteBackgroundColor删除按钮的背景颜色String--
deleteColor删除按钮的颜色String--
uploadText上传按钮的提示文字String选择图片-
showTips显示toast提示Booleantruefalse
customBtn自定义上传按钮Booleanfalsetrue
width预览图片区域的宽度，单位rpxNumber200-
height预览图片区域的高度，单位rpxNumber200-
limitType允许上传的文件类型Array['png','jpg','jpeg',
'webp','gif','image']		-
toJson自动将服务器返回的结果转换为json格式数组Booleantruefalse
beforeUpload上传文件前钩子函数Function--
beforeRemove移除文件前钩子函数Function--

Slots ​

名称说明
addBtn自定义上传图片按钮内容
file自定义上传文件列表，在H5下有效

Methods ​

此方法要通过ref手动调用。

名称说明
upload手动上传图片
clear清空已上传的图片列表
reUpload重新上传上传失败或者尚未上传的图片
remove(index)移除列表中某一张图片，index为lists数组的索引

Event ​

事件名称说明回调参数
on-list-change当列表文件发生改变时触发，添加、移除文件(lists, name) lists上传文件列表数组，name当前组件的index标识
on-oversize当所选图片的大小操作允许上传大小的最大值时触发(file, lists, name) file当前选择的图片信息，lists上传文件列表数组，name当前组件的index标识
on-exceed当选择的图片超过最大选择数时触发(file, lists, name) file当前选择的图片信息，lists上传文件列表数组，name当前组件的index标识
on-choose-complete每次选择图片后触发(lists, name) lists上传文件列表数组，name当前组件的index标识
on-choose-fail选择文件出错时触发(err)err错误信息
on-uploaded所有图片上传完毕时触发(lists, name) lists上传文件列表数组，name当前组件的index标识
on-success图片上传成功时触发(data, index, lists, name)data服务器返回的数据，index当前操作图片的索引， lists上传文件列表数组，name当前组件的index标识
on-change图片上传后触发，不区分成功与失败(res, index, lists, name)res上传后的消息，index当前操作图片的索引， lists上传文件列表数组，name当前组件的index标识
on-progress图片上传过程中进度变化时触发(res, index, lists, name)res上传图片的进度信息，index当前操作图片的索引， lists上传文件列表数组，name当前组件的index标识
on-error上传图片失败时触发(err, index, lists, name)err上传出错信息，index当前操作图片的索引， lists上传文件列表数组，name当前组件的index标识
on-remove图片移除时触发(index, lists, name)index当前操作图片的索引， lists上传文件列表数组，name当前组件的index标识
on-preview全屏预览图片时触发(url, lists, name)url当前选择图片的url地址， lists上传文件列表数组，name当前组件的index标识

Copyright © 2022~2025 图鸟UI