hdjs

--- layout: default title: WebUploader API文档 navName: API group: 'nav' weight : 3 styles: - /doc/css/doc.css --- <div class="container"> <div class="page-header"> <h1 id="WebUploader">WebUploader API文档</h1> </div> <p>Web Uploader内部类的详细说明，以下提及的功能类，都可以在<code>WebUploader</code>这个变量中访问到。</p> <p>As you know, Web Uploader的每个文件都是用过<a href="https://github.com/amdjs/amdjs-api/wiki/AMD">AMD</a>规范中的<code>define</code>组织起来的, 每个Module都会有个module id. 默认module id为该文件的路径，而此路径将会转化成名字空间存放在WebUploader中。如：</p> <ul> <li>module <code>base</code>：WebUploader.Base</li> <li>module <code>file</code>: WebUploader.File</li> <li>module <code>lib/dnd</code>: WebUploader.Lib.Dnd</li> <li>module <code>runtime/html5/dnd</code>: WebUploader.Runtime.Html5.Dnd</li> </ul> <p>以下文档中对类的使用可能省略掉了<code>WebUploader</code>前缀。</p> </div> <div id="post-container" class="container"> <div class="row"> <div class="col-md-3"> <div class="post-toc"> <ul class="nav"> <li> <a href="#WebUploader_Uploader">Uploader</a> <ul class="nav"> <li class="options"> <a class="" href="#WebUploader_Uploader_options">options</a> </li> <li class="events"> <a class="" href="#WebUploader_Uploader_events">events</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_option">option</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_getStats">getStats</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_destroy">destroy</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_addButton">addButton</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_makeThumb">makeThumb</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_md5File">md5File</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_addFiles">addFiles</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_removeFile">removeFile</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_getFiles">getFiles</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_retry">retry</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_sort">sort</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_reset">reset</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_predictRuntimeType">predictRuntimeType</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_upload">upload</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_stop">stop</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_cancelFile">cancelFile</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_isInProgress">isInProgress</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_skipFile">skipFile</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_request">request</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_Uploader_register">Uploader.register</a> </li> <li class="method"> <a class="" href="#WebUploader_Uploader_Uploader_unRegister">Uploader.unRegister</a> </li> </ul> </li> <li> <a href="#WebUploader_Base">Base</a> <ul class="nav"> <li class="method"> <a class="" href="#WebUploader_Base_create">create</a> </li> <li class="property"> <a class="" href="#WebUploader_Base_version">version</a> </li> <li class="property"> <a class="" href="#WebUploader_Base_">$</a> </li> <li class="property"> <a class="" href="#WebUploader_Base_browser">browser</a> </li> <li class="property"> <a class="" href="#WebUploader_Base_os">os</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_inherits">inherits</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_noop">noop</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_bindFn">bindFn</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_log">log</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_slice">slice</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_guid">guid</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_formatSize">formatSize</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_Deferred">Deferred</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_isPromise">isPromise</a> </li> <li class="method"> <a class="" href="#WebUploader_Base_when">when</a> </li> </ul> </li> <li> <a href="#WebUploader_Mediator">Mediator</a> <ul class="nav"> <li class="method"> <a class="" href="#WebUploader_Mediator_on">on</a> </li> <li class="method"> <a class="" href="#WebUploader_Mediator_once">once</a> </li> <li class="method"> <a class="" href="#WebUploader_Mediator_off">off</a> </li> <li class="method"> <a class="" href="#WebUploader_Mediator_trigger">trigger</a> </li> <li class="method"> <a class="" href="#WebUploader_Mediator_installTo">installTo</a> </li> </ul> </li> <li> <a href="#WebUploader_File">File</a> <ul class="nav"> <li class="events"> <a class="" href="#WebUploader_File_events">events</a> </li> <li class="property"> <a class="" href="#WebUploader_File_name">name</a> </li> <li class="property"> <a class="" href="#WebUploader_File_size">size</a> </li> <li class="property"> <a class="" href="#WebUploader_File_type">type</a> </li> <li class="property"> <a class="" href="#WebUploader_File_lastModifiedDate">lastModifiedDate</a> </li> <li class="property"> <a class="" href="#WebUploader_File_id">id</a> </li> <li class="property"> <a class="" href="#WebUploader_File_ext">ext</a> </li> <li class="property"> <a class="" href="#WebUploader_File_statusText">statusText</a> </li> <li class="method"> <a class="" href="#WebUploader_File_setStatus">setStatus</a> </li> <li class="property"> <a class="" href="#WebUploader_File_File_Status">Status</a> </li> </ul> </li> <li> <a href="#WebUploader_Queue">Queue</a> <ul class="nav"> <li class="property"> <a class="" href="#WebUploader_Queue_stats">stats</a> </li> <li class="method"> <a class="" href="#WebUploader_Queue_append">append</a> </li> <li class="method"> <a class="" href="#WebUploader_Queue_prepend">prepend</a> </li> <li class="method"> <a class="" href="#WebUploader_Queue_getFile">getFile</a> </li> <li class="method"> <a class="" href="#WebUploader_Queue_fetch">fetch</a> </li> <li class="method"> <a class="" href="#WebUploader_Queue_sort">sort</a> </li> <li class="method"> <a class="" href="#WebUploader_Queue_getFiles">getFiles</a> </li> <li class="method"> <a class="" href="#WebUploader_Queue_removeFile">removeFile</a> </li> </ul> </li> </ul> </div> </div> <div class="col-md-9"> <div class="page-container"> <a id="WebUploader_WebUploader" ></a> <div class="clearfix category"> <article class="clearfix constructor"> <h3 id="WebUploader_Uploader" >Uploader </h3> <ul class="signature"> <li>new Uploader( opts ) <span class="return">⇒ Uploader</span> </li> </ul> <p>上传入口类。</p> {% highlight javascript %} var uploader = WebUploader.Uploader({ swf: 'path_of_swf/Uploader.swf', // 开起分片上传。 chunked: true }); {% endhighlight %} </article> <div> <h3 id="WebUploader_Uploader_options">参数说明</h3> <ul class="params-list"> <li> <span class="meta"> <code>dnd</code> {Selector} [可选] [默认值：undefined] </span> <p> 指定Drag And Drop拖拽的容器，如果不指定，则不启动。</p> </li> <li> <span class="meta"> <code>disableGlobalDnd</code> {Selector} [可选] [默认值：false] </span> <p> 是否禁掉整个页面的拖拽功能，如果不禁用，图片拖进来的时候会默认被浏览器打开。</p> </li> <li> <span class="meta"> <code>paste</code> {Selector} [可选] [默认值：undefined] </span> <p> 指定监听paste事件的容器，如果不指定，不启用此功能。此功能为通过粘贴来添加截屏的图片。建议设置为<code>document.body</code>.</p> </li> <li> <span class="meta"> <code>pick</code> {Selector, Object} [可选] [默认值：undefined] </span> <p>指定选择文件的按钮容器，不指定则不创建按钮。</p> <ul> <li><code>id</code> {Seletor|dom} 指定选择文件的按钮容器，不指定则不创建按钮。<strong>注意</strong> 这里虽然写的是 id, 但是不是只支持 id, 还支持 class, 或者 dom 节点。</li> <li><code>label</code> {String} 请采用 <code>innerHTML</code> 代替</li> <li><code>innerHTML</code> {String} 指定按钮文字。不指定时优先从指定的容器中看是否自带文字。</li> <li><code>multiple</code> {Boolean} 是否开起同时选择多个文件能力。</li> </ul> </li> <li> <span class="meta"> <code>accept</code> {Arroy} [可选] [默认值：null] </span> <p>指定接受哪些类型的文件。由于目前还有ext转mimeType表，所以这里需要分开指定。</p> <ul> <li><code>title</code> {String} 文字描述</li> <li><code>extensions</code> {String} 允许的文件后缀，不带点，多个用逗号分割。</li> <li><code>mimeTypes</code> {String} 多个用逗号分割。</li> </ul> <p>如：</p> <pre><code>{ title: 'Images', extensions: 'gif,jpg,jpeg,bmp,png', mimeTypes: 'image/*' }</code></pre> </li> <li> <span class="meta"> <code>thumb</code> {Object} [可选] </span> <p>配置生成缩略图的选项。</p> <p>默认为：</p> {% highlight javascript %} { width: 110, height: 110, // 图片质量，只有type为`image/jpeg`的时候才有效。 quality: 70, // 是否允许放大，如果想要生成小图的时候不失真，此选项应该设置为false. allowMagnify: true, // 是否允许裁剪。 crop: true, // 为空的话则保留原有图片格式。 // 否则强制转换成指定的类型。 type: 'image/jpeg' } {% endhighlight %} </li> <li> <span class="meta"> <code>compress</code> {Object} [可选] </span> <p>配置压缩的图片的选项。如果此选项为<code>false</code>, 则图片在上传前不进行压缩。</p> <p>默认为：</p> {% highlight javascript %} { width: 1600, height: 1600, // 图片质量，只有type为`image/jpeg`的时候才有效。 quality: 90, // 是否允许放大，如果想要生成小图的时候不失真，此选项应该设置为false. allowMagnify: false, // 是否允许裁剪。 crop: false, // 是否保留头部meta信息。 preserveHeaders: true, // 如果发现压缩后文件大小比原来还大，则使用原来图片 // 此属性可能会影响图片自动纠正功能 noCompressIfLarger: false, // 单位字节，如果图片大小小于此值，不会采用压缩。 compressSize: 0 } {% endhighlight %} </li> <li> <span class="meta"> <code>auto</code> {Boolean} [可选] [默认值：false] </span> <p>设置为 true 后，不需要手动调用上传，有文件选择即开始上传。</p> </li> <li> <span class="meta"> <code>runtimeOrder</code> {Object} [可选] [默认值：html5,flash] </span> <p>指定运行时启动顺序。默认会想尝试 html5 是否支持，如果支持则使用 html5, 否则则使用 flash.</p> <p>可以将此值设置成 <code>flash</code>，来强制使用 flash 运行时。</p> </li> <li> <span class="meta"> <code>prepareNextFile</code> {Boolean} [可选] [默认值：false] </span> <p>是否允许在文件传输时提前把下一个文件准备好。对于一个文件的准备工作比较耗时，比如图片压缩，md5序列化。如果能提前在当前文件传输期处理，可以节省总体耗时。</p> </li> <li> <span class="meta"> <code>chunked</code> {Boolean} [可选] [默认值：false] </span> <p>是否要分片处理大文件上传。</p> </li> <li> <span class="meta"> <code>chunkSize</code> {Boolean} [可选] [默认值：5242880] </span> <p>如果要分片，分多大一片？默认大小为5M.</p> </li> <li> <span class="meta"> <code>chunkRetry</code> {Boolean} [可选] [默认值：2] </span> <p>如果某个分片由于网络问题出错，允许自动重传多少次？</p> </li> <li> <span class="meta"> <code>threads</code> {Boolean} [可选] [默认值：3] </span> <p>上传并发数。允许同时最大上传进程数。</p> </li> <li> <span class="meta"> <code>formData</code> {Object} [可选] [默认值：{}] </span> <p>文件上传请求的参数表，每次发送都会发送此对象中的参数。</p> </li> <li> <span class="meta"> <code>fileVal</code> {Object} [可选] [默认值：'file'] </span> <p>设置文件上传域的name。</p> </li> <li> <span class="meta"> <code>method</code> {Object} [可选] [默认值：'POST'] </span> <p>文件上传方式，<code>POST</code>或者<code>GET</code>。</p> </li> <li> <span class="meta"> <code>sendAsBinary</code> {Object} [可选] [默认值：false] </span> <p>是否已二进制的流的方式发送文件，这样整个上传内容<code>php://input</code>都为文件内容，其他参数在$_GET数组中。</p> </li> <li> <span class="meta"> <code>fileNumLimit</code> {int} [可选] [默认值：undefined] </span> <p>验证文件总数量, 超出则不允许加入队列。</p> </li> <li> <span class="meta"> <code>fileSizeLimit</code> {int} [可选] [默认值：undefined] </span> <p>验证文件总大小是否超出限制, 超出则不允许加入队列。</p> </li> <li> <span class="meta"> <code>fileSingleSizeLimit</code> {int} [可选] [默认值：undefined] </span> <p>验证单个文件大小是否超出限制, 超出则不允许加入队列。</p> </li> <li> <span class="meta"> <code>duplicate</code> {Boolean} [可选] [默认值：undefined] </span> <p>去重，根据文件名字、文件大小和最后修改时间来生成hash Key.</p> </li> <li> <span class="meta"> <code>disableWidgets</code> {String, Array} [可选] [默认值：undefined] </span> <p>默认所有 Uploader.register 了的 widget 都会被加载，如果禁用某一部分，请通过此 option 指定黑名单。</p> </li> </ul> </div> <div> <h3 id="WebUploader_Uploader_events">事件说明</h3> <table class="table table-bordered"> <tr> <th>事件名</th> <th class="events-tb-desc">参数说明</th> <th>描述</th> </tr> <tr> <td><code>dndAccept</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>items</code> {DataTransferItemList}</span><p>DataTransferItem</p> </li></ul> </td> <td><p>阻止此事件可以拒绝某些类型的文件拖入进来。目前只有 chrome 提供这样的 API，且只能通过 mime-type 验证。</p> </td> </tr> <tr> <td><code>beforeFileQueued</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>file</code> {File}</span><p>File对象</p> </li></ul> </td> <td><p>当文件被加入队列之前触发，此事件的handler返回值为<code>false</code>，则此文件不会被添加进入队列。</p> </td> </tr> <tr> <td><code>fileQueued</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>file</code> {File}</span><p>File对象</p> </li></ul> </td> <td><p>当文件被加入队列以后触发。</p> </td> </tr> <tr> <td><code>filesQueued</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>files</code> {File}</span><p>数组，内容为原始File(lib/File）对象。</p> </li></ul> </td> <td><p>当一批文件添加进队列以后触发。</p> </td> </tr> <tr> <td><code>fileDequeued</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>file</code> {File}</span><p>File对象</p> </li></ul> </td> <td><p>当文件被移除队列后触发。</p> </td> </tr> <tr> <td><code>reset</code></td> <td class="events-tb-desc"> </td> <td><p>当 uploader 被重置的时候触发。</p> </td> </tr> <tr> <td><code>startUpload</code></td> <td class="events-tb-desc"> </td> <td><p>当开始上传流程时触发。</p> </td> </tr> <tr> <td><code>stopUpload</code></td> <td class="events-tb-desc"> </td> <td><p>当开始上传流程暂停时触发。</p> </td> </tr> <tr> <td><code>uploadFinished</code></td> <td class="events-tb-desc"> </td> <td><p>当所有文件上传结束时触发。</p> </td> </tr> <tr> <td><code>uploadStart</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>file</code> {File}</span><p>File对象</p> </li></ul> </td> <td><p>某个文件开始上传前触发，一个文件只会触发一次。</p> </td> </tr> <tr> <td><code>uploadBeforeSend</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>object</code> {Object}</span></li><li><span class="meta"><code>data</code> {Object}</span><p>默认的上传参数，可以扩展此对象来控制上传参数。</p> </li><li><span class="meta"><code>headers</code> {Object}</span><p>可以扩展此对象来控制上传头部。</p> </li></ul> </td> <td><p>当某个文件的分块在发送前触发，主要用来询问是否要添加附带参数，大文件在开起分片上传的前提下此事件可能会触发多次。</p> </td> </tr> <tr> <td><code>uploadAccept</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>object</code> {Object}</span></li><li><span class="meta"><code>ret</code> {Object}</span><p>服务端的返回数据，json格式，如果服务端不是json格式，从ret._raw中取数据，自行解析。</p> </li></ul> </td> <td><p>当某个文件上传到服务端响应后，会派送此事件来询问服务端响应是否有效。如果此事件handler返回值为<code>false</code>, 则此文件将派送<code>server</code>类型的<code>uploadError</code>事件。</p> </td> </tr> <tr> <td><code>uploadProgress</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>file</code> {File}</span><p>File对象</p> </li><li><span class="meta"><code>percentage</code> {Number}</span><p>上传进度</p> </li></ul> </td> <td><p>上传过程中触发，携带上传进度。</p> </td> </tr> <tr> <td><code>uploadError</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>file</code> {File}</span><p>File对象</p> </li><li><span class="meta"><code>reason</code> {String}</span><p>出错的code</p> </li></ul> </td> <td><p>当文件上传出错时触发。</p> </td> </tr> <tr> <td><code>uploadSuccess</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>file</code> {File}</span><p>File对象</p> </li><li><span class="meta"><code>response</code> {Object}</span><p>服务端返回的数据</p> </li></ul> </td> <td><p>当文件上传成功时触发。</p> </td> </tr> <tr> <td><code>uploadComplete</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>file</code> {File} [可选]</span><p>File对象</p> </li></ul> </td> <td><p>不管成功或者失败，文件上传完成时触发。</p> </td> </tr> <tr> <td><code>error</code></td> <td class="events-tb-desc"> <ul class="params-list"><li><span class="meta"><code>type</code> {String}</span><p>错误类型。</p> </li></ul> </td> <td><p>当validate不通过时，会以派送错误事件的形式通知调用者。通过<code>upload.on('error', handler)</code>可以捕获到此类错误，目前有以下错误会在特定的情况下派送错来。</p> <ul> <li><code>Q_EXCEED_NUM_LIMIT</code> 在设置了<code>fileNumLimit</code>且尝试给<code>uploader</code>添加的文件数量超出这个值时派送。</li> <li><code>Q_EXCEED_SIZE_LIMIT</code> 在设置了<code>Q_EXCEED_SIZE_LIMIT</code>且尝试给<code>uploader</code>添加的文件总大小超出这个值时派送。</li> <li><code>Q_TYPE_DENIED</code> 当文件类型不满足时触发。。</li> </ul> </td> </tr> </table> </div> <article class="clearfix method"> <h3 id="WebUploader_Uploader_option" >option </h3> <ul class="signature"> <li>option( key ) <span class="return">⇒ *</span> </li> <li>option( key, val ) <span class="return">⇒ self</span> </li> </ul> <p>获取或者设置Uploader配置项。</p> {% highlight javascript %} // 初始状态图片上传前不会压缩 var uploader = new WebUploader.Uploader({ compress: null; }); // 修改后图片上传前，尝试将图片压缩到1600 * 1600 uploader.option( 'compress', { width: 1600, height: 1600 }); {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_getStats" >getStats </h3> <ul class="signature"> <li>getStats() <span class="return">⇒ Object</span> </li> </ul> <p>获取文件统计信息。返回一个包含一下信息的对象。</p> <ul> <li><code>successNum</code> 上传成功的文件数</li> <li><code>progressNum</code> 上传中的文件数</li> <li><code>cancelNum</code> 被删除的文件数</li> <li><code>invalidNum</code> 无效的文件数</li> <li><code>uploadFailNum</code> 上传失败的文件数</li> <li><code>queueNum</code> 还在队列中的文件数</li> <li><code>interruptNum</code> 被暂停的文件数</li> </ul> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_destroy" >destroy </h3> <ul class="signature"> <li>destroy() <span class="return">⇒ undefined</span> </li> </ul> <p>销毁 webuploader 实例</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_addButton" >addButton </h3> <ul class="signature"> <li>addButton( pick ) <span class="return">⇒ Promise</span> </li> </ul> <p>添加文件选择按钮，如果一个按钮不够，需要调用此方法来添加。参数跟<a href="#WebUploader_Uploader_options">options.pick</a>一致。</p> {% highlight javascript %} uploader.addButton({ id: '#btnContainer', innerHTML: '选择文件' }); {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_makeThumb" >makeThumb </h3> <ul class="signature"> <li>makeThumb( file, callback ) <span class="return">⇒ undefined</span> </li> <li>makeThumb( file, callback, width, height ) <span class="return">⇒ undefined</span> </li> </ul> <p>生成缩略图，此过程为异步，所以需要传入<code>callback</code>。通常情况在图片加入队里后调用此方法来生成预览图以增强交互效果。</p> <p>当 width 或者 height 的值介于 0 - 1 时，被当成百分比使用。</p> <p><code>callback</code>中可以接收到两个参数。</p> <ul> <li>第一个为error，如果生成缩略图有错误，此error将为真。</li> <li>第二个为ret, 缩略图的Data URL值。</li> </ul> <p><strong>注意</strong> Date URL在IE6/7中不支持，所以不用调用此方法了，直接显示一张暂不支持预览图片好了。也可以借助服务端，将 base64 数据传给服务端，生成一个临时文件供预览。</p> {% highlight javascript %} uploader.on( 'fileQueued', function( file ) { var $li = ...; uploader.makeThumb( file, function( error, ret ) { if ( error ) { $li.text('预览错误'); } else { $li.append('<img alt="" src="' + ret + '" />'); } }); }); {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_md5File" >md5File </h3> <ul class="signature"> <li>md5File( file[, start[, end]] ) <span class="return">⇒ promise</span> </li> </ul> <p>计算文件 md5 值，返回一个 promise 对象，可以监听 progress 进度。</p> {% highlight javascript %} uploader.on( 'fileQueued', function( file ) { var $li = ...; uploader.md5File( file ) // 及时显示进度 .progress(function(percentage) { console.log('Percentage:', percentage); }) // 完成 .then(function(val) { console.log('md5 result:', val); }); }); {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_addFiles" >addFiles </h3> <ul class="signature"> <li>addFiles( file ) <span class="return">⇒ undefined</span> </li> <li>addFiles( [file1, file2 ...] ) <span class="return">⇒ undefined</span> </li> </ul> <p>参数: </p> <ul class="params-list"><li><span class="meta"><code>files</code> {Array of File or File} [可选]</span><p>Files 对象数组</p> </li></ul> <p>添加文件到队列</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_removeFile" >removeFile </h3> <ul class="signature"> <li>removeFile( file ) <span class="return">⇒ undefined</span> </li> <li>removeFile( id ) <span class="return">⇒ undefined</span> </li> <li>removeFile( file, true ) <span class="return">⇒ undefined</span> </li> <li>removeFile( id, true ) <span class="return">⇒ undefined</span> </li> </ul> <p>参数: </p> <ul class="params-list"><li><span class="meta"><code>file</code> {File, id}</span><p>File对象或这File对象的id</p> </li></ul> <p>移除某一文件, 默认只会标记文件状态为已取消，如果第二个参数为 <code>true</code> 则会从 queue 中移除。</p> {% highlight javascript %} $li.on('click', '.remove-this', function() { uploader.removeFile( file ); }) {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_getFiles" >getFiles </h3> <ul class="signature"> <li>getFiles() <span class="return">⇒ Array</span> </li> <li>getFiles( status1, status2, status... ) <span class="return">⇒ Array</span> </li> </ul> <p>返回指定状态的文件集合，不传参数将返回所有状态的文件。</p> {% highlight javascript %} console.log( uploader.getFiles() ); // => all files console.log( uploader.getFiles('error') ) // => all error files. {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_retry" >retry </h3> <ul class="signature"> <li>retry() <span class="return">⇒ undefined</span> </li> <li>retry( file ) <span class="return">⇒ undefined</span> </li> </ul> <p>重试上传，重试指定文件，或者从出错的文件开始重新上传。</p> {% highlight javascript %} function retry() { uploader.retry(); } {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_sort" >sort </h3> <ul class="signature"> <li>sort( fn ) <span class="return">⇒ undefined</span> </li> </ul> <p>排序队列中的文件，在上传之前调整可以控制上传顺序。</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_reset" >reset </h3> <ul class="signature"> <li>reset() <span class="return">⇒ undefined</span> </li> </ul> <p>重置uploader。目前只重置了队列。</p> {% highlight javascript %} uploader.reset(); {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_predictRuntimeType" >predictRuntimeType </h3> <ul class="signature"> <li>predictRuntimeType() <span class="return">⇒ String</span> </li> </ul> <p>预测Uploader将采用哪个<code>Runtime</code></p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_upload" >upload </h3> <ul class="signature"> <li>upload() <span class="return">⇒ undefined</span> </li> <li>upload( file | fileId) <span class="return">⇒ undefined</span> </li> </ul> <p>开始上传。此方法可以从初始状态调用开始上传流程，也可以从暂停状态调用，继续上传流程。</p> <p>可以指定开始某一个文件。</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_stop" >stop </h3> <ul class="signature"> <li>stop() <span class="return">⇒ undefined</span> </li> <li>stop( true ) <span class="return">⇒ undefined</span> </li> <li>stop( file ) <span class="return">⇒ undefined</span> </li> </ul> <p>暂停上传。第一个参数为是否中断上传当前正在上传的文件。</p> <p>如果第一个参数是文件，则只暂停指定文件。</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_cancelFile" >cancelFile </h3> <ul class="signature"> <li>cancelFile( file ) <span class="return">⇒ undefined</span> </li> <li>cancelFile( id ) <span class="return">⇒ undefined</span> </li> </ul> <p>参数: </p> <ul class="params-list"><li><span class="meta"><code>file</code> {File, id}</span><p>File对象或这File对象的id</p> </li></ul> <p>标记文件状态为已取消, 同时将中断文件传输。</p> {% highlight javascript %} $li.on('click', '.remove-this', function() { uploader.cancelFile( file ); }) {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_isInProgress" >isInProgress </h3> <ul class="signature"> <li>isInProgress() <span class="return">⇒ Boolean</span> </li> </ul> <p>判断<code>Uplaoder</code>是否正在上传中。</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_skipFile" >skipFile </h3> <ul class="signature"> <li>skipFile( file ) <span class="return">⇒ undefined</span> </li> </ul> <p>掉过一个文件上传，直接标记指定文件为已上传状态。</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_request" >request </h3> <ul class="signature"> <li>request( command, args ) <span class="return">⇒ * | Promise</span> </li> <li>request( command, args, callback ) <span class="return">⇒ Promise</span> </li> </ul> <p>发送命令。当传入<code>callback</code>或者<code>handler</code>中返回<code>promise</code>时。返回一个当所有<code>handler</code>中的promise都完成后完成的新<code>promise</code>。</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_Uploader_register" >Uploader.register </h3> <ul class="signature"> <li>Uploader.register(proto); </li> <li>Uploader.register(map, proto); </li> </ul> <p>参数: </p> <ul class="params-list"><li><span class="meta"><code>responseMap</code> {object}</span><p>API 名称与函数实现的映射</p> </li><li><span class="meta"><code>proto</code> {object}</span><p>组件原型，构造函数通过 constructor 属性定义</p> </li></ul> <p>添加组件</p> {% highlight javascript %} Uploader.register({ 'make-thumb': 'makeThumb' }, { init: function( options ) {}, makeThumb: function() {} }); Uploader.register({ 'make-thumb': function() { } }); {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Uploader_Uploader_unRegister" >Uploader.unRegister </h3> <ul class="signature"> <li>Uploader.unRegister(name); </li> </ul> <p>参数: </p> <ul class="params-list"><li><span class="meta"><code>name</code> {string}</span><p>组件名字</p> </li></ul> <p>删除插件，只有在注册时指定了名字的才能被删除。</p> {% highlight javascript %} Uploader.register({ name: 'custom', 'make-thumb': function() { } }); Uploader.unRegister('custom'); {% endhighlight %} </article> </div> <hr /> <div class="clearfix category"> <h2 id="WebUploader_Base">Base</h2> <p>基础类，提供一些简单常用的方法。</p> <article class="clearfix method"> <h3 id="WebUploader_Base_create" >create </h3> <ul class="signature"> <li>Base.create( opts ) <span class="return">⇒ Uploader</span> </li> </ul> <p>创建Uploader实例，等同于new Uploader( opts );</p> </article> <article class="clearfix property"> <h3 id="WebUploader_Base_version" >version </h3> <p> 当前版本号。</p> </article> <article class="clearfix property"> <h3 id="WebUploader_Base_" >$ </h3> <p> 引用依赖的jQuery或者Zepto对象。</p> </article> <article class="clearfix property"> <h3 id="WebUploader_Base_browser" >browser </h3> <p>简单的浏览器检查结果。</p> <ul> <li><code>webkit</code> webkit版本号，如果浏览器为非webkit内核，此属性为<code>undefined</code>。</li> <li><code>chrome</code> chrome浏览器版本号，如果浏览器为chrome，此属性为<code>undefined</code>。</li> <li><code>ie</code> ie浏览器版本号，如果浏览器为非ie，此属性为<code>undefined</code>。<strong>暂不支持ie10+</strong></li> <li><code>firefox</code> firefox浏览器版本号，如果浏览器为非firefox，此属性为<code>undefined</code>。</li> <li><code>safari</code> safari浏览器版本号，如果浏览器为非safari，此属性为<code>undefined</code>。</li> <li><code>opera</code> opera浏览器版本号，如果浏览器为非opera，此属性为<code>undefined</code>。</li> </ul> </article> <article class="clearfix property"> <h3 id="WebUploader_Base_os" >os </h3> <p>操作系统检查结果。</p> <ul> <li><code>android</code> 如果在android浏览器环境下，此值为对应的android版本号，否则为<code>undefined</code>。</li> <li><code>ios</code> 如果在ios浏览器环境下，此值为对应的ios版本号，否则为<code>undefined</code>。</li> </ul> </article> <article class="clearfix method"> <h3 id="WebUploader_Base_inherits" >inherits </h3> <ul class="signature"> <li>Base.inherits( super ) <span class="return">⇒ child</span> </li> <li>Base.inherits( super, protos ) <span class="return">⇒ child</span> </li> <li>Base.inherits( super, protos, statics ) <span class="return">⇒ child</span> </li> </ul> <p>参数: </p> <ul class="params-list"><li><span class="meta"><code>super</code> {Class}</span><p>父类</p> </li><li><span class="meta"><code>protos</code> {Object, Function} [可选]</span><p>子类或者对象。如果对象中包含constructor，子类将是用此属性值。</p> <ul class="params-list"><li><span class="meta"><code>constructor</code> {Function} [可选]</span><p>子类构造器，不指定的话将创建个临时的直接执行父类构造器的方法。</p> </li></ul></li><li><span class="meta"><code>statics</code> {Object} [可选]</span><p>静态属性或方法。</p> </li></ul> <p>返回值: </p> <ul class="params-list"><li><span class="meta"> {Class}</span><p>返回子类。</p> </li></ul> <p>实现类与类之间的继承。</p> {% highlight javascript %} function Person() { console.log( 'Super' ); } Person.prototype.hello = function() { console.log( 'hello' ); }; var Manager = Base.inherits( Person, { world: function() { console.log( 'World' ); } }); // 因为没有指定构造器，父类的构造器将会执行。 var instance = new Manager(); // => Super // 继承子父类的方法 instance.hello(); // => hello instance.world(); // => World // 子类的__super__属性指向父类 console.log( Manager.__super__ === Person ); // => true {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Base_noop" >noop </h3> <p>一个不做任何事情的方法。可以用来赋值给默认的callback.</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Base_bindFn" >bindFn </h3> <ul class="signature"> <li>Base.bindFn( fn, context ) <span class="return">⇒ Function</span> </li> </ul> <p>返回一个新的方法，此方法将已指定的<code>context</code>来执行。</p> {% highlight javascript %} var doSomething = function() { console.log( this.name ); }, obj = { name: 'Object Name' }, aliasFn = Base.bind( doSomething, obj ); aliasFn(); // => Object Name {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Base_log" >log </h3> <ul class="signature"> <li>Base.log( args... ) <span class="return">⇒ undefined</span> </li> </ul> <p>引用Console.log如果存在的话，否则引用一个<a href="#WebUploader_Base_noop">空函数noop</a>。</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Base_slice" >slice </h3> <ul class="signature"> <li>Base.slice( target, start[, end] ) <span class="return">⇒ Array</span> </li> </ul> <p>被<a href="http://www.2ality.com/2011/11/uncurrying-this.html">uncurrythis</a>的数组slice方法。将用来将非数组对象转化成数组对象。</p> {% highlight javascript %} function doSomthing() { var args = Base.slice( arguments, 1 ); console.log( args ); } doSomthing( 'ignored', 'arg2', 'arg3' ); // => Array ["arg2", "arg3"] {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Base_guid" >guid </h3> <ul class="signature"> <li>Base.guid() <span class="return">⇒ String</span> </li> <li>Base.guid( prefx ) <span class="return">⇒ String</span> </li> </ul> <p>生成唯一的ID</p> </article> <article class="clearfix method"> <h3 id="WebUploader_Base_formatSize" >formatSize </h3> <ul class="signature"> <li>Base.formatSize( size ) <span class="return">⇒ String</span> </li> <li>Base.formatSize( size, pointLength ) <span class="return">⇒ String</span> </li> <li>Base.formatSize( size, pointLength, units ) <span class="return">⇒ String</span> </li> </ul> <p>参数: </p> <ul class="params-list"><li><span class="meta"><code>size</code> {Number}</span><p>文件大小</p> </li><li><span class="meta"><code>pointLength</code> {Number} [可选] [默认值: 2] </span><p>精确到的小数点数。</p> </li><li><span class="meta"><code>[units=[</code> {Array}</span><p>'B', 'K', 'M', 'G', 'TB' ]] 单位数组。从字节，到千字节，一直往上指定。如果单位数组里面只指定了到了K(千字节)，同时文件大小大于M, 此方法的输出将还是显示成多少K.</p> </li></ul> <p>格式化文件大小, 输出成带单位的字符串</p> {% highlight javascript %} console.log( Base.formatSize( 100 ) ); // => 100B console.log( Base.formatSize( 1024 ) ); // => 1.00K console.log( Base.formatSize( 1024, 0 ) ); // => 1K console.log( Base.formatSize( 1024 * 1024 ) ); // => 1.00M console.log( Base.formatSize( 1024 * 1024 * 1024 ) ); // => 1.00G console.log( Base.formatSize( 1024 * 1024 * 1024, 0, ['B', 'KB', 'MB'] ) ); // => 1024MB {% endhighlight %} </article> <article class="clearfix method"> <h3 id="WebUploader_Base_Deferred" >Deferred </h3> <ul class="signature"> <li>Base.Deferred() <span class="return">⇒ Deferred</span> </li> </ul> <p>创建一个<a href="http://api.jquery.com/category/deferred-object/">Defe