API Reference

Plugins

Native.js


downloader

Downloader模块管理网络文件下载任务,用于从服务器下载各种文件,并支持跨域访问操作。通过plus.downloader获取下载管理对象。Downloader下载使用HTTP的GET/POST方式请求下载文件,符合标准HTTP/HTTPS传输协议。

方法:

对象:

回调方法:

模块:

5+功能模块(permissions)


{
// ...
"permissions":{
	// ...
	"Downloader": {
		"description": "文件下载,管理文件下载任务"
	}
}
}
			

createDownload

新建下载任务


Download plus.downloader.createDownload( url, options, completedCB );
				

说明:

请求下载管理创建新的下载任务,创建成功则返回Download对象,用于管理下载任务。

参数:

返回值:

Download : 新建的下载任务对象

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 创建下载任务
function createDownload() {
	var dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc", {}, function ( d, status ) {
		// 下载完成
		if ( status == 200 ) { 
			alert( "Download success: " + d.filename );
		} else {
			 alert( "Download failed: " + status ); 
		}  
	});
	//dtask.addEventListener( "statechanged", onStateChanged, false );
	dtask.start(); 
}
	</script>
	</head>
	<body>
	<button id="download" onclick="createDownload()">Create download task</button>
	</body>
</html>
    			

enumerate

枚举下载任务


plus.downloader.enumerate( enumCB, state );
				

说明:

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

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
		plus.downloader.enumerate( function ( tasks ) {
		alert( "Unfinished task count: " + tasks.length );
	} );
}
	</script>
	</head>
	<body>
	Enumerate all unfinished download task.
	</body>
</html>
    			

clear

清除下载任务


plus.downloader.clear( state );
				

说明:

清除指定状态的下载任务。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
	plus.downloader.clear();
}
	</script>
	</head>
	<body>
	Clear all finished download task.
	</body>
</html>
    			

startAll

开始所有下载任务


plus.downloader.startAll();
				

说明:

开始所有处于为开始调度或暂停状态的下载任务。 若下载任务数超过可并发处理的总数,超出的任务处于调度状态(等待下载),当有任务完成时根据调度状态任务的优先级选择任务开始下载。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
	plus.downloader.startAll();
}
	</script>
	</head>
	<body>
	Start download task.
	</body>
</html>
    			

Download

Download对象管理一个下载任务


interface Download {
	readonly attribute String id;
	readonly attribute String url;
	readonly attribute Number state;
	readonly attribute DownloadOptions options;
	readonly attribute String filename;
	readonly attribute Number downloadedSize;
	readonly attribute Number totalSize;
	function void abort();
	function void addEventListener( String event, function Callback listener, Boolean capture );
	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

下载文件的地址


download.url;
						

说明:

String 类型 只读属性

调用plus.donwloader.createDownload()方法创建下载任务时设置的值。

state

任务的状态


download.state;
						

说明:

DownloadState 类型 只读属性

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

options

下载任务的参数


download.options;
						

说明:

DownloadOptions 类型 只读属性

调用plus.donwloader.createDownload()方法创建下载任务时设置的参数。

filename

下载的文件名称


download.filename;
						

说明:

String 类型 只读属性

下载任务在本地保存的文件路径,下载任务完成时更新,可通过此值访问下载的文件。

downloadedSize

已完成下载文件的大小


download.downloadedSize;
						

说明:

Number 类型 只读属性

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

totalSize

下载任务文件的总大小


download.totalSize;
						

说明:

Number 类型 只读属性

整数类型,单位为字节(byte),下载任务开始传输数据时更新,在此之前其值为0。 此值是从HTTP请求头中获取,如果服务器未返回则此值始终为0。

abort

取消下载任务


void download.abort();
						

说明:

如果任务未完成,则终止下载,并从任务列表中删除。 如下载未完成,将删除已下载的临时文件,如果下载已完成,将不删除已下载的文件。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var dtask = null;
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 创建下载任务
function createDownload() {
	dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc", {}, function ( d, status ) {
		// 下载完成
		if ( status == 200 ) { 
			alert( "Download success: " + d.filename );
		} else {
			alert( "Download failed: " + status ); 
		}  
	});
	//dtask.addEventListener( "statechanged", onStateChanged, false );
	dtask.start(); 
}
// 暂停下载任务 
function pauseDownload() {
	dtask.pause();
}
// 取消下载任务 
function abortDownload() {
	dtask.abort();
}
	</script>
  </head>
  <body>
	<button onclick="createDownload()">Create download task</button>
	<button onclick="pauseDownload()">Pause download task</button>
	<button onclick="abortDownload()">Abort download task</button>
  </body>
</html>
						

addEventListener

添加下载任务事件监听器


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

说明:

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

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var dtask = null;
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 监听下载任务状态 
function onStateChanged( download, status ) {
	if ( download.state == 4 && status == 200 ) {
		// 下载完成 
		alert( "Download success: " + download.getFileName() );  
	}  
}
// 创建下载任务
function createDownload() {
	dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc" );
	dtask.addEventListener( "statechanged", onStateChanged, false );
	dtask.start(); 
}
// 暂停下载任务 
function pauseDownload() {
	dtask.pause();
}
// 取消下载任务 
function abortDownload() {
	dtask.abort();
}
	</script>
	</head>
	<body>
	<button onclick="createDownload()">Create download task</button>
	<button onclick="pauseDownload()">Pause download task</button>
	<button onclick="abortDownload()">Abort download task</button>
	</body>
</html>
						

getAllResponseHeaders

获取下载请求HTTP响应头部信息


String download.getAllResponseHeaders();
						

说明:

HTTP响应头部全部内容作为未解析的字符串返回,如果没有接收到这个HTTP响应头数据或者下载请求未完成则为空字符串。

参数:

返回值:

String : HTTP响应头数据

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 创建下载任务
function createDownload() {
	var dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc", {}, function ( d, status ) {
		// 下载完成
		if ( status == 200 ) {
			console.log(dtask.getAllResponseHeaders()); // 获取下载请求响应头数据
			alert( "Download success: " + d.filename );
		} else {
			alert( "Download failed: " + status ); 
		}  
	});
	dtask.start(); 
}
	</script>
	</head>
	<body>
		<button onclick="createDownload();">Create download task</button>
	</body>
</html>
						

getResponseHeader

获取下载请求指定的HTTP响应头部的值


String download.getResponseHeader( headerName );
						

说明:

其参数是要返回的HTTP响应头部的名称,可以使用任何大小写来制定这个头部名字,和响应头部的比较是不区分大小写的。 如果没有接收到这个头部或者下载请求未完成则为空字符串;如果接收到多个有指定名称的头部,这个头部的值被连接起来并返回,使用逗号和空格分隔开各个头部的值。

参数:

返回值:

String : HTTP响应头数据值

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 创建下载任务
function createDownload() {
	var dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc", {}, function ( d, status ) {
		// 下载完成
		if ( status == 200 ) {
			console.log(dtask.getResponseHeader("Content-Type")); // 获取下载请求响应头中的Content-Type值
			alert( "Download success: " + d.filename );
		} else {
			alert( "Download failed: " + status ); 
		}  
	});
	dtask.start(); 
}
	</script>
	</head>
	<body>
		<button onclick="createDownload();">Create download task</button>
	</body>
</html>
						

pause

暂停下载任务


void download.pause();
						

说明:

暂停下载任务,如果任务已经处于初始状态或暂停状态则无任何响应。 通常在任务已开始后暂停任务。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var dtask = null;
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 创建下载任务
function createDownload() {
	dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc", {}, function ( d, status ) {
		// 下载完成
		if ( status == 200 ) { 
			alert( "Download success: " + d.filename );
		} else {
			alert( "Download failed: " + status ); 
		}  
	});
	//dtask.addEventListener( "statechanged", onStateChanged, false );
	dtask.start(); 
}
// 暂停下载任务 
function pauseDownload() {
	dtask.pause();
}
	</script>
	</head>
	<body>
	<button onclick="createDownload()">Create download task</button>
	<button onclick="pauseDownload()">Pause download task</button>
	</body>
</html>
						

resume

恢复暂停的下载任务


void download.resume();
						

说明:

继续暂停的下载任务,如果任务处于非暂停状态则无任何响应。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Downloader Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
var dtask = null;
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
}
// 创建下载任务
function createDownload() {
	dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc", {}, function ( d, status ) {
		// 下载完成
		if ( status == 200 ) {
			alert( "Download success: " + d.filename );
		} else {
			alert( "Download failed: " + status );
		}
	});
	//dtask.addEventListener( "statechanged", onStateChanged, false );
	dtask.start();
}
// 暂停下载任务
function pauseDownload() {
	dtask.pause();
}
// 恢复下载任务
function resumeDownload() {
	dtask.resume();
}
</script>
</head>
<body>
	<button onclick="createDownload()">Create download task</button>
	<button onclick="pauseDownload()">Pause download task</button>
	<button onclick="resumeDownload()">Resume download task</button>
</body>
</html>
						

setRequestHeader

设置下载请求的HTTP头数据


void download.setRequestHeader( headerName, headerValue );
						

说明:

Http的Header应该包含在通过后续start()调用而发起的请求中,此方法必需在调用start()之前设置才能生效。 如果带有指定名称的头部已经被指定了,这个头部的新值就是:之前指定的值,加上逗号、以及这个调用指定的值(形成一个数组)。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 创建下载任务
function createDownload() {
	var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {method:"POST",data:"{name:'test',id:'1234567890'}"}, function(d, status){
		// 下载完成
		if ( status == 200 ) { 
			alert( "Download success: " + d.filename );
		} else {
			alert( "Download failed: " + status ); 
		}  
	});// POST请求提交数据
	dtask.setRequestHeader('Content-Type','application/json');// 设置POST请求提交的数据类型为JSON字符串
	dtask.start(); 
}
	</script>
	</head>
	<body>
		<button onclick="createDownload();">Create download task</button>
	</body>
</html>
						

start

开始下载任务


void download.start();
						

说明:

开始下载任务,如果任务已经处于开始状态则无任何响应。 在创建任务或任务下载失败后调用可重新开始下载。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 创建下载任务
function createDownload() {
	var dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc", {}, function ( d, status ) {
		// 下载完成
		if ( status == 200 ) { 
			alert( "Download success: " + d.filename );
		} else {
			alert( "Download failed: " + status ); 
		}  
	});
	//dtask.addEventListener( "statechanged", onStateChanged, false );
	dtask.start(); 
}
	</script>
	</head>
	<body>
	<button id="download" onclick="createDownload()">Create download task</button>
	</body>
</html>
						

DownloadEvent

下载任务事件类型

常量:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Downloader Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var dtask = null;
// 扩展API加载完毕,现在可以正常调用扩展API 
function onPlusReady() {
}
// 监听下载任务状态 
function onStateChanged( download, status ) {
	if ( download.state == 4 && status == 200 ) {
		// 下载完成 
		alert( "Download success: " + download.getFileName() );  
	}  
}
// 创建下载任务
function createDownload() {
	dtask = plus.downloader.createDownload( "http://www.abc.com/a.doc" );
	dtask.addEventListener( "statechanged", onStateChanged, false );
	dtask.start(); 
}
// 暂停下载任务 
function pauseDownload() {
	dtask.pause();
}
// 取消下载任务 
function abortDownload() {
	dtask.abort();
}
	</script>
	</head>
	<body>
	<button onclick="createDownload()">Create download task</button>
	<button onclick="pauseDownload()">Pause download task</button>
	<button onclick="abortDownload()">Abort download task</button>
	</body>
</html>
				

DownloadState

下载任务状态

常量:

DownloadOptions

下载任务参数

说明:

在创建下载任务时设置的参数,如设置下载任务使用的HTTP协议类型、优先级等。

属性:

DownloadCompletedCallback

下载任务完成时的回调


vaoid onCompleted( Download download, Number status ) {
	// Download file complete code
}
				

说明:

下载任务完成时的回调函数,在下载任务完成时调用。 下载任务失败也将触发此回调。

参数:

返回值:

void : 无

DownloadStateChangedCallback

下载任务状态变化回调


void onStateChanged( Download download, status ) {
	// Download state changed code.
}
				

参数:

返回值:

void : 无

DownloadEnumerateCallback

枚举下载任务回调


void onEnumerated( Download[] downloads ) {
	// Enumerate success code
}
				

参数:

返回值:

void : 无