返回介绍

downloader

发布于 2021-10-21 18:08:11 字数 21469 浏览 931 评论 0 收藏 0

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

方法:

对象:

回调方法:

权限:

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(); 
}
    			

uni-app使用plus注意事项

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);
	});
}
    			

uni-app使用plus注意事项

clear

清除下载任务


plus.downloader.clear(state);
				

说明:

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

参数:

  • state: ( DownloadState ) 可选 清除下载任务的状态

    如果未指定state值,则清除所有未完成的下载任务。

返回值:

void : 无

示例:


// 清除下载任务 
function onPlusReady() {
	plus.downloader.clear();
}
    			

uni-app使用plus注意事项

startAll

开始所有下载任务


plus.downloader.startAll();
				

说明:

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

参数:

    返回值:

    void : 无

    示例:

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

    uni-app使用plus注意事项

    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

    下载任务的标识

    
    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();
      }
      						

      uni-app使用plus注意事项

      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();
      }
      						

      uni-app使用plus注意事项

      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(); 
      }
      						

      uni-app使用plus注意事项

      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(); 
      }
      						

      uni-app使用plus注意事项

      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();
        }
        						

        uni-app使用plus注意事项

        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();
          }
          						

          uni-app使用plus注意事项

          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(); 
          }
          						

          uni-app使用plus注意事项

          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(); 
          }
          						

          uni-app使用plus注意事项

          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();
          }
          				

          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

          下载任务参数

          
          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] ) 必选 枚举到的下载任务对象数组

          返回值:

          void : 无

          如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

          扫码二维码加入Web技术交流群

          发布评论

          需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

          列表为空,暂无数据
            我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击“接受”或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。