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地址的下载任务。 注意:如果url地址中包含中文或空格等,需要进行urlencode转换。
- options:
(
DownloadOptions
)
可选 下载任务的参数
可通过此参数设置下载任务属性,如保存文件路径、下载优先级等。
- completedCB:
(
DownloadCompletedCallback
)
可选 下载任务完成回调函数
当下载任务下载完成时触发,成功或失败都会触发。
返回值:
Download : 新建的下载任务对象示例:
// 创建下载任务
function createDownload() {
var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
// 下载完成
if(status == 200){
console.log("Download success: " + d.filename);
} else {
console.log("Download failed: " + status);
}
});
//dtask.addEventListener("statechanged", onStateChanged, false);
dtask.start();
}
enumerate
枚举下载任务
plus.downloader.enumerate( enumCB, state );
说明:
枚举指定状态的下载任务列表,通过enumCB回调函数返回结果。
参数:
- enumCB:
(
DownloadEnumerateCallback
)
必选 枚举下载任务回调函数
枚举下载任务完成时触发。
- state:
(
DownloadState
)
可选 枚举下载任务的状态
如果未指定state值,则枚举所有未完成的下载任务。
返回值:
void : 无示例:
// 枚举下载任务
function enumerateDwonload() {
plus.downloader.enumerate(function(tasks){
console.log("Unfinished task count: " + tasks.length);
});
}
clear
清除下载任务
plus.downloader.clear(state);
说明:
清除指定状态的下载任务。
参数:
- state:
(
DownloadState
)
可选 清除下载任务的状态
如果未指定state值,则清除所有未完成的下载任务。
返回值:
void : 无示例:
// 清除下载任务
function onPlusReady() {
plus.downloader.clear();
}
startAll
开始所有下载任务
plus.downloader.startAll();
说明:
开始所有处于为开始调度或暂停状态的下载任务。 若下载任务数超过可并发处理的总数,超出的任务处于调度状态(等待下载),当有任务完成时根据调度状态任务的优先级选择任务开始下载。
参数:
返回值:
void : 无示例:
// 开始所有下载任务
function onPlusReady() {
plus.downloader.startAll();
}
Download
Download对象管理一个下载任务
interface plus.downloader.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(String 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协议的Content-Length中获取,如果服务器未返回Content-Length数据则此值始终为0。
abort
取消下载任务
void download.abort();
说明:
如果任务未完成,则终止下载,并从任务列表中删除。 如下载未完成,将删除已下载的临时文件,如果下载已完成,将不删除已下载的文件。
参数:
返回值:
void : 无示例:
var dtask = null;
// 创建下载任务
function createDownload() {
dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
// 下载完成
if(status == 200){
console.log("Download success: " + d.filename);
}else{
console.log("Download failed: " + status);
}
});
//dtask.addEventListener("statechanged", onStateChanged, false);
dtask.start();
}
// 暂停下载任务
function pauseDownload() {
dtask.pause();
}
// 取消下载任务
function abortDownload() {
dtask.abort();
}
addEventListener
添加下载任务事件监听器
void download.addEventListener(type, listener, capture);
说明:
下载任务添加事件监听器后,当监听的事件发生时触发listener回调。
参数:
- type:
(
DownloadEvent
)
必选 事件类型
- listener:
(
DownloadStateChangedCallback
)
可选 事件监听器回调
当监听的事件发生时,触发设置的回调函数。
- capture:
(
Boolean
)
可选 事件流处理顺序,暂不支持
返回值:
void : 无示例:
var dtask = null;
// 监听下载任务状态
function onStateChanged(download, status) {
if(download.state == 4 && status == 200){
// 下载完成
console.log("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();
}
getAllResponseHeaders
获取下载请求HTTP响应头部信息
String download.getAllResponseHeaders();
说明:
HTTP响应头部全部内容作为未解析的字符串返回,如果没有接收到这个HTTP响应头数据或者下载请求未完成则为空字符串。
参数:
无
返回值:
String : HTTP响应头数据示例:
var dtask = null;
// 创建下载任务
function createDownload() {
var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
// 下载完成
if(status == 200){
console.log(dtask.getAllResponseHeaders()); // 获取下载请求响应头数据
console.log("Download success: " + d.filename);
}else{
console.log("Download failed: " + status);
}
});
dtask.start();
}
getResponseHeader
获取下载请求指定的HTTP响应头部的值
String download.getResponseHeader(String headerName);
说明:
其参数是要返回的HTTP响应头部的名称,可以使用任何大小写来制定这个头部名字,和响应头部的比较是不区分大小写的。 如果没有接收到这个头部或者下载请求未完成则为空字符串;如果接收到多个有指定名称的头部,这个头部的值被连接起来并返回,使用逗号和空格分隔开各个头部的值。
参数:
- headerName:
(
String
)
可选 HTTP响应头数据名称
返回值:
String : HTTP响应头数据值示例:
var dtask = null;
// 创建下载任务
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"));
} else {
console.log("Download failed: " + status);
}
});
dtask.start();
}
pause
暂停下载任务
void download.pause();
说明:
暂停下载任务,如果任务已经处于初始状态或暂停状态则无任何响应。 通常在任务已开始后暂停任务。
参数:
返回值:
void : 无示例:
var dtask = null;
// 创建下载任务
function createDownload() {
dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
// 下载完成
if(status == 200){
console.log("Download success: " + d.filename);
} else {
console.log("Download failed: " + status);
}
});
//dtask.addEventListener("statechanged", onStateChanged, false);
dtask.start();
}
// 暂停下载任务
function pauseDownload() {
dtask.pause();
}
resume
恢复暂停的下载任务
void download.resume();
说明:
继续暂停的下载任务,如果任务处于非暂停状态则无任何响应。
参数:
返回值:
void : 无示例:
var dtask = null;
// 创建下载任务
function createDownload() {
dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
// 下载完成
if(status == 200){
console.log("Download success: " + d.filename);
}else{
console.log("Download failed: " + status);
}
});
//dtask.addEventListener("statechanged", onStateChanged, false);
dtask.start();
}
// 暂停下载任务
function pauseDownload() {
dtask.pause();
}
// 恢复下载任务
function resumeDownload() {
dtask.resume();
}
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”的值。
示例:
var dtask = null;
// 创建下载任务
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){
console.log("Download success: " + d.filename);
}else{
console.log("Download failed: " + status);
}
});// POST请求提交数据
dtask.setRequestHeader('Content-Type','application/json');// 设置POST请求提交的数据类型为JSON字符串
dtask.start();
}
start
开始下载任务
void download.start();
说明:
开始下载任务,如果任务已经处于开始状态则无任何响应。 在创建任务或任务下载失败后调用可重新开始下载。
参数:
无
返回值:
void : 无示例:
var dtask = null;
// 创建下载任务
function createDownload() {
var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
// 下载完成
if(status == 200){
console.log("Download success: " + d.filename);
}else{
console.log("Download failed: " + status);
}
});
//dtask.addEventListener("statechanged", onStateChanged, false);
dtask.start();
}
DownloadEvent
下载任务事件类型
常量:
- "statechanged": (String
类型
)下载任务状态变化事件
当下载任务状态发生变化时触发此事件,事件原型参考DownloadStateChangedCallback。
示例:
var dtask = null;
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
}
// 监听下载任务状态
function onStateChanged(download, status) {
if(download.state == 4 && status == 200){
// 下载完成
console.log("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();
}
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
下载任务参数
interface plus.downloader.DownloadOptions {
readonly attribute String method;
readonly attribute String data;
readonly attribute String filename;
readonly attribute Number priority;
readonly attribute Number timeout;
readonly attribute Number retry;
readonly attribute Number retryInterval;
}
说明:
在创建下载任务时设置的参数,如设置下载任务使用的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]
)
必选 枚举到的下载任务对象数组