downloader


简介:

Downloader模块管理文件下载,用于从网络下载各种文件,支持跨域访问操作、支持断点续传、支持并发。通过rd.downloader获取下载管理对象。

下载任务状态(Number):

  • rd.downloader.Ready:值为0,初始化

  • rd.downloader.Downloading:值为1,下载任务进行中

  • rd.downloader.Paused:值为2,下载任务暂停

  • rd.downloader.Aborted:值为3,下载任务取消

  • rd.downloader.Finished:值为4,下载任务已完成

  • rd.downloader.Error:值为5,下载任务出现错误

全部任务标示(Number):

  • rd.downloader.All:值为-1,表示全部下载任务状态

方法:

  • setMaxRunningSize :设置并发任务最大数(仅Android支持)
  • setSpeed :设置总下载速度(KB/S),每秒多少KB,仅支持Android平台
  • createDownload : 新建下载任务
  • enumerate : 枚举指定任务状态的下载任务
  • enumerateById : 枚举指定任务Id的下载任务
  • clear : 清除指定任务状态的下载任务
  • startAll : 开始所有下载任务
  • remove :清除单个任务

对象:

回调方法:

setMaxRunningSize


设置并发任务最大数(仅Android支持)

rd.downloader.setMaxRunningSize(num);
说明:
  • 设置下载并发任务最大数,需注意并发数越大越浪费资源
  • 如开启的任务数量大于并发数,则会进入等待队列;后续当正在下载中的任务数小于并发数时,会自动从等待队列队首取任务并开始下载
  • (iOS不支持)

    参数:
  • num: ( Number ) 必选 默认为5 任务并发数

返回值:
示例:
rd.downloader.setMaxRunningSize(7);

setSpeed


设置总下载速度

rd.downloader.setSpeed(speed);
说明:

设置总下载速度(iOS不支持)。

参数:
  • speed: (Number) 必选 下载速度(KB/S),speed<=0不限速。
返回值:

示例:
rd.downloader.setSpeed(100);//设置下载速度会100KB/S

createDownload


新建下载任务

DownloadTask rd.downloader.createDownload(url, option);
说明:
  • 创建下载任务,创建成功则返回Download对象。
  • 在任务结束后,要及时清除任务,以免内存溢出。
  • 重复创建任务,返回原任务 :
    在新建task时,如果其参数中的url和DownloadOption中的filePath和已存在的task相同,则返回原来已生成的task。
参数:
  • url: ( String ) 必选 要下载文件资源地址

    要下载文件的url地址,仅支持网络资源地址,必须是http或https协议。

  • option: ( DownloadOption ) 必选 下载任务的参数

    可通过此参数设置任务属性。

返回值:

Download : 新建的下载任务对象

示例:
var option = {method:'GET',timeout:60,retry:3,filePath:'data://download/a.pdf'};
var dtask = rd.downloader.createDownload('https://developer.apple.com/start.pdf',option);

enumerate


枚举指定任务状态的下载任务

var downloadTask = rd.downloader.enumerate(state);
说明:

枚举指定状态的下载任务。

参数:
  • state:某种下载任务状态或者全部下载任务 必选 要枚举下载任务的状态。
返回值:
  • downloads:(Array) 枚举到的下载任务对象数组。
示例:
var downloadTask = rd.downloader.enumerate(rd.downloader.Downloading);

enumerateById


清除单个下载任务

var downloadTask = rd.downloader.enumerateById(id);
说明:

通过id获取任务,如果当任务下载时,程序出现异常(断网、进程被杀),再次下载时可通过此方法枚举出以前未下载完的任务执行start继续下载,这样可节约系统资源。

参数:
  • id: ( Number ) 必选 要获取下载任务的id。
返回值:
示例:
var downloadTask = rd.downloader.enumerateById(1);

clear


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

rd.downloader.clear(state);
说明:

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

参数:
返回值:

无返回值

示例:
rd.downloader.clear(0);

startAll


开始所有下载任务

rd.downloader.startAll();
说明:

开始所有下载任务。

参数:

返回值:

无返回值

示例:
rd.downloader.startAll();               

remove


清除单个下载任务

rd.downloader.remove( id );
说明:

清除指定id的下载任务。

参数:
  • id: ( Number ) 必选 要清除下载任务的id。
返回值:

无返回值

示例:
rd.downloader.remove(1);

Download


Download对象用于管理单个下载任务

Download {
    readonly property String id,
    readonly property String url,
    readonly property String filePath,
    readonly property Number state,
    readonly property DownloadOption option,
    readonly property Number downloadedSize,
    readonly property Number totalSize,
    function void start(),
    function void pause(),
    function void resume(),
    function void abort(),
    function void addEventListener(DownloadStateChangedCallback listener),
    function void removeEventListener(),
    function void addCompletedListener:(DownloadStateChangedCallback listener),
    function void removeCompletedListener()
}
属性:
  • id: 下载任务的标识 (Number) 只读属性

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

  • url:下载文件的地址 (String) 只读属性

    下载任务的服务器地址,在创建任务时设置的值。

  • filePath: 下载文件保存的真实路径 (String) 只读属性

  • state: 任务的状态 (下载任务状态) 只读属性

    下载任务的状态。

  • option: 下载任务的参数 (DownloadOption) 只读属性

    下载任务配置的参数,参考DownloadOption。

  • downloadedSize: 已完成下载文件的大小 (Number) 只读属性 默认大小0

    下载任务已完成下载文件的大小,单位为字节(Byte)。

  • totalSize: 下载任务文件的总大小 (Number) 只读属性 默认大小0

    下载任务要下载文件的总大小,单位为字节(Byte)。

方法:

下载状态说明:

start


开始下载任务

void download.start();
说明:
  • 开始下载任务,如果任务已经处于开始状态则无任何响应。
  • 通常在创建任务或暂停任务后重新开始。如果是重复创建的任务,且任务保存路径中的文件存在,就直接回调完成监听,不再重新下载。
  • 正在下载中的任务数大于设置的并发数,则会等待下载
参数:

返回值:

无返回值

示例:
var option = {method:'GET',timeout:5,retry:3,filePath:'data://download/a.pdf'};

var dtask = rd.downloader.createDownload('https://developer.apple.com/library/ios/documentation/DataManagement/Conceptual/    CloudKitQuickStart/CloudKit_Quick_Start.pdf',option);

dtask.start(); 

pause


暂停下载任务

void download.pause();
说明:

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

参数:

返回值:

无返回值

示例:
dtask.pause();

resume


继续下载任务

void download.resume();
说明:

继续停止的下载任务,如果任务已经处于下载状态则无任何响应。 通常在任务已暂停任务后继续下载任务。

参数:

返回值:

无返回值

示例:
dtask.resume();

abort


取消下载任务

void download.abort();
说明:
  • 取消下载任务后,此任务作废,不能再次启动(再次执行无任何回调);
  • 取消下载任务后,如果任务未完成,删除已下载的临时文件。
参数:

返回值:

无返回值

示例:
dtask.abort();

addEventListener


添加下载任务事件监听器

void download.addEventListener(listener);
说明:

添加下载任务事件监听器。

参数:
返回值:

无返回值

示例:
dtask.addEventListener(function(download, status){
                                if(download.state == rd.downloader.Error){
                                    download.resume();
                                }
                        });
download.start();// EventListener要在开始任务前添加

removeEventListener


移除下载任务事件监听器

void download.removeEventListener();
说明:

移除任务事件监听器。

参数:

返回值:

无返回值

示例:
dtask.removeEventListener();

addCompletedListener


添加下载任务事件完成监听器

void download.addCompletedListener(listener);
download.start();// CompletedListener要在开始任务前添加
说明:

添加下载任务事件完成监听器。

参数:
返回值:

无返回值

示例:
dtask.addCompletedListener(function(download, status){
alert(status)});

removeCompletedListener


移除下载任务事件完成监听器

void download.removeCompletedListener();
说明:

移除下载任务事件完成监听器。

参数:

返回值:

无返回值

示例:
dtask.removeCompletedListener();

DownloadOption


下载任务的参数

 DownloadOption {
    property String method,
    property String filePath,
    property Number timeout,
    property Number retry
}
说明:

在创建下载任务时设置的参数。

属性:
  • method: (String )网络请求类型 可选 默认"GET"

    支持“GET”、“POST”请求。

  • filePath: (String )下载文件保存的路径

  • timeout: (Number)下载任务超时时间

    数值类型,单位为s,默认值为120s。 超时时间为服务器响应请求的时间。

  • retry: (Number)下载任务重试次数 rd.downloader.Ready 数值类型,默认为重试3次。

DownloadStateChangedCallback


下载任务状态变化回调

void DownloadStateChangedCallback ( Download download, status ) {
// Download state changed code.
}
参数:
  • download: ( Download ) 必选 下载任务对象
  • status: ( Number ) 必选 Http传输协议状态码,下载成功为200、206
返回值:

无返回值