HTML5+规范:Uploader(管理网络上传任务)
Uploader模块管理网络上传任务,用于从本地上传各种文件到服务器,并支持跨域访问操作。通过plus.uploader可获取上传管理对象。Uploader上传使用HTTP的POST方式提交数据,数据格式符合Multipart/form-data规范,即rfc1867(Form-based File Upload in HTML)协议。
1、方法 1.1、createUpload: 新建上传任务Upload plus.uploader.createUpload( url, options, completedCB );
说明:请求上传管理创建新的上传任务,创建成功则返回Upload对象,用于管理上传任务。
参数:
url: ( String ) 必选 要上传文件的目标地址。上传服务器的url地址,仅支持http或https协议。 允许创建多个相同url地址的上传任务。
options: ( UploadOptions ) 可选 上传任务的参数。可通过此参数设置定义上传任务属性,如请求类型、上传优先级等。
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( "https://www.test.com/upload.do", { method:"POST",blocksize:204800,priority:100 }, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.url ); } 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>1.2、enumerate: 枚举上传任务
plus.uploader.enumerate( enumCB, state );
说明:枚举指定状态的上传任务列表,通过enumCB回调函数返回结果。
参数:
enumCB: ( UploadEnumerateCallback ) 必选 枚举上传任务回调函数。枚举上传任务完成时触发。
state: ( UploadState ) 可选 枚举上传任务的状态。如果未指定state值,则枚举所有未完成的上传任务。
返回值: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>1.3、clear: 清除上传任务
plus.uploader.clear( state );
说明:清除指定状态的上传任务。
参数:state: ( UploadState ) 可选 清除上传任务的状态。如果未指定state值,则清除所有未完成的上传任务。
返回值: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>1.4、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>2、对象 2.1、Upload: Upload对象管理一个上传任务
interface Upload {
readonly attribute String url;
readonly attribute Number state;
readonly attribute UploadOptions options;
readonly attribute String responseText;
readonly attribute Number uploadedSize;
readonly attribute Number totalSize;
function void abort();
function Boolean addData( String key, String value );
function void addEventListener( String event, function Callback listener, Boolean capture );
function Boolean addFile( String path, UploadFileOptions options );
function String getAllResponseHeaders();
function String getResponseHeader( headerName );
function void pause();
function void resume();
function void setRequestHeader( String headerName, String headerValue );
function void start();
}
2.1.1、属性:
(1)、id: 上传任务的标识
download.id;
说明:String 类型 只读属性。在创建任务时系统自动分配,用于标识上传任务的唯一性。
(2)、url: 上传文件的服务器地址
upload.url;
说明:String 类型 只读属性。调用plus.uploader.createUpload()方法创建上传任务时设置的值。
(3)、state: 任务的状态
upload.state;
说明:Number 类型 只读属性。上传任务的状态,参考UploadState,在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。
(4)、options: 上传任务的参数
upload.options;
说明:UploadOptions 类型 只读属性。上传任务配置的参数,参考UploadOptions。
(5)、responseText: 上传任务完成后服务器返回的数据
upload.responseText;
说明:String 类型 只读属性。表示当前上传任务的状态,可通过addEventListener()方法监听statechanged事件监听任务状态的变化。
(6)、uploadedSize: 已完成上传数据的大小
upload.UploadedSize;
说明:Number 类型 只读属性。整数类型,单位为字节(byte),上传任务开始传输数据时,每次触发statechanged事件或上传任务完成更新。
(7)、totalSize: 上传数据的总大小
upload.totalSize;
说明:Number 类型 只读属性。整数类型,单位为字节(byte),上传任务开始传输数据时更新。
2.1.2、方法:(1)、addFile: 添加上传文件
Boolean upload.addFile( path, options );
说明:向上传任务中添加文件,必须在任务开始上传前调用。 以下情况会导致添加上传文件失败: 1. options参数中指定的key在任务中已经存在,则添加失败返回false; 2. path参数指定的文件路径不合法或文件不存在,则添加失败返回false; 3. 上传任务已经开始调度,调用此方法则添加失败返回false。
参数:
path: ( String ) 必选 添加上传文件的路径。仅支持本地文件路径。
options: ( UploadFileOptions ) 必选 要添加上传文件的参数。可通过此参数设置上传任务属性,如文件标识、文件名称、文件类型等。
返回值: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( "https://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.url ); } 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>
(2)、addData: 添加上传数据
Boolean upload.addData( key, value );
说明:向上传任务中添加数据,必须在任务开始上传前调用。 以下情况会导致添加上传文件失败: 1. key参数中指定的键名在任务中已经存在,则添加失败返回false; 2. 上传任务已经开始调度,调用此方法则添加失败返回false。
参数:
key: ( String ) 必选 添加上传数据的键名
value: ( String ) 必选 添加上传数据的键值
返回值: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( "https://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.url ); } 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>
(3)、start: 开始上传任务
void 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( "https://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.url ); } 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>
(4)、pause: 暂停上传任务
void 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( "https://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.url ); } 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>
(5)、resume: 恢复暂停的上传任务
void 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( "https://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.url ); } 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>
(6)、abort: 取消上传任务
void 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( "https://www.test.com/upload.do", {}, function ( t, status ) { // 上传完成 if ( status == 200 ) { alert( "Upload success: " + t.url ); } 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.abort(); } </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>
(7)、addEventListener: 添加上传任务事件监听器
void upload.addEventListener( type, listener, capture );
说明:上传任务添加事件监听器后,当监听的事件发生时触发listener回调。
参数:
type: ( String ) 必选 事件类型
listener: ( UploadStateChangedCallback ) 必选 事件监听器回调函数
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( "https://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.abort(); } </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>
(8)、getAllResponseHeaders: 获取上传请求HTTP响应头部信息
String upload.getAllResponseHeaders();
说明:HTTP响应头部全部内容作为未解析的字符串返回,如果没有接收到这个HTTP响应头数据或者上传请求未完成则为空字符串。
返回值:String : HTTP响应头数据
示例:
<!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 ) { // 获取上传请求响应头数据 console.log(upload.getAllResponseHeaders()); // 上传完成 alert( "Upload success: " + upload.getFileName() ); } } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "https://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(); } </script> </head> <body > <input type="button" value="Create upload task" onclick="createUpload();" ></input> </body> </html>
(9)、getResponseHeader: 获取上传请求指定的HTTP响应头部的值
String upload.getResponseHeader( headerName );
说明:其参数是要返回的HTTP响应头部的名称,可以使用任何大小写来制定这个头部名字,和响应头部的比较是不区分大小写的。 如果没有接收到这个头部或者伤处请求未完成则为空字符串;如果接收到多个有指定名称的头部,这个头部的值被连接起来并返回,使用逗号和空格分隔开各个头部的值。
参数:headerName: ( String ) 可选 HTTP响应头数据名称
返回值:String : HTTP响应头数据值
示例:
<!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 ) { // 获取上传请求响应头中的Content-Type值 console.log(dtask.getResponseHeader("Content-Type")); // 上传完成 alert( "Upload success: " + upload.getFileName() ); } } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "https://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(); } </script> </head> <body > <input type="button" value="Create upload task" onclick="createUpload();" ></input> </body> </html>
(10)、setRequestHeader: 设置上传请求的HTTP头数据
void upload.setRequestHeader( headerName, headerValue );
说明:Http的Header应该包含在通过后续start()调用而发起的请求中,此方法必需在调用start()之前设置才能生效。 如果带有指定名称的头部已经被指定了,这个头部的新值就是:之前指定的值,加上逗号、以及这个调用指定的值(形成一个数组)。
参数:
headerName: ( String ) 必选 HTTP请求的头数据名称
headerValue: ( String ) 必选 HTTP请求的头数据值
返回值:void : 无
平台支持:Android - 2.2+ (支持): 不支持设置“Content-Type”、“User-Agent”、“Cookie”的值。iOS - 5.1+ (支持): 不支持设置“Content-Type”、“User-Agent”的值。
示例:
<!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 ) { // 获取上传请求响应头中的Content-Type值 console.log(dtask.getResponseHeader("Content-Type")); // 上传完成 alert( "Upload success: " + upload.getFileName() ); } } // 创建上传任务 function createUpload() { var task = plus.uploader.createUpload( "https://www.test.com/upload.do" ); task.addFile( "_www/a.doc", {key:"testdoc"} ); task.addData( "string_key", "string_value" ); // 设置自定义数据头 task.setRequestHeader('Customer','CustomerValue/XXXXXXXXXXXX'); task.addEventListener( "statechanged", onStateChanged, false ); task.start(); } </script> </head> <body > <input type="button" value="Create upload task" onclick="createUpload();" ></input> </body> </html>2.2、UploadState: 上传任务的状态,Number类型
常量:
(1)、undefined: (undefined 类型 )上传任务未开始。通过plus.uploader.createUpload()方法创建上传任务后的初始状态,此时可调用其start()方法开始上传。
(2)、0: (number 类型 )上传任务开始调度。调用上传任务的start()方法之后处于此状态,此时上传任务处于可调度上传状态。
(3)、1: (number 类型 )上传任务开始请求。上传任务建立网络连接,发送请求到服务器并等待服务器的响应。
(4)、2: (number 类型 )上传任务请求已经建立。上传任务网络连接已建立,服务器返回响应,准备传输数据内容。
(5)、3: (number 类型 )上传任务提交数据。上传任务提交数据,监听statechanged事件时可多次触发此状态。
(6)、4: (number 类型 )上传任务已完成。上传任务完成数据提交并断开连接,上传成功或失败都会设置为此状态。
(7)、5: (number 类型 )上传任务已暂停。调用上传任务的pause()方法将任务暂停,此时可调用其resume()方法重新开始上传。
(8)、-1: (number 类型 )枚举任务状态。非上传任务状态,泛指所有上传任务的状态,用于enumerate()和clear()操作时指定作用于所有上传任务。
2.3、UploadOptions: JSON对象,创建上传任务的参数属性:
(1)、method: (String 类型 )网络请求类型。仅支持http协议的“POST”请求。
(2)、blocksize: (number 类型 )上传任务每次上传的文件块大小(仅在支持断点续传的服务有效)。数值类型,单位为Byte(字节),默认值为102400,若设置值小于等于0则表示不分块上传。
(3)、priority: (number 类型 )上传任务的优先级。数值类型,数值越大优先级越高,默认优先级值为0。
(4)、timeout: (number 类型 )上传任务超时时间。数值类型,单位为s(秒),默认值为120s。 超时时间为服务器响应请求的时间(不是上传任务完成的总时间),如果设置为0则表示永远不超时。
(5)、retry: (number 类型 )上传任务重试次数。数值类型,默认为重试3次。
(6)、retryInterval: (Number 类型 )上传任务重试间隔时间。数值类型,单位为s(秒),默认值为30s
2.4、UploadFileOptions: JSON对象,添加上传文件的参数属性:
(1)、key: 文件键名。上传文件在上传任务中的键名,默认值为为文件名称。 上传任务中如果已经存在相同key的上传文件或数据将导致添加文件失败。
(2)、name: 文件名称。上传文件的名称,默认值为上传文件路径中的名称。
(3)、mime: 文件类型。上传文件的类型(如图片文件为“image/jpeg”),默认值自动根据文件后缀名称生成。
3、回调方法 3.1、UploadCompletedCallback: 上传任务完成时的回调函数void uploadCompleted( Upload upload, Number status ) {
// File upload completed code.
}
说明:在上传任务完成时调用,上传任务失败也将触发此回调。
参数:
upload: ( Upload ) 必选 上传任务对象
status: ( Number ) 必选 上传结果状态码。HTTP传输协议状态码,如果未获取传输状态则其值则为0,如上传成功其值通常为200。
返回值:void : 无
3.2、UploadStateChangedCallback: 上传任务状态变化回调函数,在上传任务状态发生变化时调用void onStateChanged( Upload upload, status ) {
// Upload state changed code.
}
参数:
upload: ( Upload ) 必选 上传任务对象
status: ( Number ) 必选 上传结果状态码。HTTP传输协议状态码,如果未获取传输状态则其值则为0,如上传成功其值通常为200。
返回值:void : 无
3.3、UploadEnumerateCallback: 枚举上传任务回调函数,在枚举上传任务完成时时调用void onEnumerated( Upload[] uploads ) {
// Upload enumerate completed code.
}
参数:uploads: ( Array[ Upload ] ) 必选 枚举到的上传任务对象数组
返回值:void : 无
上一篇: 使用C语言实现学生成绩管理系统