UploadPreview API文档

UploadPreview

                            
        var uploader = new UploadPreview({
            swf: "Uploader.swf",//Uploader.swf文件的路径
            url: "upload.php",//图片上传到后端的地址
            previewInfo: {//预览参数配置
                previewWrap: ".file-list"//包裹所有预览图片的父级元素
            },
            btns: {//按钮配置
                // 指定选择文件的按钮容器，选择器支持 id, class, dom。
                chooseBtn: document.getElementById("choose_file"),
                //选择文件按钮显示的文字
                chooseBtnText: "选择图片",
            }
       });
                            
                        

效果演示 新标签查看

参数配置

• swf{string} [必填] [默认: "Uploader.swf"] Uploader.swf文件的路径，如果该路径填写不正确则在IE9及以下浏览器不能预览及上传文件！
• url{string} [必填] [默认: "upload.php"] 文件上传到后端的URL
• fileVal{string} [可选] [默认: "file"] 文件上传域的name，即后端接收文件的名称
• method{string} [可选] [默认: "post"] 上传文件时的请求类型
• pictureOnly{Boolean} [可选] [默认: true] 是否只能选择图片，若设置为true则用户在选择文件时就只能选择图片，不能选择其他类型的文件。若设置为false则允许用户选择其他类型的文件 设置了pictureOnly为true后，设置accept无效
• multiple{Boolean} [可选] [默认: true] 是否允许选择、上传多张图片
• auto{Boolean} [可选] [默认: false] 是否自动上传文件，若设置为true则在用户选定文件后立即上传该文件
• datas{Object} [可选] [默认: null] 上传时需要给文件添加的额外参数，若设置了参数则每一个文件在上传时都会将datas里面的数据传递给后台
• header{Object} [可选] [默认: {}] 上传时携带给后台的自定义header
• threads{int} [可选] [默认: 3] 上传并发数。允许同时最大上传进程数。
• previewInfo预览框相关配置
  • width {int} [可选] [默认: -1] 预览框的宽度，。如果不设置或设置为-1，则默认为预览框渲染的宽度
  • height{int} [可选] [默认: -1] 预览框的高度度，如果不设置或设置为-1，则默认为预览框渲染的高度
  • viewImgHorizontal {Boolean} [可选] [默认: true] 预览图对于预览框是否水平垂直居中，如果值为false则预览图的position默认为static， 如果值为true则预览图的position为absolute。最终它的css为

                                                
            ._filelist .preview-box img{
                position: aboslute;
                top: 50%;
                left: 50%;
                margin-top: -图片自身高度的一半;
                margin-left: -图片自身宽度的一半;
            }
                                                
                                            

  • previewClass{string} [可选] [默认: ""] 需要添加在预览框上的class类名，
  • previewElement{string} [可选] [默认: div] 预览框的元素类型
  • showToolBtn{Boolean} [可选] [默认: true] 是否在预览框中显示工具按钮，默认为true。工具按钮包括左旋转、右旋转、删除，如果选择的文件不是图片则只有删除按钮。如果设置为true，则当鼠标经过预览框时工具按钮会显示，离开时自动隐藏
  • new toolBtnShowOnUpload{Boolean} [可选] [默认: false] 工具按钮在图片上传成功后（请求成功，并不代表图片真正已经存储到服务器了）是否显示，默认为false。如果图片上传完成后，你要实现点击"删除"按钮发送一条删除图片的ajax请求，然后删除图片的效果，那么可以设置这个参数为true
  • onlyDel{Boolean} [可选] [默认: false] 工具按钮中是否只生成"删除"按钮
  • previewWrap{Selector、dom、jQuery Object} [必填] [默认: null] 包裹预览框的父级元素，该参数为必填项，如果不填写则生成的预览框显示不了
  • new errorTipShow{boolean} [可选] [默认: true] 图片上传失败后是否显示上传失败的提示，默认为显示
  • errorMsg{string} [可选] [默认: "上传失败,"] 上传请求失败时的提示信息，如下图白色圈起的部分
    
  • delBtn{string} [可选] [默认: "删除"] 工具按钮中"删除"按钮的文字，若值为-1则不会创建该按钮，如下图白色部分
    
  • retryBtn{string} [可选] [默认: "重试"] 工具按钮中"重试"按钮的文字，若值为-1则不会创建该按钮，如下图白色部分
    
  • changeUploadBtnText{Boolean} [可选] [默认: true] 在上传过程中是否改变"开始上传"按钮的文字，如果按钮文字从"开始上传"变成了"暂停上传"，再次点击按钮就会暂停上传。如果文字从"暂停上传"变成了"继续上传"，再次点击按钮就会继续上传
  • pauseText{string} [可选] [默认: "暂停上传"] 该参数必须在changeUploadBtnText参数为true时才会有效。当"开始上传"按钮文字从"开始上传"变为"暂停上传"时，"暂停上传"文字就是使用 pauseText
  • continueText{string} [可选] [默认: "暂停上传"] 该参数必须在changeUploadBtnText参数为true时才会有效。当"开始上传"按钮文字从"暂停上传"变为"继续上传"时，"继续上传"文字就是使用 continueText
• new drag拖拽上传相关配置
  • dnd{Selector、dom、jQuery Object} [必填] [默认: null] 如果不传递则不会启动拖拽上传功能
  • disableGlobalDnd{boolean} [可选] [默认: false] 是否禁掉整个页面的拖拽功能，如果不禁用，图片拖进来的时候会默认被浏览器打开。
  • paste{Selector、dom、jQuery Object} [可选] [默认: null] 指定监听paste事件的容器，如果不指定，不启用此功能。此功能为通过粘贴来添加截屏的图片。建议设置为document.body.
• btns按钮相关设置
  • chooseBtn{Selector、dom、jQuery Object} [必填] [默认: null] 选择文件的按钮
  • chooseBtnText{string} [可选] [默认: "选择图片"] 选择文件按钮的文字
  • uploadBtn{Selector、dom、jQuery Object} [可选] [默认: null] 上传文件的按钮
  • retryBtn{Selector、dom、jQuery Object} [可选] [默认: null] 重新上传的按钮
  • chooseBtnCanUseOnFinish{Boolean} [可选] [默认: true] 当所有文件上传结束后"选择文件"按钮是否可用 查看demo
  • uploadBtnCanUsOnFinish{Boolean} [可选] [默认: true] 当所有文件上传结束后"开始上传"按钮是否可用 查看demo
• ignore指定排除哪些类型的文件 查看demo
  • extensions{string} [可选] [默认: ""] 排除指定后缀名的文件，多个后缀名按,隔开。如：js,html,css、.php,.class,.cs
  • mimeTypes{string} [可选] [默认: ""] 排除指定MIME类型的文件，多个MIME类型名按,隔开。如：application/A2L,application/pdf
• accept特别允许上传哪些类型的文件 查看demo
  • extensions{string} [可选] [默认: ""] 指定允许特别上传哪些后缀名的文件，多个后缀名按,隔开。如：js,html,css、.php,.class,.cs
  • mimeTypes{string} [可选] [默认: ""] 指定允许特别上传哪些MIME类型的文件，多个MIME类型名按,隔开。如：application/A2L,application/pdf
  • 设置了pictureOnly为true后，设置accept无效
• sendAsBlob{Boolean} [可选] [默认: false] 是否以二进制流的形式发送
• compress{Boolean} [可选] [默认: false] 图片在上传前是否进行压缩，默认不进行压缩
• duplicate{Boolean} [可选] [默认: false] 单个文件是否可以重复多次上传，即一个文件上传成功后是否可以再次上传
• maxFileNum{int} [可选] [默认: 50] 最大上传文件个数
• maxFileSize{int} [可选] [默认: 5242880(B)] 单个文件体积最大大小，默认5242880 Bite，即5M
• maxFileTotalSize{int} [可选] [默认: 524288000(B)] 所有文件体积最大大小，默认524288000 Bite，即500M

事件说明

upload

• uploadPreview.upload() => 当前UploadPreview对象

上传文件

                            
        var uploadPreview = new UploadPreview({...});

        $("#uploadBtn").on("click", function (){
            uploadPreview.upload();
        });
                            
                        

stop

• uploadPreview.stop() => 当前UploadPreview对象

暂停上传，调用stop()后还在上传队列中等待上传的文件将不会继续上传，已经发送的请求不会停止

                            
        var uploadPreview = new UploadPreview({...});

        $("#pauseBtn").on("click", function (){
            uploadPreview.stop();
        });
                            
                        

retry

• uploadPreview.retry() => 当前UploadPreview对象
• uploadPreview.retry( file ) => 当前UploadPreview对象

参数：

• file{WUFile} [可选]

重新上传，当文件上传出错后调用retry()方法可以重新上传之前上传出错或失败的文件。不传参数默认重新上传所有上传出错或 失败的文件，如果传递了参数并且参数是一个WUFile对象则重新上传指定的文件

                            
        var uploadPreview = new UploadPreview({...});

        $("#retryBtn").on("click", function (){
            uploadPreview.retry();
        });
                            
                        

destroy

• uploadPreview.destroy() => undefined

销毁webuploader实例

delete

• uploadPreview.delete(WUFileOrId) => 当前UploadPreview对象

删除指定文件。WUFileOrId可以是一个WUFile(文件)对象，也可以文件的id，id的值一般为：WU_FILE_x，x为数字。 调用delete()方法后会自动调用传递的fileDequeued参数

refresh

• uploadPreview.refresh() => 当前UploadPreview对象
• uploadPreview.refresh(btn) => 当前UploadPreview对象

• btn {dom、jQuery Object} [可选]

重新渲染"选择文件"按钮。有时候我们的业务场景可能是在模态窗中选择文件，而模态窗默认是display: none的，在这种情况下 如果在模态窗显示前初始化了webuploader(即new UploadPreview(...))，则可能会出现"选择文件"按钮用不了的情况。如果是这种情况 那么可以调用refresh()对按钮再次进行渲染 查看demo

                            
        var uploadPreview = new UploadPreview({...});

        $("#refresh").on("click", function (){
            uploadPreview.refresh();
            //uploadPreview.refresh(document.getElementById("chooseBtn"));
        });
                            
                        

disable

• uploadPreview.disable() => 当前UploadPreview对象

禁用"选择文件"按钮。禁用按钮后会给"选择文件"按钮添加.webuploader-pick-disableclass 类

enable

• uploadPreview.enable() => 当前UploadPreview对象

启用"选择文件"按钮

setData

• uploadPreview.setData() => 当前UploadPreview对象

• WUFile {WUFile} [必填] 该参数可以为WUFile对象或WUFile对象的id，传递这个参数后就可以给该文件设置额外参数
• data {Object} [必填] 该参数为需要添加到文件中的额外参数，该参数必须为一个对象，并且不能是伪数组、数组或window

给指定文件单独的设置需要上传到服务器端的额外参数。有时候我们在开发类似用户资料填写的功能的时候，需要先提交用户填写的文字信息，提交 完成后服务器端返回一个id，然后再上传图片的时候将这个id也传递给后端。setData()方法就是为了解决这一需求的。 查看demo

setHeader

• uploadPreview.setHeader() => 当前UploadPreview对象

• header {Object} [必填] 该参数必须为一个对象，value必须为英文。

在上传文件之前动态的设置header信息。 查看demo

getFiles

• uploadPreview.getFiles() => 包含所有已选择的文件的对象，对象的键为WUFile的id，值为选择的文件(WUFile)

获取用户选择的所有文件

getStats

• uploadPreview.getStats() => 包含以下信息的对象
• successNum上传成功的文件数
• progressNum上传中的文件数
• cancelNum被删除的文件数
• invalidNum无效的文件数
• uploadFailNum上传失败的文件数
• queueNum还在队列中的文件数
• interruptNum被暂停的文件数

获取文件统计信息

getFileLength

• uploadPreview.getFileLength() => 当前用户选择的文件数量

获取选择的文件数量

calculateWh

• UploadPreview.calculateWh() => 返回一个包含width、height的对象

• viewW {int} [必填|可选] 预览的宽度。如果不知道预览的宽度直接赋值-1.如果viewW为-1，则viewH必须大于-1
• viewH {int} [必填|可选] 预览的宽度。如果不知道预览的高度直接赋值-1.如果viewH为-1，则viewW必须大于-1
• imgW{int} [必填] 图片或真实的宽度。
• imgH{int} [必填] 图片或真实的高度。

等比例计算宽高

setProgressWidth

• uploadPreview.setProgressWidth(ele,width) => 返回传递的ele

• ele {Selector、jQuery Object} [必填] 预览框
• width {int} [必填] 进度条的长度

设置预览框中进度条的长度

案例

1. 上传头像、logo案例
2. 反复上传案例
3. 自定义上传文件类型案例
4. 自定义预览图样式案例
5. 自定义header案例
6. 排除指定文件类型案例
7. 动态渲染按钮案例
8. 动态添加额外参数案例