# [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