uploader上传

大家好，欢迎来到IT知识分享网。

综述

Uploader是非常强大的异步文件上传组件，支持ajax、iframe、flash三套方案，实现浏览器的全兼容，调用非常简单，内置多套主题支持和常用插件，比如验证、图片预览、进度条等。

广泛应用于淘宝网，比如退款系统、爱逛街、二手、拍卖、我的淘宝、卖家中心、导购中心等。

拥有非常不错的扩展性，可以自己定制主题和插件。

• 版本：1.4
• 基于：kissy1.3（兼容kissy1.2，不兼容kissy1.1.6）
• 作者：明河（剑平）、紫英、飞绿，感谢苏河、溪夏、正豪等主题和插件作者

flash上传感谢龙藏的ajbridge组件。

Uploader的特性

• 支持ajax、flash、iframe三种方案，兼容所有浏览器。（iframe不推荐使用）
• 多主题支持，可以自己定制主题
• 支持多选批量上传
• 支持上传进度显示
• 支持取消上传
• 支持图片预览（使用flash上传不支持）
• 支持上传验证
• 多种配置方式

demo汇总

• 简单demo：js配置上传组件
• 简单demo：属性配置上传组件
• combo请求
• 上传验证控制的demo
• 组件全部事件演示
• 渲染默认队列数据的demo
• 队列全部方法演示
• 只使用flash上传的demo
• 只使用iframe上传的demo
• 常用方法控制
• kissy1.2使用uploader1.4

组件内置的主题

图片上传主题

主题	作者	源码	截图
imageUploader	明河	源码
refundUploader	明河	源码
loveUploader	苏河/明河	源码
singleImageUploader	溪夏/明河	源码
cropUploader	明河、元泉	源码
editorMultipleUploader	明河、承玉	源码

文件上传主题

主题	作者	源码	截图
default	明河	源码
daogouUploader	溪夏/明河	源码

组件快速上手

kissy1.2下需要gallery的包配置：

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

kissy1.3就不需要该配置。

1.组件依赖的html结构

<inputtype="file"class="g-u"id="J_UploaderBtn"value="上传文件"name="Filedata">

组件的核心只依赖原生的文件上传域，value属性值为上传按钮的文案，name属性非常重要：服务器端获取文件数据的字段。

2.加载Uploader模块

 KISSY.use('gallery/uploader/1.4/index',function(S,Uploader){})

提醒：use()的回调，第一个参数是KISSY，第二个参数才是组件实例。

3.初始化Uploader

 KISSY.use('gallery/uploader/1.4/index',function(S,Uploader){var uploader =newUploader('#J_UploaderBtn',{//处理上传的服务器端脚本路径 action:"upload.php"});})

Uploader类接受二个参数：

• 第一个参数指向目标元素（指向原生文件上传域元素即可）
• 第二个参数为组件配置，action必须配置，为服务器端处理文件上传的路径。

提醒：如果是使用flash上传，action必须是绝对路径。

打开页面就会发现文件上传域部分的结构发生了变化，html结构如下：

<ahref="javascript:void(0)"class="g-u ks-uploader-button"><spanclass="btn-text">上传文件</span><divclass="file-input-wrapper"style="overflow: hidden;"><inputtype="file"name="Filedata"hidefocus="true"class="file-input"style=""></div></a>

但缺少样式，也没办法处理上传行为，接下来我们加载一个默认主题。

4. 主题的使用

S.use('gallery/uploader/1.4/index,gallery/uploader/1.4/themes/default/index,gallery/uploader/1.4/themes/default/style.css',function(S,Uploader,DefaultTheme){var uploader =newUploader('#J_UploaderBtn',{//处理上传的服务器端脚本路径 action:"upload.php"});//使用主题var defaultTheme =newDefaultTheme({ queueTarget:'#J_UploaderQueue'}); uploader.theme(defaultTheme);})

第一步先要use()主题js和css，模块路径为gallery/uploader/1.4/themes/default/index和gallery/uploader/1.4/themes/default/index。

第二步实例化主题：

var defaultTheme =newDefaultTheme({ queueTarget:'#J_UploaderQueue'});

queueTarget是必须配置的，指向队列容器：

<ulid="J_JsUploaderQueue"></ul>

第三步使用uploader.theme()方法，将主题实例加入到uploader中。

uploader.theme(defaultTheme);

再刷新下页面看看，就会发现已经有样式，并可以处理上传了（action指向的服务器路径可用的情况下）。

html结构上也发生了变化，模拟按钮上增加了defaultTheme-button样式，而ul队列容器上增加了defaultTheme-queue。

你可以通过这二个样式，来改变主题样式。

当然你也可以自定义自己的主题，后面会讲解到。

我们还需要加载一些uploader插件，才能让功能更完整，比如验证、预览等，继续往下看。

4. 服务器端返回的数据格式

建议服务端返回的数据格式如下：

{"status":1,"type":"ajax","name":"[1343736002.749366]0.png","url":".\/files\/[1343736002.749366]0.png"}

提醒：去掉了Uploader1.3的data字段

留意引号！！！特别是键名要加""，不然json会解析失败。

"status":1，才是上传成功的标识，其他任何状态码都认定为失败。

"url":"xxx"，一般是必须的，为文件上传到服务器后的路径。

"type":"ajax"和"name":"[1343736002.749366]0.png"并非必须的。

服务器出错时返回的信息

{"status":0,message":"图片过大！"}

如果服务器返回的格式不是这样，你需要使用filter属性，格式化数据

 uploader.set('filter',function(data){var result = S.JSON.parse(data);if(result.message) result.msg ='上传失败！';return result;});

5. 给上传组件增加验证

验证功能是作为uploader的插件出现的，需要用户手动加载并初始化。

第一步加载插件js：

 S.use('gallery/uploader/1.4/plugins/auth/auth',function(S,Auth){})

第二步初始化插件：

var auth =newAuth({//最多上传个数 max:3,//图片最大允许大小 maxSize:100});

auth插件的配置，请看文章的插件部分。

第三步使用plug()将插件插入uploader：

 uploader.plug(auth);

6.存储服务器上传成功后返回的url

上传成功后服务器会返回文件的url，供开发者后续操作，比如将url存储到数据库中，这个过程不需要用户自己写额外代码，加载Uploader的urlsInput插件即可。

插件的使用跟auth是一样的：

 S.use('gallery/uploader/1.4/plugins/urlsInput/urlsInput',function(S,UrlsInput){var urlsInput =newUrlsInput({target:'#J_Urls'}); uploader.plug(urlsInput);})

target指向用于存储的元素目标，一般是个隐藏域，比如：

<inputtype="hidden"id="J_Urls"name="urls">

7.合并插件调用

uploader的plug方法和theme方法是支持链式调用的。

 S.use('gallery/uploader/1.4/index,gallery/uploader/1.4/themes/default/index,gallery/uploader/1.4/themes/default/style.css',function(S,Uploader,DefaultTheme){//上传组件插件var plugins ='gallery/uploader/1.4/plugins/auth/auth,'+'gallery/uploader/1.4/plugins/urlsInput/urlsInput,'+'gallery/uploader/1.4/plugins/proBars/proBars'; S.use(plugins,function(S,Auth,UrlsInput,ProBars){var uploader =newUploader('#J_UploaderBtn',{//处理上传的服务器端脚本路径 action:"upload.php"});//使用主题 uploader.theme(newDefaultTheme({ queueTarget:'#J_UploaderQueue'}))//验证插件 uploader.plug(newAuth({//最多上传个数 max:3,//图片最大允许大小 maxSize:100}))//url保存插件.plug(newUrlsInput({target:'#J_Urls'}))//进度条集合.plug(newProBars());});})

uploader拥有非常丰富的插件，用户可以根据自己的需要加载和初始化指定的插件，详细内容请看下面的插件部分。

组件事件说明

提醒：如果你需要操作队列容器中的dom结构，需要监听add事件，比如：

 uploader.on('add',function(ev){var file = ev.file;var target = file.target; target.addClass('test');});

所有的事件参数都包含ev.file对象存储着文件数据。

ev.file.target指向队列容器中的每一个文件对应的DOM节点。

ev.index为文件在队列中的索引值，经常会用到。

success事件和error事件

这二个事件也经常用到，事件参数都包含服务器返回的结果集。

 uploader.on('success',function(ev){var index = ev.index, file = ev.file;//服务器端返回的结果集var result = ev.result; S.log('上传成功,服务器端返回url：'+ result.url);});

 uploader.on('error',function(ev){var index = ev.index, file = ev.file;//服务器端返回的结果集var result = ev.result; S.log('上传失败,错误消息为：'+result.msg);});

提醒：如果是前端验证触发的error事件，不会有result数据

组件属性说明

获取/设置属性

使用get()/set()来获取设置属性，举例：

 uploader.on('themeRender',function(ev){var queue = uploader.get('queue');//队列中所有的文件数据 S.log(queue.get('files'));//禁用按钮 uploader.set('disabled',true);});

常用指数：*

常用指数：**

常用指数：*

Uploader方法说明

upload (index)：上传指定队列索引的文件

//上传队列中的第一个文件 uploader.upload(0)

uploadFiles (status)：批量上传队列中的指定状态下的文件

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

cancel  (index)：取消文件上传

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

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

stop()：停止上传动作

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

theme():运行主题实例

uploader.theme(newDefaultTheme({ queueTarget:'#J_UploaderQueue'}))

plug():将插件插入到uploader中

//验证插件 uploader.plug(newAuth({//最多上传个数 max:3,//图片最大允许大小 maxSize:100}))//url保存插件.plug(newUrlsInput({target:'#J_Urls'}))

getPlugin(pluginName):获取插件

//验证插件 uploader.getPlugin('auth');

插件名称可以对照插件的模块路径上的名称gallery/uploader/1.4/plugins/auth/auth。

Queue的控制说明

Queue用于控制队列的文件，非常常用，实例存储在Uploader中。

var queue = uploader.get('queue');

Queue的files属性

queue的属性只有files，可以获取到所有上传的文件数据，为一个数组。

var queue = uploader.get('queue');var files = queue.get('files'); S.log(files.length);

add():向队列添加文件

//测试文件数据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);

当组件向队列添加文件时，会自动生成一个唯一id，比如’file-10’，’file-‘前缀是一样的，可以通过id来获取指定的文件。

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

var removeFile = queue.remove(0); S.log('删除的文件数据为：'+removeFile);

提醒：remove()的参数可以是队列数组的索引，比如上面代码的0，是取队列第一个文件数据；也可以是文件的id（唯一），比如remove(‘file-26’)。

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

 queue.clear();

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

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

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

var indexs = queue.getIndexs('waiting'); alert('所有等待中的文件index为：'+ indexs);

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

Theme说明

Theme的使用

使用theme()方法初始化主题逻辑，代码如下：

 uploader.theme(newDefaultTheme({ queueTarget:'#J_UploaderQueue'}))

如何理解主题的概念

Uploader的主题包含二个部分：脚本（index.js）和样式（style.css）。

主题的脚本可以理解为uploader事件监听器集合，主题脚本的模版如下：

KISSY.add(function(S,Node,ImageUploader){var EMPTY ='', $ =Node.all;/** * @name RefundUploader * @class 退款凭证上传主题，继承于imageUploader主题 * @constructor * @extends Theme * @requires Theme * @requires ProgressBar * @author 明河 */functionRefundUploader(config){var self =this;//调用父类构造函数RefundUploader.superclass.constructor.call(self, config);} S.extend(RefundUploader,ImageUploader,/** @lends RefundUploader.prototype*/{/** * 在上传组件运行完毕后执行的方法（对上传组件所有的控制都应该在这个函数内） * @param {Uploader} uploader */ render:function(){var self =this;var uploader = self.get('uploader');},/** * 在完成文件dom插入后执行的方法 * @param {Object} ev 类似{index:0,file:{},target:$target} */ _addHandler:function(ev){},/** * 文件处于上传错误状态时触发 */ _errorHandler:function(ev){}},{ATTRS:/** @lends RefundUploader.prototype*/{ name:{value:'refundUploader'}}});returnRefundUploader;},{requires:['node','gallery/uploader/1.4/themes/imageUploader/index']});

主题中的_errorHandler，在上传失败时会自动触发，当然像”_addHandler”或”_successHandler”也是一样的道理。

Theme的属性

在html页面直接写主题模版

这是1.4新增功能，用于用户可以更直观的控制主题模版。

<ul id="J_JsUploaderQueue"><script type="text/uploader-theme"><li id="queue-file-{id}"class="g-u" data-name="{name}"><div class="pic-wrapper"><div class="pic"><span><img class="J_Pic_{id} preview-img" src=""/></span></div> <div class=" J_Mask_{id} pic-mask"></div><div class="status-wrapper J_FileStatus"><div class="status waiting-status"><p>等待上传</p></div><div class="status start-status progress-status success-status"><div class="J_ProgressBar_{id}">上传中...</div></div> <div class="status error-status"> <p class="J_ErrorMsg_{id}">上传失败，请重试！</p></div></div> </div>'+<div><a class="J_Del_{id} del-pic" href="#">删除</a></div> </li>'</script> </ul>

模版代码必须包含在script标签内

<script type="text/uploader-theme"></script>

如何自己写一套主题？

//TODO:日后补充

插件说明

如何获取插件呢？

var auth = uploader.getPlugin('auth');//只允许上传一个文件 auth.set('max',1);

如何自己写一个uploader的插件呢？

//TODO:日后补充

auth：表单验证

配置项（属性）

auth的方法

msg(rule,msg)：获取/设置验证消息

var auth = uploader.getPlugin('auth');//设置max规则消息 auth.msg('max','每次最多上传{max}个文件！');//获取max消息 S.log(auth.msg('max'));

testRequired()：检验是否已经上传了至少一个文件

var auth = uploader.getPlugin('auth');var isPass = auth.testRequired(); S.log(isPass);

其他的规则一样拥有test方法（”test+规则名()”）。

auth的事件

当校验不通过是auth会触发uploader的error事件：

uploader.on('error',function(ev){ S.log(ev.rule);})

urlsInput：存储服务器返回的url并可以渲染默认数据

使用urlsInput插件，uploader会自动将服务器返回的url插入到一个input上。

需要有个目标容器：

<input type="hidden" id="J_Urls" name="refundImageUrls">

 uploader.use('urlsInput',{target:'.J_Urls'});

配置项（属性）

urlsInput的方法

add(url)：向input添加路径

var urlsInput = uploader.getPlugin('urlsInput'); urlsInput.add('http://www.36ria.com/test.jpg');

remove(url)：删除input内的指定路径

isExist(url)：是否已经存在指定路径

restore()：添加默认数据到队列

tagConfig：从input上拉取配置覆盖组件配置

如果你希望可以在html配置组件属性，需要use(“tagConfig”)。

demo可以猛击这里。

<inputclass="g-u"id="J_UploaderBtn"name="Filedata"type="file"value="上传图片"action="upload.php"postData='{"author":"minghe"}'max="3"maxSize="500">

提醒：html中的配置会覆盖js的配置，这跟1.4前的逻辑相反。

提醒：postData等价于js配置中的data。

tagConfig的配置覆盖会在主题初始化成功后才执行，如果你的uploader不使用主题，请手动调用覆盖方法：

var tagConfig = uploader.getPlugin('tagConfig'); tagConfig.cover();

proBars：进度条集合

提醒：proBars是队列中所有的进度条集合，插件还有个ProgressBar子类，对应每个文件的进度条。

进度条插件依赖主题模版中的进度条容器：

<divclass="J_ProgressBar_{id}">上传中...</div>

ProBars的配置项

ProBars的方法

add(fileId) ：向集合添加一个进度条

preview：图片预览插件

提醒：该插件在IE10下无效，无效的情况下，主题会使用服务器返回的路径来渲染出图片。

preview(fileInput, imgElem)：preview只有这个方法，用于渲染本地图片。

var preview = uploader.getPlugin('preview');var fileInput = uploader.get('fileInput'); preview.preview(fileInput,$img);

filedrop：文件拖拽上传插件

Filedrop的配置项

Filedrop的方法

show()/hide()：显示和隐藏拖拽区域

imageZoom：图片放大插件

利用image-dd组件来实现图片放大。

Q&A

如何处理跨域上传？

目前跨域处理只支持iframe和flash方式，如果遇到需要跨域的情况，推荐设置type:"iframe"。

假设你表单页面的域是：refund.taobao.com，而处理上传的服务器端路径却是upload.taobao.com。

那么将二个页面使用js将域设置为taobao.com：

<script>document.domain="taobao.com";</script>

处理上传的服务器返回的内容可以如下：

<script>document.domain="taobao.com";</script> {"status":1,"type":"ajax","name":"54.png","url":".\/files\/54.png"}

脚本部分不用做任何处理，组件会自动处理，只取需要的结果集。

flash上传进度条不走，上传失败

在url后面加上ks-debug，看下调试工具控制台输出是否有个“缺少crossdomain.xml”的提示。

crossdomain.xml是flash的安全策略文件，需要放在在域名根目录下，比如应用域名为refund.taobao.com，那么就应该有http://www.refund.taobao.com/crossdomain.xml，在调试时可以将这个文件代理到本地。

crossdomain.xml的内容可以如下：

<?xml version="1.0"?><cross-domain-policy><allow-access-fromdomain="*"/><!--下面这行代码必须有--><allow-access-fromdomain="*.tbcdn.cn"/></cross-domain-policy>

tbcdn.cn为swf文件所在的位置，安全策略文件需要加上。

flash上传时，隐藏上传按钮后再显示，上传组件不可用

flash对象不能设置display:none;，父容器隐藏也是不行的！这点特别留意。

你可以设置position:absolute;top:-2000px，这样的位移方式来处理。

issues