HTML5+规范：Downloader(管理网络文件下载任务)

时间：2016-07-03 19:15:28 阅读：215 评论：0 收藏：0 [点我收藏+]

标签：

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

1、方法

1.1、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>
<input id="download" type="button" value="Create download task" onclick="createDownload();"></input>
</body>
</html>

1.2、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>

1.3、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>

1.4、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>

2、对象

2.1、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();

}

2.1.1、属性

（1）、id: 下载任务的标识。在创建任务时系统自动分配，用于标识下载任务的唯一性。

（2）、url: 下载文件的地址。调用plus.donwloader.createDownload()方法创建下载任务时设置的值。

（3）、state: 任务的状态。DownloadState 类型只读属性，表示当前下载任务的状态，可通过addEventListener()方法监听statechanged事件监听任务状态的变化。

（4）、options: 下载任务的参数。DownloadOptions 类型只读属性，调用plus.donwloader.createDownload()方法创建下载任务时设置的参数。

（5）、filename: 下载的文件名称。下载任务在本地保存的文件路径，下载任务完成时更新，可通过此值访问下载的文件。

（6）、downloadedSize: 已完成下载文件的大小。整数类型，单位为字节（byte），下载任务开始传输数据时，每次触发statechanged事件或下载任务完成时更新。

（7）、totalSize: 下载任务文件的总大小。整数类型，单位为字节（byte），下载任务开始传输数据时更新，在此之前其值为0。此值是从HTTP请求头中获取，如果服务器未返回则此值始终为0。

2.1.2、方法

（1）、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>
<input type="button" value="Create download task" onclick="createDownload();"></input>
<input type="button" value="Pause download task" onclick="pauseDownload();"></input>
<input type="button" value="Abort download task" onclick="abortDownload();"></input>
  </body>
</html>

（2）、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>
<input type="button" value="Create download task" onclick="createDownload();"></input>
<input type="button" value="Pause download task" onclick="pauseDownload();"></input>
<input type="button" value="Abort download task" onclick="abortDownload();"></input>
</body>
</html>

（3）、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>

（4）、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>

（5）、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>
<input type="button" value="Create download task" onclick="createDownload();"></input>
<input type="button" value="Pause download task" onclick="pauseDownload();"></input>
</body>
</html>

（6）、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>
<input type="button" value="Create download task" onclick="createDownload();"></input>
<input type="button" value="Pause download task" onclick="pauseDownload();"></input>
<input type="button" value="Resume download task" onclick="resumeDownload();"></input>
</body>
</html>

（7）、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", {}, function ( d, status ) {
// 下载完成
if ( status == 200 ) {
alert( "Download success: " + d.filename );
} else {
alert( "Download failed: " + status );
}  
},{method:"POST",data:"{name:'test',id:'1234567890'}"});// POST请求提交数据
dtask.setRequestHeader('Content-Type','application/json');// 设置POST请求提交的数据类型为JSON字符串
dtask.start();
}
</script>
</head>
<body>
<button onclick="createDownload();">Create download task</button>
</body>
</html>

（8）、start: 开始下载任务

2.2、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>
<input type="button" value="Create download task" onclick="createDownload();"></input>
<input type="button" value="Pause download task" onclick="pauseDownload();"></input>
<input type="button" value="Abort download task" onclick="abortDownload();"></input>
</body>
</html>

2.3、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()操作时指定作用于所有下载任务。

2.4、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。

3、回调方法

3.1、DownloadCompletedCallback: 下载任务完成时的回调

vaoid onCompleted( Download download, Number status ) {

// Download file complete code

}

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

参数：

download : ( Download ) 必选下载任务对象

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

返回值：void : 无

3.2、DownloadStateChangedCallback: 下载任务状态变化回调

void onStateChanged( Download download, status ) {

// Download state changed code.

}

参数：

download : ( Download ) 必选下载任务对象

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

返回值：void : 无

3.3、DownloadEnumerateCallback: 枚举下载任务回调

void onEnumerated( Download[] downloads ) {

// Enumerate success code

}

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

返回值：void : 无

HTML5+规范：Downloader(管理网络文件下载任务)

标签：

原文地址：http://blog.csdn.net/qq_27626333/article/details/51815378

踩

(0)

评论一句话评论（0）

分享档案

更多>

2021年07月29日 (22)
2021年07月28日 (40)
2021年07月27日 (32)
2021年07月26日 (79)
2021年07月23日 (29)
2021年07月22日 (30)
2021年07月21日 (42)
2021年07月20日 (16)
2021年07月19日 (90)
2021年07月16日 (35)

周排行