downloader

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

方法：

createDownload: 新建下载任务
enumerate: 枚举下载任务
clear: 清除下载任务
startAll: 开始所有下载任务

对象：

Download: Download对象管理一个下载任务
DownloadEvent: 下载任务事件类型
DownloadState: 下载任务状态
DownloadOptions: 下载任务参数

回调方法：

DownloadCompletedCallback: 下载任务完成时的回调
DownloadStateChangedCallback: 下载任务状态变化回调
DownloadEnumerateCallback: 枚举下载任务回调

模块：

5+功能模块（permissions）


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

createDownload

新建下载任务


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

说明：

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

参数：

url: ( String ) 必选 要下载文件资源地址
要下载文件的url地址，仅支持网络资源地址，支持http或https协议。允许创建多个相同url地址的下载任务。
options: ( DownloadOptions ) 可选 下载任务的参数
可通过此参数设置下载任务属性，如保存文件路径、下载优先级等。
completedCB: ( DownloadCompletedCallback ) 可选 下载任务完成回调函数
当下载任务下载完成时触发，成功或失败都会触发。

返回值：

Download : 新建的下载任务对象

平台支持：

Android - 2.2+ (支持)
iOS - 4.3+ (支持)

示例：


<!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回调函数返回结果。

参数：

enumCB: ( DownloadEnumerateCallback ) 必选 枚举下载任务回调函数
枚举下载任务完成时触发。
state: ( DownloadState ) 可选 枚举下载任务的状态
如果未指定state值，则枚举所有未完成的下载任务。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 4.3+ (支持)

示例：


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

说明：

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

参数：

state: ( DownloadState ) 可选 清除下载任务的状态
如果未指定state值，则清除所有未完成的下载任务。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 4.3+ (支持)

示例：


<!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: 下载任务的标识
url: 下载文件的地址
state: 任务的状态
options: 下载任务的参数
filename: 下载的文件名称
downloadedSize: 已完成下载文件的大小
totalSize: 下载任务文件的总大小

方法：

abort: 取消下载任务
addEventListener: 添加下载任务事件监听器
getAllResponseHeaders: 获取下载请求HTTP响应头部信息
getResponseHeader: 获取下载请求指定的HTTP响应头部的值
pause: 暂停下载任务
resume: 恢复暂停的下载任务
setRequestHeader: 设置下载请求的HTTP头数据
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回调。

参数：

type: ( DownloadEvent ) 必选 事件类型
listener: ( DownloadStateChangedCallback ) 可选 事件监听器回调
当监听的事件发生时，触发设置的回调函数。
capture: ( Boolean ) 可选 事件流处理顺序，暂不支持

返回值：

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响应头部的名称，可以使用任何大小写来制定这个头部名字，和响应头部的比较是不区分大小写的。如果没有接收到这个头部或者下载请求未完成则为空字符串；如果接收到多个有指定名称的头部，这个头部的值被连接起来并返回，使用逗号和空格分隔开各个头部的值。

参数：

headerName: ( String ) 可选 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()之前设置才能生效。如果带有指定名称的头部已经被指定了，这个头部的新值就是：之前指定的值，加上逗号、以及这个调用指定的值（形成一个数组）。

参数：

headerName: ( String ) 必选 HTTP请求的头数据名称
headerValue: ( String ) 必选 HTTP请求的头数据值

返回值：

void : 无

平台支持：

Android - 2.2+ (支持): 不支持设置“User-Agent”、“Cookie”的值。
iOS - 5.1+ (支持): 不支持设置“User-Agent”的值。

示例：


<!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 : 无

平台支持：

Android - 2.2+ (支持)
iOS - 4.3+ (支持)

示例：


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

下载任务事件类型

常量：

"statechanged": (String 类型 )下载任务状态变化事件
当下载任务状态发生变化时触发此事件，事件原型参考DownloadStateChangedCallback。

示例：


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

下载任务状态

常量：

undefined: (undefined 类型 )下载任务未开始
通过plus.downloader.createDownload()方法创建下载任务后的初始状态，此时可调用其start()方法开始下载。
0: (Number 类型 )下载任务开始调度
调用下载任务的start()方法之后处于此状态，此时下载任务处于可调度下载状态。
1: (Number 类型 )下载任务开始请求
下载任务建立网络连接，发送请求到服务器并等待服务器的响应。
2: (Number 类型 )下载任务请求已经接收
下载任务网络连接已建立，服务器返回响应，准备传输数据内容。
3: (Number 类型 )下载任务接收数据
下载任务接收数据，监听statechanged事件时可多次触发此状态。
4: (Number 类型 )下载任务已完成
下载任务完成数据传输并断开连接，下载成功或失败都会设置为此状态。
5: (Number 类型 )下载任务已暂停
调用下载任务的pause()方法将任务暂停，此时可调用其resume()方法重新开始下载。
-1: (Number 类型 )枚举任务状态
非下载任务状态，泛指所有下载任务的状态，用于enumerate()和clear()操作时指定作用于所有下载任务。

DownloadOptions

下载任务参数

说明：

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

属性：

method: (String 类型 )网络请求类型
支持http协议的“GET”、“POST”，默认为“GET”请求。
data: (String 类型 )POST请求时提交的数据
仅在网络请求类型method设置为"POST"时有效，"GET"请求时忽略此数据。
filename: (String 类型 )下载文件保存的路径
保存文件路径仅支持以"_downloads/"、"_doc/"、"_documents/"开头的字符串。文件路径以文件后缀名结尾（如"_doc/download/a.doc"）表明指定保存文件目录及名称，以“/”结尾则认为指定保存文件的目录（此时程序自动生成文件名）。如果指定的文件已经存在，则自动在文件名后面加"(i)"，其中i为数字，如果文件名称后面已经是此格式，则数字i递增，如"download(1).doc"。默认保存目录为（"_downloads"），并自动生成文件名称。
priority: (Number 类型 )下载任务的优先级
数值类型，数值越大优先级越高，默认优先级值为0。
timeout: (Number 类型 )下载任务超时时间
数值类型，单位为s(秒)，默认值为120s。超时时间为服务器响应请求的时间（不是下载任务完成的总时间），如果设置为0则表示永远不超时。
retry: (Number 类型 )下载任务重试次数
数值类型，默认为重试3次。
retryInterval: (Number 类型 )下载任务重试间隔时间
数值类型，单位为s(秒)，默认值为30s。

DownloadCompletedCallback

下载任务完成时的回调


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

说明：

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

参数：

download : ( Download ) 必选 下载任务对象
status: ( Number ) 必选 下载结果状态码
HTTP传输协议状态码，如果未获取传输状态则其值则为0，如下载成功其值通常为200。

返回值：

void : 无

DownloadStateChangedCallback

下载任务状态变化回调


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

参数：

download : ( Download ) 必选 下载任务对象
status: ( Number ) 必选 下载结果状态码
HTTP传输协议状态码，如果未获取传输状态则其值则为0，如下载成功其值通常为200。

返回值：

void : 无

DownloadEnumerateCallback

枚举下载任务回调


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

参数：

downloads: ( Array[ Download ] ) 必选 枚举到的下载任务对象数组

返回值：

void : 无

Downloader

API Reference

Plugins

Native.js

方法：

对象：

回调方法：

模块：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

示例：

属性：

方法：

说明：

说明：

说明：

说明：

说明：

说明：

说明：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

平台支持：

示例：

常量：

示例：

常量：

说明：

属性：

说明：

参数：

返回值：

参数：

返回值：