综述
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拥有非常丰富的插件，用户可以根据自己的需要加载和初始化指定的插件，详细内容请看下面的插件部分。
组件事件说明
| 事件名 | 描述 |
|---|---|
| select | 选择完文件后触发 |
| add | 向队列添加完文件后触发 |
| start | 开始上传后触发 |
| progress | 正在上传中时触发，这个事件在iframe上传方式中不存在 |
| success | 上传成功后触发 |
| error | 上传失败后触发 |
| cancel | 取消上传后触发 |
| remove | 删除队列中的图片后触发 |
提醒：如果你需要操作队列容器中的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);});常用指数：*
| 参数名 | 类型 | 默认值 | 是否只读 | 描述 |
|---|---|---|---|---|
| action | String | '' | 读/写 | 服务器端处理上传的路径（v1.3.0+） |
| data | Object | {} | 读/写 | 此配置用于动态修改post给服务器的数据（v1.3.0+） |
| name | String | Filedata | 只读 | 文件上传域name名 |
| autoUpload | Boolean | true | 读/写 | 是否自动上传，当为false时，可以通过uploader的upload()和uploadFiles()手动上传队列中的文件。 |
| multiple | Boolean | false | 读/写 | 是否开启多选支持
如果采用iframe上传，请设置为
false |
| disabled | Boolean | false | 读/写 | 是否可用,false为按钮可用 |
| filter | Function | "" | 写 | 用于格式化服务器端返回的数据 |
常用指数：**
| 属性名 | 类型 | 默认值 | 是否只读 | 描述 |
|---|---|---|---|---|
| target | NodeList | '' | 只读 | 上传组件的目标元素，当组件初始化成功后会指向模拟按钮 |
| fileInput | NodeList | '' | 只读 | 模拟按钮内的文件上传input(type="file")，如果是flash上传此项不存在 |
| queue | Queue | '' | 只读 | 队列的实例，对队列的操作都集中在这个实例上 |
| type | Queue | '' | 只读 | 采用的上传方案，当值是数组时，比如“type” : ["flash","ajax","iframe"]，按顺序获取浏览器支持的方式，该配置会优先使用flash上传方式，如果浏览器不支持flash，会降级为ajax，如果还不支持ajax，会降级为iframe；当值是字符串时，比如“type” : “ajax”，表示只使用ajax上传方式。这种方式比较极端，在不支持ajax上传方式的浏览器会不可用；当“type” : “auto”，auto是一种特例，等价于["ajax","iframe"]。 |
| isAllowUpload | Boolean | true | 只读 | 是否允许上传文件 |
| curUploadIndex | Number | "" | 只读 | 当前上传的文件对应的在数组内的索引值，如果没有文件正在上传，值为空 |
| multipleLen | Number | -1 | 只读 | 用于限制多选文件个数，值为负时不设置多选限制 |
常用指数：*
| 属性名 | 类型 | 默认值 | 是否只读 | 描述 |
|---|---|---|---|---|
| theme | Theme | '' | 只读 | 主题类实例 |
| btnTpl | Theme | 只读 | 模拟按钮模版 | |
| swfSize | Object | {} | 只读 | 强制设置flash的尺寸，只有在flash上传方式中有效，比如{100,height:100}，默认为自适应按钮容器尺寸 |
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的属性
| 属性名 | 类型 | 默认值 | 是否只读 | 描述 |
|---|---|---|---|---|
| name | String | '' | 只读 | 主题名，是主题对应的模拟按钮和队列容器的样式名的前缀 |
| fileTpl | String | '' | 只读 | 主题模版，用于定制主题的DOM样式 |
| authMsg | Object | {} | 只读 | 验证插件的消息文案 |
| allowExts | String | '' | 只读 | 文件格式限制 |
| queueTarget | NodeList | '' | 只读 | 队列容器目标元素 |
| uploader | Uploader | '' | 只读 | Uploader的实例 |
在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：表单验证
配置项（属性）
| 属性名 | 类型 | 默认值 | 是否只读 | 描述 |
|---|---|---|---|---|
| allowExts | String | '' | 读/写 | 图片格式验证控制 |
| required | Boolean | '' | 读/写 | 必须至少上传一个文件
组件默认不触发，可以使用uploader的testRequired()方法手动验证。
|
| max | Number | '' | 读/写 | 最多上传N个图片，当达到N个图片后按钮会增加禁用样式uploader-button-disabled，用户可以通过这个样式名定制需要的置灰样式。 |
| maxSize | Number | '' | 读/写 | 单图片最大允许上传的文件大小，单位是KB
如果是iframe上传方式，此验证无效。
|
| allowRepeat | Boolean | '' | 读/写 | 是否允许多次上传同一个文件 |
| widthHeight | Array | '' | 读/写 | v1.4新增的验证规则，用于限制图片尺寸，非常特殊的验证方式：1.异步验证；2.值为一个函数数组[fnWidth,fnHeight]，比如限制宽度大于60，高度大于160，代码如下： widthHeight:function(width,height){ return width > 160 && height > 160; } |
| msg | Object | {} | 读/写 | 验证的消息集合，请使用msg()方法来设置消息 |
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'});配置项（属性）
| 属性名 | 类型 | 默认值 | 是否只读 | 描述 |
|---|---|---|---|---|
| target | String | '' | 读 | 用于存储文件路径的目标容器 |
| urls | Array | [] | 读 | 容器内的所有路径 |
| autoRestore | Boolean | true | 读 | 是否自动渲染默认数据 |
| split | String | "," | 读/写 | 多个路径间的分隔符 |
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的配置项
| 属性名 | 类型 | 默认值 | 是否只读 | 描述 |
|---|---|---|---|---|
| width | Number | 'auto' | 读/写 | 进度条的宽度 |
| bars | Object | {} | 读 | 进度条实例集合 |
| isHide | Boolean | true | 读/写 | 进度走到100%时是否隐藏 |
| speed | String | 0.2 | 读/写 | 进度条跑动速度控制 |
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的配置项
| 属性名 | 类型 | 默认值 | 是否只读 | 描述 |
|---|---|---|---|---|
| target | NodeList | '' | 读 | 指向模拟按钮 |
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，这样的位移方式来处理。