Uploader 异步文件上传组件

例子

必须从服务器端浏览demo，demo中使用的服务器端脚本是php。

选择要上传的文件

html结构

                    
                     选择要上传的文件 
                    
                    


                    
                 

非常简单的html结构，一个上传按钮（必须）和一个文件队列（可以不存在）。

生成的dom结构

ajax上传方案（chrome/firefox）

                    
                        选择要上传的文件
                        

                            
                        
                        
                    
                 

flash上传方案（IE）

                    
                        选择要上传的文件
                        

                            
                        
                        
                    
                 

javascript代码

配置下gallery的包路径

                    KISSY.config({
                        packages:[ {
                            name:"gallery",
                            path:"http://a.tbcdn.cn/s/kissy/",
                            charset:"utf-8"
                        } ]
                    });
                

初始化上传组件

                KISSY.use('gallery/form/1.3/uploader/index', function (S, RenderUploader) {
                    new RenderUploader('#J_UploaderBtn', '#J_UploaderQueue',{
                        //服务器端配置
                        serverConfig:{
                            //处理上传的服务器端脚本路径
                            action:"upload.php"
                        },
                        // 文件域
                        name:"Filedata",
                        //用于放服务器端返回的url的隐藏域
                        urlsInputName:"fileUrls"
                    });
                })
                

配置参数说明

参数名	类型	默认值	描述
serverConfig	Object	{action:'', data:{}, dataType:'json'}	服务器端配置，包括最重要的action（路径）配置，data为post到服务器端数据
name	String	Filedata	文件上传域name名，组件会根据这个name值生成一个文件上传input（type="file"）
urlsInputName	String	''	用于存放服务器端返回的文件路径的input（type="hidden"）

例子

选择要上传的文件

增加authConfig配置

                    new RenderUploader('#J_UploaderAuthBtn', '#J_UploaderAuthQueue', {
                        serverConfig:{ action:"upload.php" },
                        name:"Filedata",
                        urlsInputName:"fileUrls",
                        //验证配置
                        authConfig: {
                            require:[true,"必须至少上传一个文件！"],
                            max:[3, "最多上传{max}个文件！"],
                            maxSize:[1000, "文件大小为{size}，文件太大！"],
                            allowRepeat:[false, "该文件已经存在！"],
                            allowExts:[
                                {"desc":"JPG,JPEG,PNG,GIF,BMP", "ext":"*.jpg;*.jpeg;*.png;*.gif;*.bmp"},
                                "不支持{ext}格式的文件上传！"
                            ]
                        }
                    });
                

支持的验证规则

规则名	举例	描述
require	[true,"必须至少上传一个文件！"]	必须至少上传一个文件 上传必须性，默认不打印消息
max	[3, "最多上传{max}个文件！"]	最多上传3个文件，当达到3个文件后按钮会增加禁用样式uploader-button-disabled，用户可以通过这个样式名定制需要的置灰样式。 不推荐隐藏按钮，不可隐藏按钮的父容器。
maxSize	[1000, "文件大小为{size}，文件太大！"]	单文件最大允许上传的文件大小，单位是KB 如果是iframe上传方式，此验证无效
allowRepeat	[false, "该文件已经存在！"]	是否允许多次上传同一个文件 不推荐增加这个验证，比较粗糙，只是根据文件名来做重复判断
allowExts	[ {"desc":"JPG,JPEG,PNG,GIF,BMP", "ext":"*.jpg;*.jpeg;*.png;*.gif;*.bmp"}, "不支持{ext}格式的文件上传！" ]	非常常用的文件格式验证，基本上每个上传都会用到 留意：数组第一个值是个object，desc为文件格式描述，只在IE（flash）下起作用。ext才是真正的文件过滤规则。

监听error事件

监听uploader的error事件即可（V1.2.6），比如下面的代码：

        uploader.on('error', function (ev) {
            var rule = ev.rule, msg = ev.msg,status = ev.status;
            if (rule == 'max') {
                alert(msg);
            }
            if(status === -1){
                alert('前端验证错误');
            }
        });
        

试下demo上传三个文件会出现弹出框提示

手动触发验证

有时我们需要额外调用验证方法，比如提交表单时验证下是不是有至少有一个文件上传。

        $('#J_SubmitAuthDemo').on('click', function (ev) {
            var auth = uploader.get('auth');
            var isPass = auth.testRequire();
            if (isPass) {
                alert('存在上传文件！');
            }else{
                alert('请至少上传一个文件！');
            }
        })
        

先要获取Auth实例，然后调用testRequire()方法。

testMax()可以检验是否达到最大允许上传数。

主题html结构如下：

          

              

                  

                      
                           还可以上传5图片！ 
                          
                      
                  
              
          
        

增加theme配置项

        new RenderUploader('#J_ImageUploaderBtn', '#J_ImageUploaderQueue', {
            theme:"imageUploader",
            urlsInputName:"imgUrlsInput",
            serverConfig:{"action":"./upload.php", "data":{"iid":77010, "fieldId":132338}},
            name:"Filedata",
            authConfig:{
                require:[true, "必须至少上传一个文件！"],
                maxSize:[500, "文件大小为{size}，文件太大！"],
                allowExts:[
                    {"desc":"JPG,JPEG,PNG,GIF,BMP", "ext":"*.jpg;*.jpeg;*.png;*.gif;*.bmp"},
                    "文件格式错误！"
                ],
                max:[5, "最多允许上传五张图片！"]
            }
        });
        

theme:"imageUploader"使用uploader内置图片上传主题imageUploader，此主题会获取服务器返回的url，显示在页面。

imageUploader肯定无法100%满足实际的场景，这时候你可以制作自己的主题，请看《如何制作属于自己的主题（上、下）》，还可以监听uploader的事件做些额外的逻辑处理（但没办法覆盖主题的逻辑）。

如何自定义主题样式？

不加载主题样式，可以如下处理

        new RenderUploader('#J_ImageUploaderBtn', '#J_ImageUploaderQueue', {
            theme:"imageUploader",
            themeConfig:{
                cssUrl:''
            }
        });
        

如何改变主题的模板？

        new RenderUploader('#J_ImageUploaderBtn', '#J_ImageUploaderQueue', {
            theme:"imageUploader",
            themeConfig:{
                fileTpl:
                    '
' +
                    '
' +
                        '' +
                        '
' +
                    '
' +
                    '
' +
                        '
等待上传，请稍候
' +
                        '
' +
                            '
上传中...
' +
                            '
' +
                        '
' +
                            '
上传失败，请重试！
' +
                        '
' +
                    '删除' +
                    '
'
            }
        });
        

选择要上传的文件

服务器端在页面中打印如下数据：

为一个array，文件数据为object，结构跟队列中的file数据保持一致，所以看上去数据有些繁冗。

初始化时增加restoreHook配置项

          new RenderUploader('#J_RestoreUploaderBtn', '#J_RestoreUploaderQueue', {
                serverConfig:{ action:"upload.php" },
                name:"Filedata",
                urlsInputName:"fileUrls",
                restoreHook:"#J_UploaderRestore"
          });
        

好了，组件会自动将数据插入到queue中，并渲染出图片。

示例

选择要上传的文件

初始化组件

        var ru = new RenderUploader('#J_ButtonUploaderBtn', '#J_ButtonUploaderQueue',{
            serverConfig:{"action":"upload.php"},
            name:"Filedata",
            urlsInputName:"fileUrls",
            autoUpload: false,
            multiple:false,
            disabled:true
        });
        

配置说明

参数名	类型	默认值	描述
autoUpload	Boolean	true	是否自动上传，当为false时，可以通过uploader的upload()和uploadFiles()手动上传队列中的文件。
multiple	Boolean	true	是否开启多选支持 如果采用iframe上传，请设置为false
disabled	Boolean	false	是否可用,false为按钮可用

通过设置uploader属性控制按钮

        //对组件的后续操作务必放在init事件内，因为组件时可能需要异步加载模板
        ru.on("init", function (ev) {
            var uploader = ev.uploader;
            $('#J_Disabled').on('change',function(ev){
                var isChecked = $(ev.target).prop('checked');
                uploader.set('disabled',isChecked);
            });
            $('#J_Multiple').on('change',function(ev){
                var isChecked = $(ev.target).prop('checked');
                uploader.set('multiple',isChecked);
            });
            $('#J_UploadAll').on('click',function(){
                uploader.uploadFiles();
            })
        })
        

示例

选择要上传的文件

想要操作队列，就必须先获取queue实例（为uploader的属性），比如下面的代码：

        //uploaderQueueTest为RenderUploader的实例
        uploaderQueueTest.on('init',function(ev){
           var uploader = ev.uploader,
                   queue = uploader.get('queue');
        })
        

下面举例说明常用的方法和属性。

add():向队列添加文件

               $('#J_Add').on('click', function (ev) {
                //测试文件数据
                var testFile = {'name':'test.jpg',
                    'size':2000,
                    'input':{},
                    'file':{'name':'test.jpg', 'type':'image/jpeg', 'size':2000}
                };
                //向队列添加文件
                var file = queue.add(testFile);
                S.log('添加的文件数据为：'+file);
            });
        

remove():删除队列中的文件

               $('#J_DelFirst').on('click', function (ev) {
                    var removeFile = queue.remove(0);
                    S.log('删除的文件数据为：'+removeFile);
                });
        

fileStatus(index, status, args):改变文件状态

默认的主题共有以下文件状态：'waiting'、'start'、'progress'、'success'、'cancel'、'error'

不同的主题拥有的状态情况可能存在差异。

           $('#J_ChangeStatus').on('click', function (ev) {
                queue.fileStatus(0, 'success');
            });
        

clear():删除队列内的所有文件

           $('#J_Clear').on('click', function (ev) {
            queue.clear();
            });
        

files：通过该属性可以获取队列中所有的文件数据

               $('#J_GetAll').on('click', function (ev) {
                    var ids = [],
                            files = queue.get('files');
                    S.each(files, function (file) {
                        ids.push(file.id);
                    });
                    alert('所有文件id：' + ids);
                });
        

getFiles(type):获取指定状态下的文件

           $('#J_GetStatusFileIds').on('click', function (ev) {
                var files = queue.getFiles('waiting'),
                        ids = [];
                S.each(files, function (file) {
                    ids.push(file.id);
                });
                alert('所有等待中的文件id为：' + ids);
            });
        

getIndexs(type):获取等指定状态的文件对应的文件数组索引值组成的数组

getFiles()和getFileIds()的作用是不同的，getFiles()类似过滤数组，获取的是指定状态的文件数据，而getFileIds()只是获取指定状态下的文件对应的在文件数组内的索引值。

           $('#J_GetStatusFilesIndex').on('click', function () {
                var indexs = queue.getIndexs('waiting');
                alert('所有等待中的文件index为：' + indexs);
            })
        

uploader常用方法

upload (index)

上传指定队列索引的文件。

//上传队列中的第一个文件，uploader为Uploader的实例
uploader.upload(0)

uploadFiles (status)

批量上传队列中的指定状态下的文件。

//上传队列中所有等待的文件
uploader.uploadFiles("waiting")

cancel (index)

取消文件上传，当index参数不存在时取消当前正在上传的文件的上传。cancel并不会停止其他文件的上传（对应方法是stop）。

//取消当前正在上传的文件的上传
uploader.cancel();

stop()

停止上传动作

        //停止上传
        uploader.stop();
        

uploader常用事件

事件名	描述
select	选择完文件后触发
start	开始上传后触发
progress	正在上传中时触发，这个事件在iframe上传方式中不存在
success	上传成功后触发
error	上传失败后触发
cancel	取消上传后触发