# [downloader]()
Downloader模块管理文件下载，用于从网络下载各种文件，可支持跨域访问操作。通过plus.downloader获取下载管理对象。
### 方法：
- [createDownload](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.createDownload): 新建下载任务
- [enumerate](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.enumerate): 枚举应用的所有下载任务
- [clear](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.clear): 清除下载任务
- [startAll](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.startAll): 开始所有下载任务
### 对象：
- [Download](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download): Download对象用于管理单个下载任务
- [DownloadEvent](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadEvent): 下载任务事件类型
- [DownloadState](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadState): 下载任务状态
- [DownloadOption](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadOption): 下载任务的参数
### 回调方法：
- [DownloadCompletedCallback](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadCompletedCallback): 下载任务完成时的回调
- [DownloadStateChangedCallback](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadStateChangedCallback): 下载任务状态变化回调
- [DownloadEnumerateCallback](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadEnumerateCallback): 枚举下载任务回调
### 权限：
permissions
~~~
"Downloader": {
"description": "管理下载任务"
}
~~~
# [createDownload]()
新建下载任务
~~~
Download plus.downloader.createDownload( url, option, completedCB );
~~~
### 说明：
请求下载管理创建新的下载任务，创建成功则返回Download对象，用于管理下载任务的各种状态。
### 参数：
- url: *( DOMString ) 必选 *要下载文件资源地址
要下载文件的url地址，仅支持网络资源地址。必须是http或https协议。
- option: *( [DownloadOption](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadOption) ) 可选 *下载任务的参数
可通过此参数设置自定义任务属性，自定义属性值仅支持字符串类型。
- completedCB: *( [DownloadCompletedCallback](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadCompletedCallback) ) 可选 *下载任务完成后的回调
### 返回值：
[Download](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.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>
~~~
# [enumerate]()
枚举应用的所有下载任务
~~~
plus.downloader.enumerate( enumCB, state );
~~~
### 说明：
枚举指定状态的下载任务列表。 枚举操作完成后通过enumCB回调返回结果。
### 参数：
- enumCB: *( [DownloadEnumerateCallback](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadEnumerateCallback) ) 必选 *枚举操作完成后的回调
- state: *( [DownloadState](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadState) ) 可选 *要枚举下载任务的状态，默认值为所有未完成的下载任务
### 返回值：
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](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadState) ) 必选 *要清除下载任务的状态，默认值为所有已完成的下载任务
### 返回值：
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 DOMString id;
readonly attribute DOMString url;
readonly attribute Number state;
readonly attribute DownloadOption options;
readonly attribute DOMString filename;
function void start();
function void pause();
function void resume();
function void abort();
function void addEventListener( DOMString event, function Callback listener, Boolean capture );
}
~~~
### 属性：
- [id](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.id): 下载任务的标识
- [url](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.url): 下载文件的地址
- [state](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.state): 任务的状态
- [options](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.options): 下载任务的参数
- [filename](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.filename): 下载的文件名称
- [downloadedSize](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.downloadedSize): 已完成下载文件的大小
- [totalSize](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.totalSize): 下载任务文件的总大小
### 方法：
- [start](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.start): 开始下载任务
- [pause](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.pause): 暂停下载任务
- [resume](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.resume): 继续下载任务
- [abort](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.abort): 取消下载任务
- [addEventListener](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download.addEventListener): 添加下载任务事件监听器
# [id]()
下载任务的标识
~~~
download.id;
~~~
### 说明：
DOMString 类型 只读属性
在创建任务时系统自动分配，用于标识下载任务的唯一性。
# [url]()
下载文件的地址
~~~
download.url;
~~~
### 说明：
DOMString 类型 只读属性
下载任务的服务器地址，在创建任务时设置的值。
# [state]()
任务的状态
~~~
download.state;
~~~
### 说明：
[DownloadState](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadState) 类型 只读属性
下载任务的状态，参考DownloadState，在DownloadCompleteCallback事件和DownloadStateChangedCallback事件触发时更新。
# [options]()
下载任务的参数
~~~
download.options;
~~~
### 说明：
[DownloadOption](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadOption) 类型 只读属性
下载任务配置的参数，参考DownloadOption。
# [filename]()
下载的文件名称
~~~
download.filename;
~~~
### 说明：
DOMString 类型 只读属性
下载任务在本地保存的文件路径，在DownloadCompleteCallback事件和DownloadStateChangedCallback事件触发时更新。
# [downloadedSize]()
已完成下载文件的大小
~~~
download.downloadedSize;
~~~
### 说明：
Number 类型 只读属性
下载任务已完成下载文件的大小，单位为字节（byte）。在DownloadCompleteCallback事件和DownloadStateChangedCallback事件触发时更新。
# [totalSize]()
下载任务文件的总大小
~~~
download.downloadedSize;
~~~
### 说明：
Number 类型 只读属性
下载任务要下载文件的总大小，单位为字节（byte）。在DownloadCompleteCallback事件和DownloadStateChangedCallback事件触发时更新。在连接到服务器获取大小之前其值为0。
# [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>
<input id="download" type="button" value="Create download task" onclick="createDownload();"></input>
</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>
<input type="button" value="Create download task" onclick="createDownload();"></input>
<input type="button" value="Pause download task" onclick="pauseDownload();"></input>
</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>
<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>
~~~
# [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.pause();
}
</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>
~~~
# [addEventListener]()
添加下载任务事件监听器
~~~
void download.addEventListener( type, listener, capture );
~~~
### 说明：
下载任务添加事件监听器后，当任务事件发生时触发。
### 参数：
- type: *( [DownloadEvent](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.DownloadEvent) ) 必选 *事件类型
- listener: *( [DownloadStateChangedCallback](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.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.pause();
}
</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>
~~~
# [DownloadEvent]()
下载任务事件类型
### 常量：
- "statechanged": *(DOMString 类型 )*下载任务状态变化事件
当下载任务状态发生变化时触发此事件，事件原型参考DownloadStateChangedCallback。
# [DownloadState]()
下载任务状态
### 常量：
- undefined: *(undefined 类型 )*未开始状态
在创建之后触发此状态事件，下载任务处于可开始状态，需调用下载任务的start方法。
- 0: *(Number 类型 )*初始状态
在调用下载任务start之后触发此状态事件，下载任务处于可调度状态。
- 1: *(Number 类型 )*下载任务开始处理
开始建立网络连接，发送请求到服务器并等待服务器的响应。
- 2: *(Number 类型 )*下载任务请求已经接收
网络连接已建立，服务器返回响应，准备传输数据内容。
- 3: *(Number 类型 )*下载任务请求处理中
传输数据中，在传输过程中不断触发此状态事件。
- 4: *(Number 类型 )*下载任务已完成
下载任务成功或失败都会设置为此状态。
- 5: *(Number 类型 )*下载任务暂停状态
暂停任务时设置任务的状态，此时可重新开始下载任务。
- -1: *(Number 类型 )*非任务状态
不用于表示任务的状态，用于enumerate()和claer()操作所有下载任务。
# [DownloadOption]()
下载任务的参数
### 说明：
在创建下载任务时设置的参数。可添加自定义参数，用于传递额外的数据，自定义参数仅支持字符串类型。
### 属性：
- method: *(DOMString 类型 )*网络请求类型
支持http协议的“GET”、“POST”，默认为“GET”请求。
- filename: *(DOMString 类型 )*下载文件保存的路径
以文件后缀名结尾（如"_doc/download/a.doc"）表明指定保存文件目录及名称，否则认为指定保存文件的目录，若没有指定文件名称则由程序自动生成文件名称。
- priority: *(Number 类型 )*下载任务的优先级
数值类型，数值越大优先级越高，默认优先级值为0。
- timeout: *(Number 类型 )*下载任务超时时间
数值类型，单位为s，默认值为120s。
- retry: *(Number 类型 )*下载任务重试次数
数值类型，默认为重试3次。
# [DownloadCompletedCallback]()
下载任务完成时的回调
~~~
vaoid onCompleted( Download download, Number status ) {
// Download file complete code
}
~~~
### 说明：
下载任务完成时的回调函数，在下载任务完成时调用。 下载任务失败也将触发此回调。
### 参数：
- download : *( [Download](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download) ) 必选 *下载任务对象
- status: *( Number ) 必选 *Http传输协议状态码，如果未获取传输状态则其值则为0，如下载成功其值通常为200
### 返回值：
void : 无
# [DownloadStateChangedCallback]()
下载任务状态变化回调
~~~
void onStateChanged( Download download, status ) {
// Download state changed code.
}
~~~
### 参数：
- download : *( [Download](http://www.dcloud.io/docs/api/zh_cn/downloader.shtml#plus.downloader.Download) ) 必选 *下载任务对象
- status: *( Number ) 必选 *Http传输协议状态码，如果未获取传输状态则其值则为0，如下载成功其值通常为200
### 返回值：
void : 无
# [DownloadEnumerateCallback]()
枚举下载任务回调
~~~
void onEnumerated( Download[] downloads ) {
// Enumerate success code
}
~~~
### 参数：
- downloads : *( Download ) 必选 *枚举到的下载任务对象数组
### 返回值：
void : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS