API Reference

Plugins

Native.js


uploader

Uploader模块管理网络上传任务,用于从本地上传各种文件到服务器,并支持跨域访问操作。通过plus.uploader可获取上传管理对象。Uploader上传使用HTTP的POST方式提交数据,数据格式符合Multipart/form-data规范,即rfc1867(Form-based File Upload in HTML)协议。

方法:

对象:

回调方法:

模块:

5+功能模块(permissions)


{
// ...
"permissions":{
	// ...
	"Uploader": {
		"description": "文件上传,管理文件上传任务"
	}
}
}			

createUpload

新建上传任务


Upload plus.uploader.createUpload( url, options, completedCB );
				

说明:

请求上传管理创建新的上传任务,创建成功则返回Upload对象,用于管理上传任务。

参数:

返回值:

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.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>
				

enumerate

枚举上传任务


plus.uploader.enumerate( enumCB, state );
				

说明:

枚举指定状态的上传任务列表,通过enumCB回调函数返回结果。

参数:

返回值:

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 );
				

说明:

清除指定状态的上传任务。

参数:

返回值:

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对象管理一个上传任务


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

上传任务的标识


download.id;
						

说明:

String 类型 只读属性

在创建任务时系统自动分配,用于标识上传任务的唯一性。

url

上传文件的服务器地址


upload.url;
						

说明:

String 类型 只读属性

调用plus.uploader.createUpload()方法创建上传任务时设置的值。

state

任务的状态


upload.state;
						

说明:

Number 类型 只读属性

上传任务的状态,参考UploadState,在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。

options

上传任务的参数


upload.options;
						

说明:

UploadOptions 类型 只读属性

上传任务配置的参数,参考UploadOptions。

responseText

上传任务完成后服务器返回的数据


upload.responseText;
						

说明:

String 类型 只读属性

表示当前上传任务的状态,可通过addEventListener()方法监听statechanged事件监听任务状态的变化。

uploadedSize

已完成上传数据的大小)


upload.UploadedSize;
						

说明:

Number 类型 只读属性

整数类型,单位为字节(byte),上传任务开始传输数据时,每次触发statechanged事件或上传任务完成更新。

totalSize

上传数据的总大小


upload.totalSize;
						

说明:

Number 类型 只读属性

整数类型,单位为字节(byte),上传任务开始传输数据时更新。

addFile

添加上传文件


Boolean upload.addFile( path, options );
						

说明:

向上传任务中添加文件,必须在任务开始上传前调用。 以下情况会导致添加上传文件失败: 1. options参数中指定的key在任务中已经存在,则添加失败返回false; 2. path参数指定的文件路径不合法或文件不存在,则添加失败返回false; 3. 上传任务已经开始调度,调用此方法则添加失败返回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.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>
						

addData

添加上传数据


Boolean upload.addData( key, value );
						

说明:

向上传任务中添加数据,必须在任务开始上传前调用。 以下情况会导致添加上传文件失败: 1. key参数中指定的键名在任务中已经存在,则添加失败返回false; 2. 上传任务已经开始调度,调用此方法则添加失败返回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.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>
						

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( "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();
}
	</script>
	</head>
	<body >
	<input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input>
	</body>
</html>
						

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( "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();
}
	</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

恢复暂停的上传任务


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( "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();
}
	</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

取消上传任务


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( "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();
}
	</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

添加上传任务事件监听器


void upload.addEventListener( type, listener, capture );
						

说明:

上传任务添加事件监听器后,当监听的事件发生时触发listener回调。

参数:

返回值:

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.abort();
}
	</script>
	</head>
	<body >
		<button onclick="createUpload()">Create upload task</button><br/>
		<button onclick="pauseUpload()">Pause upload task</button><br/>
		<button onclick="abortUpload()">Abort upload task</button><br/>
	</body>
</html>
						

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( "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();
}
	</script>
	</head>
	<body >
		<input type="button" value="Create upload task" onclick="createUpload();" ></input>
	</body>
</html>
						

getResponseHeader

获取上传请求指定的HTTP响应头部的值


String upload.getResponseHeader( headerName );
						

说明:

其参数是要返回的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( "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();
}
	</script>
	</head>
	<body >
		<input type="button" value="Create upload task" onclick="createUpload();" ></input>
	</body>
</html>
						

setRequestHeader

设置上传请求的HTTP头数据


void upload.setRequestHeader( headerName, headerValue );
						

说明:

Http的Header应该包含在通过后续start()调用而发起的请求中,此方法必需在调用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 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( "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();
}
	</script>
	</head>
	<body >
		<input type="button" value="Create upload task" onclick="createUpload();" ></input>
	</body>
</html>
						

UploadEvent

上传任务事件类型

常量:

示例:


<!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.abort();
}
	</script>
	</head>
	<body >
		<button onclick="createUpload()">Create upload task</button><br/>
		<button onclick="pauseUpload()">Pause upload task</button><br/>
		<button onclick="abortUpload()">Abort upload task</button><br/>
	</body>
</html>
				

UploadState

上传任务的状态,Number类型

常量:

UploadOptions

JSON对象,创建上传任务的参数

属性:

UploadFileOptions

JSON对象,添加上传文件的参数

属性:

key

文件键名

说明:

String 类型 可选属性

上传文件在上传任务中的键名,默认值为为文件名称。 上传任务中如果已经存在相同key的上传文件或数据将导致添加文件失败。

name

文件名称

说明:

String 类型 可选属性

上传文件的名称,默认值为上传文件路径中的名称。

mime

文件类型

说明:

String 类型

上传文件的类型(如图片文件为“image/jpeg”),默认值自动根据文件后缀名称生成。

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.
}
				

参数:

返回值:

void : 无