Uploader模块管理网络上传任务，用于从本地上传各种文件到服务器，并支持跨域访问操作。通过plus.uploader可获取上传管理对象。Uploader上传使用HTTP的POST方式提交数据，数据格式符合Multipart/form-data规范，即rfc1867(Form-based File Upload in HTML)协议。
方法：
clear: 清除上传任务
startAll: 开始所有上传任务
对象：
Upload: Upload对象管理一个上传任务
UploadState: 上传任务的状态，Number类型
UploadOptions: JSON对象，创建上传任务的参数
UploadFileOptions: JSON对象，添加上传文件的参数
回调方法：
权限：
5+功能模块(permissions)
{
// ...
"permissions":{
// ...
"Uploader": {
"description": "文件上传，管理文件上传任务"
}
}
}
新建上传任务
Upload plus.uploader.createUpload( url, options, completedCB );
说明：
请求上传管理创建新的上传任务，创建成功则返回Upload对象，用于管理上传任务。
参数：
url:
(
String
)
必选要上传文件的目标地址
上传服务器的url地址，仅支持http或https协议。
允许创建多个相同url地址的上传任务。
options:
可通过此参数设置定义上传任务属性，如请求类型、上传优先级等。
completedCB:
当上传任务提交完成时触发，成功或失败都会触发。
返回值：
Upload
: Upload对象
示例：
// 创建上传任务
function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do",
{ method:"POST",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();
}
清除上传任务
plus.uploader.clear( state );
说明：
清除指定状态的上传任务。
参数：
state:
如果未指定state值，则清除所有未完成的上传任务。
返回值：
void
: 无
枚举上传任务
plus.uploader.enumerate( enumCB, state );
说明：
枚举指定状态的上传任务列表，通过enumCB回调函数返回结果。
参数：
enumCB:
枚举上传任务完成时触发。
state:
如果未指定state值，则枚举所有未完成的上传任务。
返回值：
void
: 无
示例：
// 枚举上传任务
function enumerateUpload() {
plus.uploader.enumerate( function ( tasks ) {
alert( "Unfinished task count: " + tasks.length );
} );
}
开始所有上传任务
plus.uploader.startAll();
说明：
开始所有处于未开始调度或暂停状态的上传任务。
若上传任务数超过可并发处理的总数，超出的任务处于调度状态(等待上传)，当有任务完成时根据调度状态任务的优先级选择任务开始上传。
参数：
无
返回值：
void
: 无
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();
}
属性：
id: 上传任务的标识
url: 上传文件的服务器地址
state: 任务的状态
options: 上传任务的参数
responseText: 上传任务完成后服务器返回的数据
uploadedSize: 已完成上传数据的大小)
totalSize: 上传数据的总大小
方法：
addFile: 添加上传文件
addData: 添加上传数据
start: 开始上传任务
pause: 暂停上传任务
resume: 恢复暂停的上传任务
abort: 取消上传任务
getResponseHeader: 获取上传请求指定的HTTP响应头部的值
setRequestHeader: 设置上传请求的HTTP头数据
上传任务的标识
download.id;
说明：
String
类型
只读属性
在创建任务时系统自动分配，用于标识上传任务的唯一性。
上传文件的服务器地址
upload.url;
说明：
String
类型
只读属性
调用plus.uploader.createUpload()方法创建上传任务时设置的值。
任务的状态
upload.state;
说明：
Number
类型
只读属性
上传任务的状态，参考UploadState，在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。
上传任务的参数
upload.options;
说明：
上传任务配置的参数，参考UploadOptions。
上传任务完成后服务器返回的数据
upload.responseText;
说明：
String
类型
只读属性
表示当前上传任务的状态，可通过addEventListener()方法监听statechanged事件监听任务状态的变化。
已完成上传数据的大小)
upload.UploadedSize;
说明：
Number
类型
只读属性
整数类型，单位为字节(byte)，上传任务开始传输数据时，每次触发statechanged事件或上传任务完成更新。
上传数据的总大小
upload.totalSize;
说明：
Number
类型
只读属性
整数类型，单位为字节(byte)，上传任务开始传输数据时更新。
添加上传文件
Boolean upload.addFile( path, options );
说明：
向上传任务中添加文件，必须在任务开始上传前调用。
以下情况会导致添加上传文件失败：
1. options参数中指定的key在任务中已经存在，则添加失败返回false；
2. path参数指定的文件路径不合法或文件不存在，则添加失败返回false；
3. 上传任务已经开始调度，调用此方法则添加失败返回false。
参数：
path:
(
String
)
必选添加上传文件的路径
仅支持本地文件路径。
options:
可通过此参数设置上传任务属性，如文件标识、文件名称、文件类型等。
返回值：
Boolean
:
添加文件成功返回true，失败则返回false。
示例：
// 创建上传任务
function createUpload() {
var task = plus.uploader.createUpload( "http://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();
}
添加上传数据
Boolean upload.addData( key, value );
说明：
向上传任务中添加数据，必须在任务开始上传前调用。
以下情况会导致添加上传文件失败：
1. key参数中指定的键名在任务中已经存在，则添加失败返回false；
2. 上传任务已经开始调度，调用此方法则添加失败返回false。
参数：
key:
(
String
)
必选添加上传数据的键名
value:
(
String
)
必选添加上传数据的键值
返回值：
Boolean
:
添加成功返回true，失败则返回false。
示例：
// 创建上传任务
function createUpload() {
var task = plus.uploader.createUpload( "http://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();
}
开始上传任务
void upload.start();
说明：
开始调度上传任务，如果任务已经处于开始状态则无任何响应。
在创建任务或任务上传失败后调用可重新开始上传。
参数：
无
返回值：
void
: 无
示例：
// 创建上传任务
function createUpload() {
var task = plus.uploader.createUpload( "http://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();
}
暂停上传任务
void upload.pause();
说明：
暂停上传任务，如果任务已经处于初始状态或暂停状态则无任何响应。
参数：
无
返回值：
void
: 无
示例：
var task=null;
// 创建上传任务
function createUpload() {
var task = plus.uploader.createUpload( "http://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();
}
恢复暂停的上传任务
void upload.resume();
说明：
继续暂停的上传任务，如果任务处于非暂停状态则无任何响应。
参数：
无
返回值：
void
: 无
示例：
var task = null;
// 创建上传任务
function createUpload() {
var task = plus.uploader.createUpload( "http://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();
}
取消上传任务
void upload.abort();
说明：
如果任务未完成，则终止上传，并从任务列表中删除。
参数：
无
返回值：
void
: 无
示例：
var task = null;
// 创建上传任务
function createUpload() {
var task = plus.uploader.createUpload( "http://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.pause();
}
添加上传任务事件监听器
void upload.addEventListener( type, listener, capture );
说明：
上传任务添加事件监听器后，当监听的事件发生时触发listener回调。
参数：
type:
listener:
当监听的事件发生时，触发设置的回调函数。
capture:
(
Boolean
)
可选事件流处理顺序，暂不支持
返回值：
void
: 无
示例：
var task = null;
// 监听上传任务状态
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.abort();
}
获取上传请求HTTP响应头部信息
String upload.getAllResponseHeaders();
说明：
HTTP响应头部全部内容作为未解析的字符串返回，如果没有接收到这个HTTP响应头数据或者上传请求未完成则为空字符串。
参数：
无
返回值：
String
: HTTP响应头数据
示例：
var task = null;
// 监听上传任务状态
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( "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();
}
获取上传请求指定的HTTP响应头部的值
String upload.getResponseHeader( headerName );
说明：
其参数是要返回的HTTP响应头部的名称，可以使用任何大小写来制定这个头部名字，和响应头部的比较是不区分大小写的。
如果没有接收到这个头部或者伤处请求未完成则为空字符串；如果接收到多个有指定名称的头部，这个头部的值被连接起来并返回，使用逗号和空格分隔开各个头部的值。
参数：
headerName:
(
String
)
可选HTTP响应头数据名称
返回值：
String
: HTTP响应头数据值
示例：
var task = null;
// 监听上传任务状态
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( "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();
}
设置上传请求的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”的值。
示例：
var task = null;
// 监听上传任务状态
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( "http://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();
}
上传任务事件类型
常量：
"statechanged": (String
类型
)上传任务状态变化事件
当上传任务状态发生变化时触发此事件，事件原型参考UploadStateChangedCallback。
示例：
var task = null;
// 监听上传任务状态
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.abort();
}
上传任务的状态，Number类型
常量：
undefined: (undefined
类型
)上传任务未开始
通过plus.uploader.createUpload()方法创建上传任务后的初始状态，此时可调用其start()方法开始上传。
0: (number
类型
)上传任务开始调度
调用上传任务的start()方法之后处于此状态，此时上传任务处于可调度上传状态。
1: (number
类型
)上传任务开始请求
上传任务建立网络连接，发送请求到服务器并等待服务器的响应。
2: (number
类型
)上传任务请求已经建立
上传任务网络连接已建立，服务器返回响应，准备传输数据内容。
3: (number
类型
)上传任务提交数据
上传任务提交数据，监听statechanged事件时可多次触发此状态。
4: (number
类型
)上传任务已完成
上传任务完成数据提交并断开连接，上传成功或失败都会设置为此状态。
5: (number
类型
)上传任务已暂停
调用上传任务的pause()方法将任务暂停，此时可调用其resume()方法重新开始上传。
-1: (number
类型
)枚举任务状态
非上传任务状态，泛指所有上传任务的状态，用于enumerate()和clear()操作时指定作用于所有上传任务。
JSON对象，创建上传任务的参数
属性：
blocksize: (Number
类型
)【已废弃】支持断点续传时，上传任务每次上传的文件块大小
数值类型，单位为Byte(字节)，默认值为102400，若设置值小于等于0则表示不分块上传。
chunkSize: (Number
类型
)分块上传的大小
单位为Kb，设置值小于等于0则不分块上传，默认为不分块上传。
Android平台需设置分块上传才能准确触发statechanged返回上传进度，如果不设置分块上传则在开始后快速返回上传完成进度，而实际并没有上传完。
注意：分块上传需要服务器支持，如果服务器不支持则会上传失败。
平台支持
Android - ALL (支持)
iOS - ALL (不支持)
:
忽略此属性
method: (String
类型
)网络请求类型
仅支持http协议的“POST”请求。
priority: (Number
类型
)上传任务的优先级
数值类型，数值越大优先级越高，默认优先级值为0。
retry: (Number
类型
)上传任务重试次数
数值类型，默认为重试3次。
retryInterval: (Number
类型
)上传任务重试间隔时间
数值类型，单位为s(秒)，默认值为30s。
timeout: (Number
类型
)上传任务超时时间
数值类型，单位为s(秒)，默认值为120s。
超时时间为服务器响应请求的时间(不是上传任务完成的总时间)，如果设置为0则表示永远不超时。
JSON对象，添加上传文件的参数
属性：
key: (String
类型
)文件键名
上传文件在上传任务中的键名，默认值为为文件名称。
上传任务中如果已经存在相同key的上传文件或数据将导致添加文件失败。
name: (String
类型
)文件名称
上传文件的名称，默认值为上传文件路径中的名称。
mime: (String
类型
)文件类型
上传文件的类型(如图片文件为“image/jpeg”)，默认值自动根据文件后缀名称生成。
上传任务完成时的回调函数
void uploadCompleted( Upload upload, Number status ) {
// File upload completed code.
}
说明：
在上传任务完成时调用，上传任务失败也将触发此回调。
参数：
upload:
status:
(
Number
)
必选上传结果状态码
HTTP传输协议状态码，如果未获取传输状态则其值则为0，如上传成功其值通常为200。
返回值：
void
: 无
上传任务状态变化回调函数，在上传任务状态发生变化时调用
void onStateChanged( Upload upload, status ) {
// Upload state changed code.
}
参数：
upload:
status:
(
Number
)
必选上传结果状态码
HTTP传输协议状态码，如果未获取传输状态则其值则为0，如上传成功其值通常为200。
返回值：
void
: 无
枚举上传任务回调函数，在枚举上传任务完成时时调用
void onEnumerated( Upload[] uploads ) {
// Upload enumerate completed code.
}
参数：
uploads:
(
Array[Upload]
)
必选枚举到的上传任务对象数组
返回值：
void
: 无
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
