uploader
Uploader模块管理网络上传,用于从本地上传各种文件到网络,支持跨域访问操作。通过plus.uploader可获取上传管理对象。
方法:
- createUpload: 新建上传任务
- enumerate: 枚举应用的所有上传任务
- clear: 清除上传任务
- startAll: 开始所有上传任务
对象:
- Upload: Upload对象用于管理单个上传任务
- UploadState: 上传任务的状态,Number类型
- UploadOption: JSON对象,创建上传任务的参数
- UploadFileOption: JSON对象,创建上传文件选项的参数
回调方法:
- UploadCompletedCallback: 上传任务完成时的回调函数
- UploadStateChangedCallback: 上传任务状态变化回调函数,在上传任务状态发生变化时调用
- UploadEnumerateCallback: 枚举上传任务回调函数,在枚举上传任务完成时时调用
权限:
permissions
"Uploader": { "description": "管理上传任务" }
createUpload
新建上传任务
Upload plus.uploader.createUpload( url, option, completedCB );
说明:
请求上传管理创建新的上传任务。
参数:
- url:
(
DOMString
)
必选 要上传文件的目标地址
必须是支持http协议的服务器地址 - option:
(
UploadOption
)
可选 上传任务的参数
- completedCB:
(
UploadCompletedCallback
)
可选 上传任务完成后的回调函数
返回值:
Upload : Upload对象示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "http://www.test.com/upload.do", { method:"POST",blocksize:204800,priority:100 }, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.filename ); } else { alert( "Upload failed: " + status ); } } ); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); //task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } </script> </head> <body > <input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input> </body> </html>
enumerate
枚举应用的所有上传任务
plus.uploader.enumerate( enumCB, state );
说明:
枚举指定状态的上传任务列表。枚举操作完成后通过enumCB回调返回结果。
参数:
- enumCB:
(
UploadEnumerateCallback
)
必选 枚举操作完成后的回调函数
- state:
(
UploadState
)
可选 要枚举上传任务的状态
默认值为所有未完成的上传任务。
返回值:
void : 无示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { plus.uploader.enumerate( function ( tasks ) { alert( "Unfinished task count: " + tasks.length ); } ); } </script> </head> <body > Enumerate all unfinished upload task. </body> </html>
clear
清除上传任务
plus.uploader.clear( state );
说明:
清除指定状态的上传任务。
参数:
- state:
(
UploadState
)
可选 要清除上传任务的状态
默认值为所有已完成的上传任务。
返回值:
void : 无示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { plus.uploader.clear(); } </script> </head> <body > Clear all finished upload task. </body> </html>
startAll
开始所有上传任务
plus.uploader.startAll();
说明:
开始所有处于暂停状态的上传任务。若上传任务数超过可并发处理的总数,超出的任务处于调度状态(等待上传),当有任务完成时根据调度状态任务的优先级选择任务开始上传。
参数:
无
返回值:
void : 无示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { plus.uploader.startAll(); } </script> </head> <body > Start upload task. </body> </html>
Upload
Upload对象用于管理单个上传任务
属性:
- url: 上传文件的服务器地址
- state: 任务的状态
- options: 上传任务的参数
- responseText: 上传任务完成后服务器返回的数据
- uploadedSize: 已完成上传文件的大小,单位为字节(byte)
- totalSize: 上传任务文件的总大小,单位为字节(byte)
方法:
- addFile: 添加上传文件
- addData: 添加上传数据
- start: 开始上传任务
- pause: 停止上传任务
- resume: 恢复上传任务
- abort: 取消上传任务
- addEventListener: 添加上传任务事件监听器
url
上传文件的服务器地址
upload.url;
说明:
DOMString 类型 只读属性
上传任务的服务器地址,在创建任务时设置的值。
state
任务的状态
upload.state;
说明:
Number 类型 只读属性
上传任务的状态,参考UploadState,在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。
options
上传任务的参数
upload.options;
说明:
UploadOption 类型 只读属性
上传任务配置的参数,参考UploadOption。
responseText
上传任务完成后服务器返回的数据
upload.responseText;
说明:
DOMString 类型 只读属性
上传任务完成后服务器返回的数据,在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。
uploadedSize
已完成上传文件的大小,单位为字节(byte)
upload.UploadedSize;
说明:
Number 类型 只读属性
上传任务已完成上传文件的大小,在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。
totalSize
上传任务文件的总大小,单位为字节(byte)
upload.totalSize;
说明:
Number 类型 只读属性
上传任务要上传文件的总大小,在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。
addFile
添加上传文件
Boolean upload.addFile( path, option );
说明:
向上传任务中添加文件,必须在任务开始上传前调用。若指定的key在任务中已经存在则会添加失败,返回false。若添加的文件路径不合法或指定文件不存在,则任务添加操作失败,返回false。若任务已经开始上传,再次调用则会操作失败。
参数:
- path:
(
DOMString
)
必选 要添加上传文件的路径
- option:
(
UploadFileOption
)
必选 要添加上传文件的参数
返回值:
Boolean : 添加成功则返回true,添加失败则返回false。示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.filename ); } else { alert( "Upload failed: " + status ); } }); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); //task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } </script> </head> <body > <input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input> </body> </html>
addData
添加上传数据
Boolean upload.addData( key, value );
说明:
向上传任务中添加数据,必须在任务开始上传前调用。若指定的key在任务中已经存在则会添加失败,返回false。若任务已经开始上传,再次调用则会操作失败。
参数:
返回值:
Boolean : 添加成功则返回true,添加失败则返回false。示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.filename ); } else { alert( "Upload failed: " + status ); } }); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); //task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } </script> </head> <body > <input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input> </body> </html>
start
开始上传任务
upload.start();
说明:
开始上传任务,如果任务已经处于开始状态则无任何响应。通常在创建任务或任务失败后重新开始。
参数:
无
返回值:
void : 无示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.filename ); } else { alert( "Upload failed: " + status ); } }); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); //task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } </script> </head> <body > <input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input> </body> </html>
pause
停止上传任务
upload.pause();
说明:
停止上传任务,如果任务已经处于初始状态或暂停状态则无任何响应。通常在任务已开始后暂停任务。
参数:
无
返回值:
void : 无示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var task = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.filename ); } else { alert( "Upload failed: " + status ); } }); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); //task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } // 暂停上传任务 function pauseUpload() { task.pause(); } </script> </head> <body > <input type="button" value="Create upload task" onclick="createUpload();" ></input> <input type="button" value="Pause upload task" onclick="pauseUpload();" ></input> </body> </html>
resume
恢复上传任务
upload.resume();
说明:
恢复上传任务,当任务暂停后调用此方法继续上传操作。当任务不处于暂停状态,调用此方法将无任何作用。
参数:
无
返回值:
void : 无示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var task = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.filename ); } else { alert( "Upload failed: " + status ); } }); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); //task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } // 暂停上传任务 function pauseUpload() { task.pause(); } // 恢复上传任务 function resumeUpload() { task.resume(); } </script> </head> <body > <input type="button" value="Create upload task" onclick="createUpload();" ></input> <input type="button" value="Pause upload task" onclick="pauseUpload();" ></input> <input type="button" value="Resume upload task" onclick="resumeUpload();" ></input> </body> </html>
abort
取消上传任务
upload.abort();
说明:
取消上传任务,如果任务已经取消则无任何响应。如果任务未完成,将删除已上传的临时文件。如果任务已完成,将不删除已上传的文件。
参数:
无
返回值:
void : 无示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var task = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.filename ); } else { alert( "Upload failed: " + status ); } }); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); //task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } // 暂停上传任务 function pauseUpload() { task.pause(); } // 取消上传任务 function abortUpload() { task.pause(); } </script> </head> <body > <input type="button" value="Create upload task" onclick="createUpload();" ></input> <input type="button" value="Pause upload task" onclick="pauseUpload();" ></input> <input type="button" value="Abort upload task" onclick="abortUpload();" ></input> </body> </html>
addEventListener
添加上传任务事件监听器
upload.addEventListener( type, listener, capture );
说明:
上传任务添加事件监听器后,当任务事件发生时触发。
参数:
- type:
(
DOMString
)
必选 事件类型
- listener:
(
DOMString
)
必选 事件监听器回调函数
- capture:
(
Boolean
)
可选 事件流处理顺序,暂不支持
返回值:
void : 无示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Uploader Example</title> <script type="text/javascript" > // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); var task = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { } // 监听上传任务状态 function onStateChanged( upload, status ) { if ( upload.state == 4 && status == 200 ) { // 上传完成 alert( "Upload success: " + upload.getFileName() ); } } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "http://www.test.com/upload.do" ); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } // 暂停上传任务 function pauseUpload() { task.pause(); } // 取消上传任务 function abortUpload() { task.pause(); } </script> </head> <body > <input type="button" value="Create upload task" onclick="createUpload();" ></input> <input type="button" value="Pause upload task" onclick="pauseUpload();" ></input> <input type="button" value="Abort upload task" onclick="abortUpload();" ></input> </body> </html>
UploadState
上传任务的状态,Number类型
属性:
- 0: 初始状态,在创建之后触发此状态事件,上传任务处于可调度状态
- 1: 上传任务开始处理,开始建立网络连接
- 2: 上传任务请求已经接收,网络连接已建立
- 3: 上传任务请求处理中,上传过程中不断触发
- 4: 上传任务已完成(成功或失败)
- 5: 上传任务暂停状态,可重新开始
- -1: 非任务状态,用于enumerate()和claer()操作所有上传任务
0
初始状态,在创建之后触发此状态事件,上传任务处于可调度状态
说明:
number 类型
1
上传任务开始处理,开始建立网络连接
说明:
number 类型
2
上传任务请求已经接收,网络连接已建立
说明:
number 类型
3
上传任务请求处理中,上传过程中不断触发
说明:
number 类型
4
上传任务已完成(成功或失败)
说明:
number 类型
5
上传任务暂停状态,可重新开始
说明:
number 类型
-1
非任务状态,用于enumerate()和claer()操作所有上传任务
说明:
number 类型
UploadOption
JSON对象,创建上传任务的参数
属性:
- method: 网络请求类型,必须是http协议的“POST”
- blocksize: 上传任务每次上传的文件块大小(仅在支持断点续传的服务有效),单位为字节,默认值为102400,若设置值小于等于0则表示不分块上传
- priority: 上传任务的优先级,数值越大优先级越高
- timeout: 上传任务超时时间,单位为s,默认为120s
- retry: 上传任务重试次数,默认为3次
method
网络请求类型,必须是http协议的“POST”
说明:
DOMString 类型
blocksize
上传任务每次上传的文件块大小(仅在支持断点续传的服务有效),单位为字节,默认值为102400,若设置值小于等于0则表示不分块上传
说明:
number 类型
priority
上传任务的优先级,数值越大优先级越高
说明:
number 类型
timeout
上传任务超时时间,单位为s,默认为120s
说明:
number 类型
retry
上传任务重试次数,默认为3次
说明:
number 类型
UploadFileOption
JSON对象,创建上传文件选项的参数
属性:
key
文件标识
说明:
DOMString 类型
不设置则自动取文件名称,一个上传任务中如果添加相同key的上传字段将导致添加失败。
name
文件名称
说明:
DOMString 类型
不设置则自动取本地文件名称。
mime
文件类型
说明:
DOMString 类型
不设置则自动根据文件后缀名称生成。
UploadCompletedCallback
上传任务完成时的回调函数
void uploadCompleted( Upload upload, Number status ) { // File upload completed code. }
说明:
在上传任务完成时调用,上传任务失败也将触发此回调。
参数:
返回值:
void : 无UploadStateChangedCallback
上传任务状态变化回调函数,在上传任务状态发生变化时调用
void onStateChanged( Upload upload, status ) { // Upload state changed code. }
参数:
返回值:
void : 无UploadEnumerateCallback
枚举上传任务回调函数,在枚举上传任务完成时时调用
void onEnumerated( Upload[] uploads ) { // Upload enumerate completed code. }
参数:
- uploads:
(
Upload
)
必选 枚举到的上传任务对象数组