downloader

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

方法：

对象：

回调方法：

权限：

5+功能模块（permissions）

  2. {
  3. // ...
  4. "permissions":{
  5.     // ...
  6.     "Downloader": {
  7.         "description": "文件下载，管理文件下载任务"
  8.     }
  9. }
  10. }
  11.

createDownload

新建下载任务

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

说明：

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

参数：

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

返回值：

Download: 新建的下载任务对象

示例：

  2. // 创建下载任务
  3. function createDownload() {
  4.     var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
  5.         // 下载完成
  6.         if(status == 200){ 
  7.             console.log("Download success: " + d.filename);
  8.         } else {
  9.              console.log("Download failed: " + status); 
  10.         }  
  11.     });
  12.     //dtask.addEventListener("statechanged", onStateChanged, false);
  13.     dtask.start(); 
  14. }
  15.

uni-app使用plus注意事项

enumerate

枚举下载任务

  2. plus.downloader.enumerate( enumCB, state );
  3.

说明：

枚举指定状态的下载任务列表，通过enumCB回调函数返回结果。

参数：

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

返回值：

void: 无

示例：

  2. // 枚举下载任务 
  3. function enumerateDwonload() {
  4.     plus.downloader.enumerate(function(tasks){
  5.         console.log("Unfinished task count: " + tasks.length);
  6.     });
  7. }
  8.

uni-app使用plus注意事项

clear

清除下载任务

  2. plus.downloader.clear(state);
  3.

说明：

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

参数：

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

返回值：

void: 无

示例：

  2. // 清除下载任务 
  3. function onPlusReady() {
  4.     plus.downloader.clear();
  5. }
  6.

uni-app使用plus注意事项

startAll

开始所有下载任务

  2. plus.downloader.startAll();
  3.

说明：

开始所有处于为开始调度或暂停状态的下载任务。若下载任务数超过可并发处理的总数，超出的任务处于调度状态（等待下载），当有任务完成时根据调度状态任务的优先级选择任务开始下载。

参数：

返回值：

void: 无

示例：

  2. // 开始所有下载任务
  3. function onPlusReady() {
  4.     plus.downloader.startAll();
  5. }
  6.

uni-app使用plus注意事项

Download

Download对象管理一个下载任务

  2. interface plus.downloader.Download {
  3.     readonly attribute String id;
  4.     readonly attribute String url;
  5.     readonly attribute Number state;
  6.     readonly attribute DownloadOptions options;
  7.     readonly attribute String filename;
  8.     readonly attribute Number downloadedSize;
  9.     readonly attribute Number totalSize;
  10.     function void abort();
  11.     function void addEventListener(String event, function Callback listener, Boolean capture);
  12.     function String getAllResponseHeaders();
  13.     function String getResponseHeader(String headerName);
  14.     function void pause();
  15.     function void resume();
  16.     function void setRequestHeader(String headerName, String headerValue);
  17.     function void start();
  18. }
  19.

属性：

方法：

id

下载任务的标识

  2. download.id;
  3.

说明：

String类型 只读属性

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

url

下载文件的地址

  2. download.url;
  3.

说明：

String类型 只读属性

调用plus.donwloader.createDownload()方法创建下载任务时设置的值。

state

任务的状态

  2. download.state;
  3.

说明：

DownloadState类型 只读属性

表示当前下载任务的状态，可通过addEventListener()方法监听statechanged事件监听任务状态的变化。

options

下载任务的参数

  2. download.options;
  3.

说明：

DownloadOptions类型 只读属性

调用plus.donwloader.createDownload()方法创建下载任务时设置的参数。

filename

下载的文件名称

  2. download.filename;
  3.

说明：

String类型 只读属性

下载任务在本地保存的文件路径，下载任务完成时更新，可通过此值访问下载的文件。

downloadedSize

已完成下载文件的大小

  2. download.downloadedSize;
  3.

说明：

Number类型 只读属性

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

totalSize

下载任务文件的总大小

  2. download.totalSize;
  3.

说明：

Number类型 只读属性

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

abort

取消下载任务

  2. void download.abort();
  3.

说明：

如果任务未完成，则终止下载，并从任务列表中删除。如下载未完成，将删除已下载的临时文件，如果下载已完成，将不删除已下载的文件。

参数：

返回值：

void: 无

示例：

  2. var dtask = null;
  3. // 创建下载任务
  4. function createDownload() {
  5.     dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
  6.         // 下载完成
  7.         if(status == 200){ 
  8.             console.log("Download success: " + d.filename);
  9.         }else{
  10.             console.log("Download failed: " + status); 
  11.         }  
  12.     });
  13.     //dtask.addEventListener("statechanged", onStateChanged, false);
  14.     dtask.start(); 
  15. }
  16. // 暂停下载任务 
  17. function pauseDownload() {
  18.     dtask.pause();
  19. }
  20. // 取消下载任务 
  21. function abortDownload() {
  22.     dtask.abort();
  23. }
  24.

uni-app使用plus注意事项

addEventListener

添加下载任务事件监听器

  2. void download.addEventListener(type, listener, capture);
  3.

说明：

下载任务添加事件监听器后，当监听的事件发生时触发listener回调。

参数：

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

返回值：

void: 无

示例：

  2. var dtask = null;
  3. // 监听下载任务状态 
  4. function onStateChanged(download, status) {
  5.     if(download.state == 4 && status == 200){
  6.         // 下载完成 
  7.         console.log("Download success: " + download.getFileName());  
  8.     }  
  9. }
  10. // 创建下载任务
  11. function createDownload() {
  12.     dtask = plus.downloader.createDownload("http://www.abc.com/a.doc");
  13.     dtask.addEventListener("statechanged", onStateChanged, false);
  14.     dtask.start(); 
  15. }
  16. // 暂停下载任务 
  17. function pauseDownload() {
  18.     dtask.pause();
  19. }
  20. // 取消下载任务 
  21. function abortDownload() {
  22.     dtask.abort();
  23. }
  24.

uni-app使用plus注意事项

getAllResponseHeaders

获取下载请求HTTP响应头部信息

  2. String download.getAllResponseHeaders();
  3.

说明：

HTTP响应头部全部内容作为未解析的字符串返回，如果没有接收到这个HTTP响应头数据或者下载请求未完成则为空字符串。

参数：

无

返回值：

String: HTTP响应头数据

示例：

  2. var dtask = null;
  3. // 创建下载任务
  4. function createDownload() {
  5.     var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
  6.         // 下载完成
  7.         if(status == 200){
  8.             console.log(dtask.getAllResponseHeaders()); // 获取下载请求响应头数据
  9.             console.log("Download success: " + d.filename);
  10.         }else{
  11.             console.log("Download failed: " + status); 
  12.         }  
  13.     });
  14.     dtask.start(); 
  15. }
  16.

uni-app使用plus注意事项

getResponseHeader

获取下载请求指定的HTTP响应头部的值

  2. String download.getResponseHeader(String headerName);
  3.

说明：

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

参数：

  • headerName: _(String)可选 _HTTP响应头数据名称

返回值：

String: HTTP响应头数据值

示例：

  2. var dtask = null;
  3. // 创建下载任务
  4. function createDownload() {
  5.     var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
  6.         // 下载完成
  7.         if ( status == 200 ) {
  8.             console.log(dtask.getResponseHeader("Content-Type"));
  9.         } else {
  10.             console.log("Download failed: " + status); 
  11.         }  
  12.     });
  13.     dtask.start(); 
  14. }
  15.

uni-app使用plus注意事项

pause

暂停下载任务

  2. void download.pause();
  3.

说明：

暂停下载任务，如果任务已经处于初始状态或暂停状态则无任何响应。通常在任务已开始后暂停任务。

参数：

返回值：

void: 无

示例：

  2. var dtask = null;
  3. // 创建下载任务
  4. function createDownload() {
  5.     dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
  6.         // 下载完成
  7.         if(status == 200){ 
  8.             console.log("Download success: " + d.filename);
  9.         } else {
  10.             console.log("Download failed: " + status); 
  11.         }  
  12.     });
  13.     //dtask.addEventListener("statechanged", onStateChanged, false);
  14.     dtask.start(); 
  15. }
  16. // 暂停下载任务 
  17. function pauseDownload() {
  18.     dtask.pause();
  19. }
  20.

uni-app使用plus注意事项

resume

恢复暂停的下载任务

  2. void download.resume();
  3.

说明：

继续暂停的下载任务，如果任务处于非暂停状态则无任何响应。

参数：

返回值：

void: 无

示例：

  2. var dtask = null;
  3. // 创建下载任务
  4. function createDownload() {
  5.     dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
  6.         // 下载完成
  7.         if(status == 200){
  8.             console.log("Download success: " + d.filename);
  9.         }else{
  10.             console.log("Download failed: " + status);
  11.         }
  12.     });
  13.     //dtask.addEventListener("statechanged", onStateChanged, false);
  14.     dtask.start();
  15. }
  16. // 暂停下载任务
  17. function pauseDownload() {
  18.     dtask.pause();
  19. }
  20. // 恢复下载任务
  21. function resumeDownload() {
  22.     dtask.resume();
  23. }
  24.

uni-app使用plus注意事项

setRequestHeader

设置下载请求的HTTP头数据

  2. void download.setRequestHeader( headerName, headerValue );
  3.

说明：

Http的Header应该包含在通过后续start()调用而发起的请求中，此方法必需在调用start()之前设置才能生效。如果带有指定名称的头部已经被指定了，这个头部的新值就是：之前指定的值，加上逗号、以及这个调用指定的值（形成一个数组）。

参数：

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

返回值：

void: 无

平台支持：

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

示例：

  2. var dtask = null;
  3. // 创建下载任务
  4. function createDownload() {
  5.     var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {method:"POST",data:"{name:'test',id:'1234567890'}"}, function(d, status){
  6.         // 下载完成
  7.         if(status == 200){ 
  8.             console.log("Download success: " + d.filename);
  9.         }else{
  10.             console.log("Download failed: " + status); 
  11.         }  
  12.     });// POST请求提交数据
  13.     dtask.setRequestHeader('Content-Type','application/json');// 设置POST请求提交的数据类型为JSON字符串
  14.     dtask.start(); 
  15. }
  16.

uni-app使用plus注意事项

start

开始下载任务

  2. void download.start();
  3.

说明：

开始下载任务，如果任务已经处于开始状态则无任何响应。在创建任务或任务下载失败后调用可重新开始下载。

参数：

无

返回值：

void: 无

示例：

  2. var dtask = null;
  3. // 创建下载任务
  4. function createDownload() {
  5.     var dtask = plus.downloader.createDownload("http://www.abc.com/a.doc", {}, function(d, status){
  6.         // 下载完成
  7.         if(status == 200){ 
  8.             console.log("Download success: " + d.filename);
  9.         }else{
  10.             console.log("Download failed: " + status); 
  11.         }  
  12.     });
  13.     //dtask.addEventListener("statechanged", onStateChanged, false);
  14.     dtask.start(); 
  15. }
  16.

uni-app使用plus注意事项

DownloadEvent

下载任务事件类型

常量：

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

示例：

  2. var dtask = null;
  3. // 扩展API加载完毕，现在可以正常调用扩展API 
  4. function onPlusReady() {
  5. }
  6. // 监听下载任务状态 
  7. function onStateChanged(download, status) {
  8.     if(download.state == 4 && status == 200){
  9.         // 下载完成 
  10.         console.log("Download success: " + download.getFileName());  
  11.     }  
  12. }
  13. // 创建下载任务
  14. function createDownload() {
  15.     dtask = plus.downloader.createDownload("http://www.abc.com/a.doc");
  16.     dtask.addEventListener("statechanged", onStateChanged, false);
  17.     dtask.start(); 
  18. }
  19. // 暂停下载任务 
  20. function pauseDownload() {
  21.     dtask.pause();
  22. }
  23. // 取消下载任务 
  24. function abortDownload() {
  25.     dtask.abort();
  26. }
  27.

uni-app使用plus注意事项

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

下载任务参数

  2. interface plus.downloader.DownloadOptions {
  3.     readonly attribute String method;
  4.     readonly attribute String data;
  5.     readonly attribute String filename;
  6.     readonly attribute Number priority;
  7.     readonly attribute Number timeout;
  8.     readonly attribute Number retry;
  9.     readonly attribute Number retryInterval;
  10. }
  11.

说明：

在创建下载任务时设置的参数，如设置下载任务使用的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

下载任务完成时的回调

  2. vaoid onCompleted(Download download, Number status) {
  3.     // Download file complete code
  4. }
  5.

说明：

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

参数：

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

返回值：

void: 无

DownloadStateChangedCallback

下载任务状态变化回调

  2. void onStateChanged( Download download, status ) {
  3.     // Download state changed code.
  4. }
  5.

参数：

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

返回值：

void: 无

DownloadEnumerateCallback

枚举下载任务回调

  2. void onEnumerated( Download[] downloads ) {
  3.     // Enumerate success code
  4. }
  5.

参数：

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

返回值：

void: 无