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