TnImageUpload-图片上传

图片上传组件用于上传图片场景。

组件位置

nodeuni_modules

typescript

import TnImageUpload from '@tuniao/tnui-vue3-uniapp/components/image-upload/src/image-upload.vue'

import TnImageUpload from '@tuniao/tnui-vue3-uniapp/components/image-upload/src/image-upload.vue'

typescript

import TnImageUpload from '@/uni_modules/tuniaoui-vue3/components/image-upload/src/image-upload.vue'

import TnImageUpload from '@/uni_modules/tuniaoui-vue3/components/image-upload/src/image-upload.vue'

平台差异说明

App(vue)	H5	微信小程序	支付宝小程序	...
√	√	√	√	适配中

基础使用

通过v-model绑定已上传(成功状态)的图片 Url 地址
通过disabled设置是否禁止上传状态，在禁止上传状态下，点击图片不会触发上传事件、点击删除按钮不会触发删除事件

vue

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

const imageList = ref<string[]>([
  'http://192.168.3.23:8090/uploads/images/1683602434042.jpeg',
])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload v-model="imageList" :action="actionUrl" />
</template>

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

const imageList = ref<string[]>([
  'http://192.168.3.23:8090/uploads/images/1683602434042.jpeg',
])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload v-model="imageList" :action="actionUrl" />
</template>

使用组件集成的上传方法

使用TnImageUpload组件内置的上传方法需要配置action才能使用，action为上传图片的接口地址

配置name设置服务器接受文件的字段名称，默认值为file

使用TnImageUpload组件内置的上传方法需要服务器在上传成功的时候返回以下格式的数据，并且为json格式

json

{
  "code": 200,
  "data": {
    "errCode": 0,
    "url": "图片地址"
  }
}

{
  "code": 200,
  "data": {
    "errCode": 0,
    "url": "图片地址"
  }
}

vue

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload v-model="imageList" :action="actionUrl" />
</template>

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload v-model="imageList" :action="actionUrl" />
</template>

自定义处理接口返回的字段信息

为了兼容各种情况，TnImageUpload组件提供了custom-upload-callback参数设置自定义处理接口返回的字段信息

该参数为一个函数，函数接受一个参数，参数为接口返回的数据，函数需要返回图片的url地址或者是一个携带图片地址的Promise对象

nodeuni_modules

vue

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

import type { ImageUploadCustomCallbackFunction } from '@tuniao/tnui-vue3-uniapp'

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

// const uploadCallbackHandle: ImageUploadCustomCallbackFunction = (
//   data: UniApp.UploadFileSuccessCallbackResult
// ) => {
//   const resData = JSON.parse(data.data)
//   return Promise.resolve(resData.data.url)
// }

const uploadCallbackHandle: ImageUploadCustomCallbackFunction = (
  data: UniApp.UploadFileSuccessCallbackResult
) => {
  const resData = JSON.parse(data.data)
  return resData.data.url
}
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :custom-upload-callback="uploadCallbackHandle"
  />
</template>

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

import type { ImageUploadCustomCallbackFunction } from '@tuniao/tnui-vue3-uniapp'

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

// const uploadCallbackHandle: ImageUploadCustomCallbackFunction = (
//   data: UniApp.UploadFileSuccessCallbackResult
// ) => {
//   const resData = JSON.parse(data.data)
//   return Promise.resolve(resData.data.url)
// }

const uploadCallbackHandle: ImageUploadCustomCallbackFunction = (
  data: UniApp.UploadFileSuccessCallbackResult
) => {
  const resData = JSON.parse(data.data)
  return resData.data.url
}
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :custom-upload-callback="uploadCallbackHandle"
  />
</template>

vue

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

import type { ImageUploadCustomCallbackFunction } from '@/uni_modules/tuniaoui-vue3'

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

// const uploadCallbackHandle: ImageUploadCustomCallbackFunction = (
//   data: UniApp.UploadFileSuccessCallbackResult
// ) => {
//   const resData = JSON.parse(data.data)
//   return Promise.resolve(resData.data.url)
// }

const uploadCallbackHandle: ImageUploadCustomCallbackFunction = (
  data: UniApp.UploadFileSuccessCallbackResult
) => {
  const resData = JSON.parse(data.data)
  return resData.data.url
}
</script>

<template>
  <tn-image-upload
    v-model="imageList"
    :action="actionUrl"
    :custom-upload-callback="uploadCallbackHandle"
  />
</template>

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

import type { ImageUploadCustomCallbackFunction } from '@/uni_modules/tuniaoui-vue3'

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

// const uploadCallbackHandle: ImageUploadCustomCallbackFunction = (
//   data: UniApp.UploadFileSuccessCallbackResult
// ) => {
//   const resData = JSON.parse(data.data)
//   return Promise.resolve(resData.data.url)
// }

const uploadCallbackHandle: ImageUploadCustomCallbackFunction = (
  data: UniApp.UploadFileSuccessCallbackResult
) => {
  const resData = JSON.parse(data.data)
  return resData.data.url
}
</script>

<template>
  <tn-image-upload
    v-model="imageList"
    :action="actionUrl"
    :custom-upload-callback="uploadCallbackHandle"
  />
</template>

自定义图片上传方法

TnImageUpload组件不仅提供了可自定义处理回调函数的方法，还提供了可自定义上传方法的方法

通过设置custom-upload-handler参数，可以自定义上传图片的方法，该参数为一个函数，函数接受一个参数，参数为UniApp.ChooseImageSuccessCallbackResultFile | File对象，函数需要返回图片的url地址或者是一个携带图片地址的Promise对象

在非 H5 端参数为``UniApp.ChooseImageSuccessCallbackResultFile对象，在 H5 端参数为File`对象

设置custom-upload-handler参数后，内置的上传的图片上传方法将失效

nodeuni_modules

vue

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

import type {
  ImageUploadCustomFunction,
  ImageUploadFile,
} from '@tuniao/tnui-vue3-uniapp'

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

const uploadHandle: ImageUploadCustomFunction = (file: ImageUploadFile) => {
  return new Promise((resolve, reject) => {
    const url = (file as UniApp.ChooseImageSuccessCallbackResultFile).path
    uni.uploadFile({
      url: actionUrl,
      filePath: url,
      name: 'file',
      success: (res) => {
        const data = JSON.parse(res.data)
        resolve(data.data.url)
      },
      fail: (err) => {
        reject(err)
      },
    })
  })
}
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :custom-upload-handler="uploadHandle"
  />
</template>

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

import type {
  ImageUploadCustomFunction,
  ImageUploadFile,
} from '@tuniao/tnui-vue3-uniapp'

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

const uploadHandle: ImageUploadCustomFunction = (file: ImageUploadFile) => {
  return new Promise((resolve, reject) => {
    const url = (file as UniApp.ChooseImageSuccessCallbackResultFile).path
    uni.uploadFile({
      url: actionUrl,
      filePath: url,
      name: 'file',
      success: (res) => {
        const data = JSON.parse(res.data)
        resolve(data.data.url)
      },
      fail: (err) => {
        reject(err)
      },
    })
  })
}
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :custom-upload-handler="uploadHandle"
  />
</template>

vue

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

import type {
  ImageUploadCustomFunction,
  ImageUploadFile,
} from '@/uni_modules/tuniaoui-vue3'

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

const uploadHandle: ImageUploadCustomFunction = (file: ImageUploadFile) => {
  return new Promise((resolve, reject) => {
    const url = (file as UniApp.ChooseImageSuccessCallbackResultFile).path
    uni.uploadFile({
      url: actionUrl,
      filePath: url,
      name: 'file',
      success: (res) => {
        const data = JSON.parse(res.data)
        resolve(data.data.url)
      },
      fail: (err) => {
        reject(err)
      },
    })
  })
}
</script>

<template>
  <tn-image-upload
    v-model="imageList"
    :action="actionUrl"
    :custom-upload-handler="uploadHandle"
  />
</template>

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

import type {
  ImageUploadCustomFunction,
  ImageUploadFile,
} from '@/uni_modules/tuniaoui-vue3'

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

const uploadHandle: ImageUploadCustomFunction = (file: ImageUploadFile) => {
  return new Promise((resolve, reject) => {
    const url = (file as UniApp.ChooseImageSuccessCallbackResultFile).path
    uni.uploadFile({
      url: actionUrl,
      filePath: url,
      name: 'file',
      success: (res) => {
        const data = JSON.parse(res.data)
        resolve(data.data.url)
      },
      fail: (err) => {
        reject(err)
      },
    })
  })
}
</script>

<template>
  <tn-image-upload
    v-model="imageList"
    :action="actionUrl"
    :custom-upload-handler="uploadHandle"
  />
</template>

设置最大允许上传的图片数量

通过limit参数可以设置最大允许上传的图片数量，默认值为9

如果已上传的图片数量超过了limit的值，将不会触发上传事件

vue

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload v-model="imageList" :action="actionUrl" :limit="3" />
</template>

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload v-model="imageList" :action="actionUrl" :limit="3" />
</template>

设置最大允许上传的图片大小和图片类型

通过max-size参数可以设置最大允许上传的图片大小，默认值为10 * 1024 * 1024，单位为byte

通过extensions参数可以设置最大允许上传的图片类型，默认值为['jpg','jpeg','png','gif','webp','ico']

vue

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :max-size="3 * 1024 * 1024"
    :extensions="['jpg', 'jpeg', 'png']"
  />
</template>

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :max-size="3 * 1024 * 1024"
    :extensions="['jpg', 'jpeg', 'png']"
  />
</template>

隐藏错误提示信息弹框

通过show-error-tips参数可以设置隐藏错误提示信息弹框，默认值为true

vue

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :show-error-tips="false"
  />
</template>

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :show-error-tips="false"
  />
</template>

隐藏内置的上传进度显示

通过show-upload-progress参数可以设置内置的上传进度显示，默认值为true

vue

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :show-upload-progress="false"
  />
</template>

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

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'
</script>

<template>
  <TnImageUpload
    v-model="imageList"
    :action="actionUrl"
    :show-upload-progress="false"
  />
</template>

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

通过修改uploadBtn插槽可以自定义上传按钮，在使用自定义上传按钮后需要手动调用chooseFile方法选择图片

通过修改uploadImage插槽可以自定义显示列表的样式，插槽返回对应上传对象的数据

nodeuni_modules

vue

<script lang="ts" setup>
import { ref } from 'vue'
import type { TnImageUploadInstance } from '@tuniao/tnui-vue3-uniapp'

const imageUploadRef = ref<TnImageUploadInstance>()

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

const chooseFile = () => {
  imageUploadRef.value?.chooseFile()
}
</script>

<template>
  <TnImageUpload ref="imageUploadRef" v-model="imageList" :action="actionUrl">
    <template #uploadBtn>
      <view class="upload-new-btn tn-flex-center" @tap.stop="chooseFile">
        请上传身份证
      </view>
    </template>
    <template #uploadImage="{ data }">
      <image
        style="width: 100%; height: 260rpx"
        :src="data.url"
        mode="aspectFill"
      />
    </template>
  </TnImageUpload>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { TnImageUploadInstance } from '@tuniao/tnui-vue3-uniapp'

const imageUploadRef = ref<TnImageUploadInstance>()

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

const chooseFile = () => {
  imageUploadRef.value?.chooseFile()
}
</script>

<template>
  <TnImageUpload ref="imageUploadRef" v-model="imageList" :action="actionUrl">
    <template #uploadBtn>
      <view class="upload-new-btn tn-flex-center" @tap.stop="chooseFile">
        请上传身份证
      </view>
    </template>
    <template #uploadImage="{ data }">
      <image
        style="width: 100%; height: 260rpx"
        :src="data.url"
        mode="aspectFill"
      />
    </template>
  </TnImageUpload>
</template>

vue

<script lang="ts" setup>
import { ref } from 'vue'
import type { TnImageUploadInstance } from '@/uni_modules/tuniaoui-vue3'

const imageUploadRef = ref<TnImageUploadInstance>()

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

const chooseFile = () => {
  imageUploadRef.value?.chooseFile()
}
</script>

<template>
  <tn-image-upload ref="imageUploadRef" v-model="imageList" :action="actionUrl">
    <template #uploadBtn>
      <view class="upload-new-btn tn-flex-center" @tap.stop="chooseFile">
        请上传身份证
      </view>
    </template>
    <template #uploadImage="{ data }">
      <image
        style="width: 100%; height: 260rpx"
        :src="data.url"
        mode="aspectFill"
      />
    </template>
  </tn-image-upload>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { TnImageUploadInstance } from '@/uni_modules/tuniaoui-vue3'

const imageUploadRef = ref<TnImageUploadInstance>()

const imageList = ref<string[]>([])

const actionUrl = 'http://192.168.3.23:8090/upload/image'

const chooseFile = () => {
  imageUploadRef.value?.chooseFile()
}
</script>

<template>
  <tn-image-upload ref="imageUploadRef" v-model="imageList" :action="actionUrl">
    <template #uploadBtn>
      <view class="upload-new-btn tn-flex-center" @tap.stop="chooseFile">
        请上传身份证
      </view>
    </template>
    <template #uploadImage="{ data }">
      <image
        style="width: 100%; height: 260rpx"
        :src="data.url"
        mode="aspectFill"
      />
    </template>
  </tn-image-upload>
</template>

API

Props

属性名	说明	类型	默认值	可选值
model-value/v-model	已上传图片列表的值	Array<string>	-	-
disabled	禁止图片上传	Boolean	`false`	`true`
action	图片上传地址	String	-	-
name	图片上传的字段名称	String	`file`	-
header	图片上传的`header`, `header` 中不能设置 `Referer`	Object	{}	-
form-data	图片上传 HTTP 请求中其他额外的 `form data`	Object	{}	-
limit	最大允许上传个数	Number	9	-
multiple	允许多选图片	Boolean	`true`	`false`
auto-upload	自动上传	Boolean	`true`	`false`
show-remove	显示删除按钮	Boolean	`true`	`false`
show-error-tips	显示错误提示信息	Boolean	`true`	`false`
show-upload-progress	显示上传进度条	Boolean	`true`	`false`
size-type	上传图片的 SizeType，具体解释参考官网https://uniapp.dcloud.net.cn/api/media/image.html	Array<ImageUploadSizeType>	`['original', 'compressed']`	-
source-type	上传图片的来源，具体解释参考官网https://uniapp.dcloud.net.cn/api/media/image.html	Array<ImageUploadSource>	`['album', 'camera']`	-
max-size	允许上传的最大图片大小，单位为`byte`	Number	`10 * 1024 * 1024`	-
extensions	允许上传的图片类型	Array<string>	`['jpg','jpeg','png', 'gif','webp','ico']`	-
auto-remove-faild-file	自动移除上传失败的文件	Boolean	`false`	`true`
custom-upload-handler	自定义上传函数	`ImageUploadCustomFunction`	-	-
customupload-callback	自定义上传回调处理函数	`ImageUploadCustomCallbackFunction`	-	-
before-upload	上传前的钩子函数	`ImageBeforeUploadFunction`	-	-
before-remove	删除前的钩子函数	`ImageBeforeRemoveFunction`	-	-
validate-event	值发生修改时是否触发表单验证	Boolean	`true`	`false`

Emits

事件名	说明	类型
change	文件列表发生改变时触发	`(value: Array<string>) => void`
oversize-or-no-support	图片超过最大尺寸或者文件不支持时触发	`(file: Array<ImageUploadFile>) => void`
success	图片上传成功回调	`(file: ImageUploadListItem) => void`
fail	图片上传失败回调	`(error: Error, file: ImageUploadListItem) => void`
remove	图片删除成功回调	`(url: string) => void`
preview	图片预览回调	`(url: string) => void`

Expose

函数名	说明	类型
chooseFile	手动选择文件	`() => void`
upload	手动上传文件	`() => void`
retry	重新上传上传失败的文件	`() => void`
clear	清空已上传的文件	`() => void`

Slots

插槽名	说明	返回数据
uploadImage	上传的图片数据	ImageUploadList
uploadBtn	上传按钮内容
addBtn	内部上传按钮内容

ImageUploadListItem

参数	说明	必填
url	图片 url 地址	是
status	上传图片的状态，`ready \| uploading \| done \| failed`	是
progress	上传进度	是
uploadTask	上传对象	-
file	ImageUploadFile	-

ImageUploadSizeType

typescript

type ImageUploadCustomFunction = (
  file: ImageUploadFile
) => Promise<string> | string

type ImageUploadCustomFunction = (
  file: ImageUploadFile
) => Promise<string> | string

ImageUploadCustomCallbackFunction

typescript

ImageUploadCustomCallbackFunction = (
  data: UniApp.UploadFileSuccessCallbackResult
) => Promise<string> | string

ImageUploadCustomCallbackFunction = (
  data: UniApp.UploadFileSuccessCallbackResult
) => Promise<string> | string

ImageBeforeUploadFunction

typescript

ImageBeforeUploadFunction = (file: ImageUploadFile) =>
  boolean | Promise<boolean>

ImageBeforeUploadFunction = (file: ImageUploadFile) =>
  boolean | Promise<boolean>

ImageBeforeRemoveFunction

typescript

ImageBeforeRemoveFunction = (file: ImageUploadListItem) =>
  boolean | Promise<boolean>

ImageBeforeRemoveFunction = (file: ImageUploadListItem) =>
  boolean | Promise<boolean>

ImageUploadFile

typescript

ImageUploadFile = UniApp.ChooseImageSuccessCallbackResultFile | File

ImageUploadFile = UniApp.ChooseImageSuccessCallbackResultFile | File

ImageUploadList

typescript

ImageUploadList = ImageUploadListItem[]

ImageUploadList = ImageUploadListItem[]

TnImageUpload-图片上传 ​

组件位置 ​

平台差异说明 ​

基础使用 ​

使用组件集成的上传方法 ​

自定义处理接口返回的字段信息 ​

自定义图片上传方法 ​

设置最大允许上传的图片数量 ​

设置最大允许上传的图片大小和图片类型 ​

隐藏错误提示信息弹框 ​

隐藏内置的上传进度显示 ​

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

API ​

Props ​

Emits ​

Expose ​

Slots ​

ImageUploadListItem ​

ImageUploadSizeType ​

ImageUploadCustomCallbackFunction ​

ImageBeforeUploadFunction ​

ImageBeforeRemoveFunction ​

ImageUploadFile ​

ImageUploadList ​

TnImageUpload-图片上传

组件位置

平台差异说明

基础使用

使用组件集成的上传方法

自定义处理接口返回的字段信息

自定义图片上传方法

设置最大允许上传的图片数量

设置最大允许上传的图片大小和图片类型

隐藏错误提示信息弹框

隐藏内置的上传进度显示

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

API

Props

Emits

Expose

Slots

ImageUploadListItem

ImageUploadSizeType

ImageUploadCustomCallbackFunction

ImageBeforeUploadFunction

ImageBeforeRemoveFunction

ImageUploadFile

ImageUploadList