# tui-upload 图片上传开源组件

介绍

图片上传，支持对单张图片大小限制，支持限制上传图片类型。

特别说明

如果使用组件内默认方法上传，图片上传成功后默认接口返回数据格式以及必要的参数如下：

{
	"code":100,
	"msg":"成功",
	"url":"https://thorui.cn/public/8aa6a3cb5f8b439db77ba1d14f51b22a.png"
}

如果 code % 100 === 0 则表示上传成功，否则为上传失败，如果需要自定义返回数据格式请根据组件内提示修改。

TIP

小程序端如果无法唤起选择图片弹框 (opens new window)，请检查是否更新了隐私策略 (opens new window)。

# 引入

# uni-app引入

第一种，手动引入（可全局引入）

import tuiUpload from "@/components/thorui/tui-upload/tui-upload"
export default {
	components:{
		tuiUpload
	}
}

第二种，开启easycom组件模式，如果不了解如何配置，可先查看官网文档 (opens new window)。

# uni-app版本平台差异说明

App-Nvue	App-vue	H5	微信小程序	支付宝小程序	百度小程序	字节小程序	QQ小程序
升级中	✓	✓	✓	✓	✓	✓	✓

# 微信小程序引入（可在app.json中全局引入）

{
  "usingComponents": {
    "tui-upload": "/components/thorui/tui-upload/tui-upload"
  }
}

# 代码演示

部分功能演示，具体可参考示例程序以及文档API。

基础使用

value 属性为初始化图片路径，serverUrl 属性为上传接口地址，当接口地址为空时，直接返回本地图片地址。

<!--uni-app-->
<tui-upload :value="value" :serverUrl="serverUrl" @complete="result" @remove="remove"></tui-upload>

// data 数据 及 方法
export default {
  data() {
  	return {
  		imageData: [],
  		//上传接口地址
  		serverUrl: "https://api.thorui.cn/",
  		value:[] //初始化图片
  	}
  },
  onLoad() {
  	setTimeout(()=>{
  		this.value=['https://thorui.cn/images/index/logo.png']
  	},200)
  },
  methods: {
  	result: function(e) {
  		console.log(e)
  		this.imageData = e.imgArr;
  	},
  	remove: function(e) {
  		//移除图片
  		console.log(e)
  		let index = e.index
  	}
  }
}

<!--微信小程序-->
<tui-upload value="{{value}}" serverUrl="{{serverUrl}}" bindcomplete="result" bindremove="remove"></tui-upload>

// data 数据 及 方法
Page({
  data: {
    imageData: [],
    //上传接口地址，此处需换成自己的接口地址，示例接口地址已关闭
    serverUrl: "https://api.thorui.cn/upload/uploadFile",
    value:[] //初始化图片
  },
   onLoad(){
    setTimeout(()=>{
  	 this.setData({
  	   value:['https://thorui.cn/images/index/logo.png']
  	 })
     },200)
  },
  result: function(e) {
  	console.log(e)
  	this.setData({
  	  imageData: e.detail.imgArr
  	})
   },
   remove: function(e) {
  	//移除图片
  	console.log(e)
  	let index = e.detail.index
   }
})

// Make sure to add code blocks to your code group

传入一个返回Promise的文件上传的函数

该方法需自行处理上传，组件内会返回上传图片对象信息，如果有特殊处理需求的可使用此方法进行上传，根据自身需求灵活调整。

<!--uni-app-->
<tui-upload ref="uploadRef" @complete="complete" @reupload="reUpload"></tui-upload>
<tui-button bold type="gray-primary" btn-size="medium" @click="upload" margin="30rpx 0">上传</tui-button>

// data 数据 及 方法
export default {
  data() {
  	return {
  		//上传接口地址，此处需换成自己的接口地址，示例接口地址已关闭
  		serverUrl: "https://api.thorui.cn/upload/uploadFile",
  		imageList: []
  	}
  },
  methods: {
  	//以下为调用upload 方法上传示例
  	//注：上传成功或失败处理，请按照下方示例返回(resolve, reject)信息，请勿修改格式
  	uploadImg(file) {
  		//上传的文件信息
  		console.log('组件内返回的文件信息', file)
  		// 文件上传的函数，返回一个promise
  		//上传成功后返回上传后的图片地址，上传失败则返回false即可
  		return new Promise((resolve, reject) => {
  			//调用api上传，所有需要参数自行补充【上传自行实现，便于扩展】
  			uni.uploadFile({
  				//请换成真实的上传接口地址，示例接口已关闭
  				url: this.serverUrl,
  				name: 'file',
  				// header: {},
  				// formData:{},
  				filePath: file.path,
  				success: (res) => {
  					//上传成功后，将图片地址返回
  					//此处逻辑自行根据接口返回判断
  					console.log(res)
  					if (true) {
  						//返回上传成功后的图片地址，根据实际接口返回处理数据 
  						const data = JSON.parse(res.data.replace(/\ufeff/g, "") || "{}")
  						let url = data.data.url
  						//上传成功后务必返回图片地址信息
  						resolve(url)
  					} else {
  						//上传失败
  						reject(false)
  					}
  				},
  				fail: (err) => {
  					//上传失败
  					console.log(err)
  					reject(false)
  				}
  			})
  		})
  	},
  	upload() {
  		if(this.imageList.length===0){
  			this.tui.toast('请选择图片！')
  			return;
  		}
  		//调用upload 方法上传，并传入函数，初始上传时勿传入索引值
  		this.$refs.uploadRef && this.$refs.uploadRef.upload(this.uploadImg)
  	},
  	//重新上传
  	reUpload(e) {
  		//当前上传按钮索引值
  		console.log(e.index)
  		//调用upload 方法上传，并传入函数，且此时需要传入index值
  		this.$refs.uploadRef && this.$refs.uploadRef.upload(this.uploadImg, e.index)
  	},
  	complete(e) {
  		console.log(e)
  		this.imageList = e.imgArr
  	}
  }
}

<!--微信小程序-->
<tui-upload id="uploadRef" bindcomplete="complete" bindreupload="reUpload"></tui-upload>
<tui-button bold type="gray-primary" btn-size="medium" bindclick="upload" margin="30rpx 0">上传</tui-button>

let uploadRef;
Page({
  data: {
   //上传接口地址，此处需换成自己的接口地址，示例接口地址已关闭
    serverUrl: "https://api.thorui.cn/upload/uploadFile",
    imageList: []
  },
  onReady(){
    uploadRef = this.selectComponent('#uploadRef')
  },
  //以下为调用upload 方法上传示例
  uploadImg(file) {
    //上传的文件信息
    console.log('组件内返回的文件信息', file)
    // 文件上传的函数，返回一个promise
    //上传成功后返回上传后的图片地址，上传失败则返回false即可
    return new Promise((resolve, reject) => {
      //调用api上传，所有需要参数自行补充【上传自行实现，便于扩展】
      wx.uploadFile({
        //请换成真实的上传接口地址，示例接口已关闭
        url: this.data.serverUrl,
        name: 'file',
        // header: {},
        // formData:{},
        filePath: file.path,
        success: (res) => {
          //上传成功后，将图片地址返回
          //此处逻辑自行根据接口返回判断
          console.log(res)
          if (true) {
            //返回上传成功后的图片地址，根据实际接口返回处理数据 
            const data = JSON.parse(res.data.replace(/\ufeff/g, "") || "{}")
            let url = data.data.url
            resolve(url)
          } else {
            //上传失败
            reject(false)
          }
        },
        fail: (err) => {
          //上传失败
          console.log(err)
          reject(false)
        }
      })
    })
  },
  upload() {
    if(this.data.imageList.length===0){
      wx.showToast({
        title: '选择图片！',
        icon:'none'
      })
      return;
    }
    //调用upload 方法上传，并传入函数，初始上传时勿传入索引值
    uploadRef && uploadRef.upload(this.uploadImg)
  },
  //重新上传
  reUpload(e) {
    //当前上传按钮索引值
    console.log(e.detail.index)
    //调用upload 方法上传，并传入函数，且此时需要传入index值
    uploadRef && uploadRef.upload(this.uploadImg, e.detail.index)
  },
  complete(e) {
    console.log(e.detail)
    this.data.imageList = e.detail.imgArr
  }
})

// Make sure to add code blocks to your code group

# Slots

插槽名称	说明
default V2.8.0+	自定义选择框加号，小程序端需要将custom属性设置为true

# Props

属性名	类型	说明	默认值
width V1.6.2+	[Number,String]	展示图片的宽度，单位rpx	218
height V1.6.2+	[Number,String]	展示图片的高度，单位rpx	218
value	Array<String>	初始化图片路径	[ ]
radius V2.8.0+	[Number,String]	选择框与图片圆角值，单位rpx	0
background V2.8.0+	String	选择框背景颜色	#F7F7F7
borderColor V2.8.0+	String	选择框边框颜色	transparent
borderSytle V2.8.0+	String	选择框边框样式类型，可选值：solid、dashed、dotted	dashed
delColor V2.8.0+	String	删除图标背景色	#EB0909
delConfirm V1.7.2+	Boolean	删除图片前是否弹框确认	false
forbidDel	Boolean	禁用删除	false
delTrigger V2.9.6+	Boolean	删除图片是否触发 complete 事件	true
addColor V2.8.0+	String	添加图标颜色	#888
addSize V2.8.0+	[Number,String]	添加图标字体大小，单位rpx	68
custom V2.8.0+	Boolean	是否自定义加号图标，结合插槽使用，仅小程序端需要设置	false
forbidAdd	Boolean	禁用添加	false
serverUrl	String	服务器接口地址。当接口地址为空时，直接返回本地图片地址	""
limit	Number	限制数	9
sizeType	Array<String>	original 原图，compressed 压缩图，默认二者都有	['original', 'compressed']
sourceType	Array<String>	album 从相册选图，camera 使用相机，默认二者都有。如需直接开相机或直接选相册，请只使用一个选项	['album', 'camera']
imageFormat	Array<String>	上传图片类型，默认为空数组，不限制，格式:['jpg','png','gif']	[ ]
size	Number	单张图片大小限制 MB	4
fileKeyName	String	文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容	file
header	Object	HTTP 请求 Header, header 中不能设置 Referer	{ }
formData	Object	HTTP 请求中其他额外的 form data	{ }
params V1.6.1	[Number, String]	自定义参数，触发事件时回传	0

# Events

注：uni-app端绑定事件使用@前缀，如@complete；微信小程序原生使用bind前缀，如bindcomplete

事件名	说明	回调参数
complete	上传完成事件	{ //上传状态 1-成功 2-上传中 3-失败 status:Number, //图片信息 imgArr:Array //自定义参数 params: params //是否手动上传 manual: false }
remove	删除图片，回传index索引	{ index:Number, params: params //自定义参数 }
reuploadV2.9.1	上传失败时点击重新上传按钮事件，回传index索引	{ index:Number }

# Methods

uni-app通过ref (opens new window) 来注册组件引用信息，微信小程序通过 this.selectComponent 获取子组件的实例对象，如何调用方法详见进阶用法介绍。

方法名	说明	传入参数
uploadAllImageV1.6.1	当属性serverUrl传空时，父级可调用该方法一次性上传所有图片	serverUrl(服务器接口地址)
uploadV2.9.1	父级可调用该方法进行上传图片，传入一个返回Promise的文件上传的函数，serverUrl属性请勿传值	upload(callback, index)

upload(callback, index) : 
// callback : 返回Promise的文件上传的函数，参考示例中 uploadImg 方法
// index 当前上传图片所在索引【仅上传失败点击重新上传按钮时传入使用，初始上传请勿传入此参数】

uploadImg(file) 
//upload 方法的callback参数，其中 uploadImg 名称可自行定义

//file：组件内调用方法回传参数，当前上传的文件对象信息
//console.log('组件内返回的文件信息', file)

// 具体使用请参考上方示例

# 预览

请以移动端效果为准，touch事件目前尚未在PC端做兼容。

# 特别说明

该组件为 开源组件，uni-app版所有用户均可免费使用。
微信小程序原生版仅开源至v1.4.2，后续版本需开通会员才可获取使用。

# 线上程序扫码预览


ThorUI组件库小程序码	H5二维码	ThorUI示例小程序码

← tui-collapse 折叠面板 tui-skeleton 骨架屏 →