#HotTrans 使用文档 -------- ## 简介 -------- HotTrans 是一个基于 jQuery 的,适用于当代浏览器的 Ajax 文件传输插件。HotTrans 使用了 FormData、XMLHttpRequest、Files、rem 等技术, 因此不适用于老版本浏览器。 请注意,HotTrans 是专门针对移动端设计的插件,其单位是基于 rem 的。 浏览器兼容性: Chrome | Safari | iOS Safari | Android Browser | UC Browser for Android ----|------|----|----|---- 7+ | 5+ | 5.1+ | 3+ | 11+ <br/> <br/> <br/> ## 快速开始 -------- HotTrans 只有一个 js 文件,不依赖 CSS,其样式会自动生成至元素行内。如果您需要对HotTrans的部分样式进行修改,您可以参见下面 style 参数的传递设置。 您使用时,需引入 HotTrans.min.js 文件:(在此之前你可能还需要引入 jQuery 文件) ``` <script src="http://static.hooperui.com/hottrans.min.js"></script> ``` 接下来,您需要在上传文件的位置设置一个 `file input` ``` <input type="file"> ``` 当然,这个 input 的样子并不容易改变,但幸运的是您选择了 HotTrans ! 现在,您可以像 div 一样随性、方便的使用 file input 标签,只需为input添加 class 和 style,HotTrans 便会自动转换成你想要的样式。 插件不会解绑你绑定在这个input上的任何事件,也不会删除你的重要 attr。 **请注意!请不要通过 class 选择器为这个 input 绑定事件!因为 HotTrans 会对这个 input 的 class 进行特殊处理。您可以使用 name、id 等其他可以找到这个 input 的方式为这个 input 绑定事件。** ``` <input type="file" multiple="true" class="yourClassName" id="yourId" style="background: red"> ``` 最后一步,调用 `$().hotTrans` 方法。 ``` <script> $("#yourId").hotTrans({ "url":"http://yourURL.com/upload.php" }); </script> ``` 大功告成! <br/> <br/> <br/> ## 参数详解 -------- 在调用 `$().hotTrans` 方法时,可传递不同的参数,下方列举并详细说明了所有参数的意义。 ``` <script> $("#yourId").hotTrans({ "text":"选择附件", "fileType":"all", "url":"", "data":{}, "delete":true, "stream":"multiple", "size":"20M", "styles":{}, "messages":[], "transstart":function(index){}, "success":function(index,res){}, "deleteFn":function(index){}, "callback":function(){} }); </script> ``` 参数名称 | 意义 | 可取值 ----|------|---- text | 生成的按钮上显示的文字 | 此项可不设置(默认值为`"选择附件"`)<br/>可设置为任意 `String` 类型的值 fileType | 允许上传的文件类型 | 此项可不设置(默认值为`"all"`)<br/>可设置为 `"all"`,意思是文件格式不限<br/>可设置为数组,如 `["jpg","png","doc"]`,数组内格式均为**小写**,意思是所有可支持的格式 url | 上传的后端接口 | 此项必填 data | 传送文件的时候向后端同时传递的参数(如身份信息等) | 此项可不设置(默认为空) delete | 是否显示删除按钮 | 此项可不设置(默认值为`"true"`) stream | 后端接口可支持的文件流 | 此项可不设置(默认值为`"multiple"`)<br/>可设置为 `"single"`,意思是后端接口不支持批量上传文件,如果这里用户一次选择了多个文件,HotTrans会自动分割为单个文件逐一上传<br/>可设置为 `"multiple"`,意思是后端接口支持批量上传文件,不管用户选择了多少文件,都会直接一次性上传 size | 每个文件允许的最大体积 | 此项可不设置(默认值为`"20M"`)<br/>可设置为任意大小,但必须以Mb为单位,以数字开始的字符串 messages | 检测到有问题的文件时给用户的提示 | 此项可不设置<br/>HotTrans 会优先保证上传,当检测文件的格式和大小时,如果出现了不合格的文件会自动过滤,留下合格的文件继续上传。如果全部不合格,会给出错误提示。<br/>请按如下顺序设置数组:<br/>`["选择的文件中有一部分文件有问题被自动过滤的提示文字","没有选择文件的提示文字",["选择的文件的大小超出限制的提示文字","所选文件中有一部分文件大小不符合导致上传中止"],["选择的文件格式错误的提示文字","选择的文件中有一部分不符合类型导致停止上传的提示文字"]]` transstart | 文件上传开始时调用 | 此项可不设置(默认什么也不做)<br/>可设置为任意 `Function` 类型的值,在文件开始上传的时候调用,注意,此时文件的类型和大小已经校验合格,且上传进度已经开始。其中可设置一个传参,参数是文件索引 index。(在 `"stream"` 设置为 `"multiple"` 的时候没有索引 index 传参) success | 后端接口成功返回后调用 | 此项可不设置(默认什么也不做)<br/>可设置为任意 `Function` 类型的值,其中可设置两个传参,第一个参数是文件索引 index ,后面一个参数会接收后端的返回值 res 。<br/>这个接口在 `"stream"` 设置为 `"single"` 的时候使用比较普遍,用来存储所有文件上传后,后端返回的每一个文件的地址。**注意,当设置为multiple的时候, function 只有一个参数 res,没有文件索引。** deleteFn | 删除一个文件的时候调用 | 此项可不设置(默认什么也不做)<br/>可设置为任意 `Function` 类型的值,内含一个参数,这个参数是当前删除的文件的索引,可以直接拿存储所有文件的数组 splice 该索引值即可 callback | 所有文件上传完毕后调用 | 此项可不设置(默认什么也不做)<br/>可设置为任意 `Function` 类型的值,在所有文件上传完毕后会调用。请注意,该函数的优先级比 `"success"` 回调的优先级低 styles | 个性化样式 | 详见“原理、结构与个性化”章节 <br/> <br/> <br/> ## 原理、结构与个性化 -------- 在您调用 `$().hotTrans` 方法后,我们会对您的 `file input` 进行包装。前后对比如下: ``` <input type="file" multiple="true" class="yourClassName" id="yourId" style="background: red"> ``` ↓↓↓↓↓ ``` <ul id="hot-trans-list" ></ul> <div style="background: red" class="yourClassName"> <span id="transBtnTest">选择附件</span> <input type="file" multiple="true" class="" id="yourId" > </div> <div id="hot-trans-tip"></div> ``` 上面的变化可以看到,我们对您的 `file input` 做了如下包装: * 在 input 外围添加了 div,并用专门的 `span#transBtnTest` 来呈现按钮上显示的文字 * 将 input 上所有的 style 和 class 转移到了上一步创建的 div 上(这也是为何不让你通过 class 选择器为 input 绑定事件的原因) * 在 input 上方,添加了一个 `ul#hot-trans-list` 标签,用于存放用户选择的文件列表 * 在 input 下方,添加了一个 `ul#hot-trans-tip` 标签,用于展示错误信息,这个标签默认是隐藏的 当您选择文件后,会在 `ul#hot-trans-list` 中自动添加 li,显示文件名和进度,其结构是这样的: ``` <ul id="hot-trans-list"> <li> 文件名称.扩展名 <span class="hot-trans-bar"></span> <span class="hot-trans-percent">上传进度</span> </li> </ul> ``` `span#hot-trans-bar` 是上传进度条,其默认的样式为: ``` processBar:{ "position":"absolute", "bottom":"0", "left":"0", "height":"2px", "border-radius":"3px", "width":"0", //"background":"#ECF0F1", "background":"-webkit-linear-gradient(left, #2ECC71 0%,#3498DB 100%)", "z-index":"-1", "transition":"all .2s", "-webkit-transition":"all .2s" } ``` 在上传中,会随着文件的上传进度实时的更新进度条的宽度,以及 `span#hot-trans-percent` 上传进度文字的内容。 从上面的配置文件可以看到,样式不是 css 而是一个 json配置文件。所以为了使 HotTrans 更加个性化,我们支持 json 格式的样式自定义。 参数就是您调用 `$().hotTrans` 方法时传递的 `"style"` 属性。 ``` var styles = { listItem:{}, processBar:{}, processBarNormal:{}, percentTip:{}, percentTipNormal:{}, input:{}, ul:{}, tip:{} } ``` 参数意义如下: 参数名称 | 意义 -----|------ listItem | 文件列表中的 li 的样式 processBar | `span#hot-trans-bar` 进度条上传中的样式 processBarNormal | `span#hot-trans-bar` 进度条上传完毕后的样式 percentTip | `span#hot-trans-percent` 上传进度文字上传中的样式 percentTipNormal | `span#hot-trans-percent` 上传进度文字上传完毕后的样式 input | 最原始的 file input 在执行了`$().hotTrans`后的样式(**不建议修改**) ul | 文件列表外层 ul 的样式 tip | 按钮下提示文字的样式 下面是所有 styles 的默认值 ``` var styles = { listItem:{ "position":"relative", "padding": "0 0 2px", "margin-bottom": "1px", "box-sizing":"border-box", "width":"100%", "padding-right":"4rem", "overflow":"hidden", "white-space":"nowrap", "text-overflow": "ellipsis" }, processBar:{ "position":"absolute", "bottom":"0", "left":"0", "height":"2px", "border-radius":"3px", "width":"0", "background":"-webkit-linear-gradient(left, #2ECC71 0%,#3498DB 100%)", "z-index":"-1", "transition":"all .2s", "-webkit-transition":"all .2s" }, processBarNormal:{ "height":"1px", "background":"#eee" }, percentTip:{ "float":"right", "position":"absolute", "top":"0", "right":"0", "font-size":"0.9rem", "line-height":"2.6rem" }, percentTipNormal:{ "color":"#27AE60" }, percentTipDelete:{ "color":"#3498DB" }, input:{ "opacity": "0", "position": "absolute", "width":"100%", "height": "inherit", "left":"0", "top":"0" }, ul:{ "font-size":"1rem", "line-height":"2.6rem", "color":"#333", "list-style":"none", "margin":"0", "padding":"0", "padding-bottom":"1rem" }, tip:{ "font-size":"0.8rem", "line-height":"2.6rem", "color":"#bbb" } }; ```