下载文件_网盘与相册服务(PDS)-阿里云帮助中心

PDSClient 提供2种下载单个文件方法： downloadFile 和 createDownloadTask，目前仅支持 Node.js 环境（或 Electron ）。下面分别介绍。

说明

关于Web端下载：

Web 端和桌面端下载文件不一样。web 端的下载有3种方式，下面分别介绍下。

第一种：listFiles/getFile 返回的文件 IFileItem 里有个 download_url 字段，可以用浏览器直接打开下载。这种方式只能下载单个文件，不能下载多个文件或目录。

第二种：开通服务端打包下载的增值服务，调用 client.pollingArchiveFile() 方法，拿到 url 字段后用浏览器直接打开下载。这种方式可以下载多个文件和目录。

第三种：递归遍历文件列表和目录中的每个文件的 download_url，在前端下载并 zip。这种方式可以下载多个文件和目录，但是占用内存较大，不适合下载较大文件或目录。

Web 端下载，推荐使用第一和第二种结合的方式。单个文件用第一种，多个文件或目录用第二种。

downloadFile 方法

下载文件便捷方法。

重要

此方法仅支持 Node.js 环境（或Electron）。

await 会等待下载完成。
state 为 stopped, cancelled 和 error 时，会 throw PDSError。

const cp = await client.downloadFile(pdsFile, downloadTo, options)

举例

// from
const pdsFile= {
  drive_id: '1',
  file_id: 'xxxxxxxx',
}

// to
const downloadTo = '/Users/test/a.txt'

const options = {
  onProgress(state, progress){
    console.log(state, progress)
  }
}

// 下载
await client.downloadFile(pdsFile, downloadTo, options)；

console.log('下载完成');

参数说明

字段	类型	必选	说明
pdsFile	IDownCheckpoint	是	下载源对象。或者下载断点信息。
downloadTo	string	是	本地文件路径。
options	IDownloadOptions		下载配置（包括回调方法等）。

IDownCheckpoint 字段说明

字段	类型	必选	说明
path_type	string	是	domain 的 `path_type` 属性。取值范围： `StandardMode`, `HostingMode`。
loc_id	string		（不推荐，请使用`drive_id` 或者 `share_id` 替代）下载文件所在的 `drive_id` 或者 `share_id`。
loc_type	string		下载文件所在的类型配合 `loc_id` 使用，取值范围： "`drive`" 或者 "`share`"。
file_key	string		下载文件唯一标识。标准模式为目录ID，托管模式为目录Path。
drive_id	string		云盘ID。 `drive_id`和`share_id`互斥，只需传一个即可。
share_id	string		（托管模式有效）共享ID。`drive_id`和`share_id`互斥，只需传一个即可。
file_id	string		要下载的文件ID（标准模式）。`file_id` 和`file_path` 互斥，只需传一个即可。
file_path	string		要下载的文件路径（托管模式）。`file_id` 和`file_path` 互斥，只需传一个即可。
file	IFile	是	下载目的的本地文件对象。
id	string		下载任务ID
download_id	string		下载ID。本地临时文件创建成功，会生成此ID。
download_url	string		下载url
content_md5	string		文件的`MD5`值
crc64ecma	string		文件的`crc64`值
content_type	string		文件的`content-type`
part_info_list	Array<IDownPartInfo>		下载分片信息
state	string		下载任务状态，取值范围： `waiting, start, created, running, stopped, complete, checking, success, error, cancelled`
message	string		报错信息。
progress	number		下载进度信息。取值0-100。
loaded	number		已经下载的字节数 (`Bytes`)
start_time	number		开始下载时间（单位：`ms`）
end_time	number		结束下载时间（单位：`ms`）
used_avg_speed	number		平均速度（单位：`Bytes/s`）
used_time_len	number		已用时长（单位：`ms`）

loc_id & loc_type 和 share_id || drive_id 传入一组即可。
file_key 和 file_id || file_path 传入一组即可。

IDownloadOptions (extends IDownConfig)

字段	类型	必选	说明
onReady	(task: UploadTask) => void		UploadTask创建好后回调方法。
onProgress	(state: string, progress:number) => void		监听进度变化的回调方法。支持下载进度，计算`crc64`进度的监听。 `state` 的取值范围为：`running`（正在下载）, `checking`（计算`crc64`）。 `progress` 取值范围：0 - 100。
onStateChange	(cp: IDownCheckpoint, state: string, error?: PDSError) => void		监听任务状态变化的回调方法。 `state` 取值范围：`waiting, start, created, running, stopped, complete, checking, success, error, cancelled`
onPartComplete	(cp:IDownCheckpoint, part: IPartInfo) => void		监听分片上传完成的回调方法。
... IDownConfig 其他字段			其他字段

IDownPartInfo 字段说明

字段	类型	必选	说明
part_number	number	是	分片序号，从1开始
part_size	number	是	分片大小

IDownConfig 字段说明

字段	类型	必选	说明
verbose	boolean		是否打印调试日志
checking_crc	boolean		是否进行`crc`校验, 默认：`true`
chunk_con_auto	boolean		是否自动调整并发数
init_chunk_con	number		自定义指定并发数，`chunk_con_auto`为`false` 时生效
max_chunk_size	number		分片大小

字段	类型	必选	说明
cp	IDownCheckpoint	是	任务的断点信息。此时（任务）断点的状态，可能为 `success, error, stopped, cancelled`。

createDownloadTask 方法

创建一个下载任务。

重要

此方法仅支持 Node.js 环境（或Electron）。

const task = client.createDownloadTask(checkpoint, configs)

举例

const cp = {
  // to
  file: {
    name: "a.txt",
    path: "/Users/zu/a.txt",
    size: 100,
  },

  // from
  path_type: 'StandardMode',
  // loc_type: 'drive',
  // loc_id: '1',        // 可以使用 drive_id 替代
  // file_key: 'xxxxxxxx'  // 可以使用 file_id 替代

  drive_id: '1',
  file_id: 'xxxxxxxx',
};

const task = client.createDownloadTask(cp);

参数说明

字段	类型	必选	说明
checkpoint	IDownCheckpoint	是	下载参数
configs	IDownConfig		下载配置

返回 DownloadTask 实例。

字段	类型	必选	说明
task	DownloadTask	是	下载任务实例

DownloadTask 类介绍

用于创建一个下载文件任务。

支持方法

.wait()

调用后，任务将进入等待中状态。state改为waiting。

.start()

开始任务。直接开始分片并发下载。

task.start();

.stop()

暂停（停止）任务。state改为stopped。此时客户端可以将 checkpoint 信息存储起来，供下次断点续传。

task.stop();

.cancel()

取消任务。state将改为cancelled。

task.cancel()

.getCheckpoint()

获取checkpoint信息。除了调用此方法，还可以通过事件回调拿到checkpoint信息。

var cp = task.getCheckpoint()

.on(eventname, callback)

事件监听。

// 举例 
task.on('progress', (state, progress)=>{    
   console.log(state, progress) 
})

参数说明

字段	类型	必选	说明
eventname	string	是	事件名称，目前支持：`progress, statechange, partialcomplete`。
callback	Function	是	回调函数

支持的事件

目前支持的事件： progress, statechange, partialcomplete。

progress 事件回调函数

task.on('progress', (state, progress)=>{    
  // 
})

参数说明

字段

类型

必选

说明

state

string

是

任务状态。

state 可能值为：running（正在下载）, checking（计算crc64）。

progress

number

是

进度，取值范围： 0 - 100。

statechange 事件

task.on('statechange', (checkpoint, state, error)=>{    
  // 
})

字段	类型	必选	说明
checkpoint	IDownCheckpoint	是	下载断点信息。
state	string	是	下载任务状态，取值范围： `waiting, start, created, running, stopped, complete, checking, success, error, cancelled`
error	PDSError		下载错误。状态为 `error`, `stopped`, `cancelled` 时可能有值。

partialcomplete 事件

task.on('partialcomplete', (checkpoint, partInfo)=>{    
  // 
})

字段	类型	必选	说明
checkpoint	IDownCheckpoint	是	下载断点信息。
partInfo	IDownPartInfo	是	当前完成的分片信息。

state 状态说明

下载任务状态有 10 种：

状态	说明
waiting	等待中。任务创建后的默认状态。调用 `wait()` 方法触发。
start	开始下载。调用 `start()` 方法触发。
created	创建本地临时文件后触发。
running	下载中。
stopped	暂停下载。
complete	下载完成，未校验文件正确性。
checking	校验文件正确性（`crc64`）。
success	下载成功。
error	任务失败。下载过程中调用接口失败（包括网络错误），或者本地 IO 操作失败，均会触发。
cancelled	任务取消。调用 `.cancel()` 方法才会触发。

可能会用到的属性

状态	类型	说明
speed	number	下载速度，单位 `Byte/s`。状态为running时有效。
progress	number	进度。取值 0-100。
loaded	number	已经下载的大小。单位 `Byte`。
file	IFile	文件信息。
left_time	number	大约的剩余时间，单位 `s`。
start_time	number	开始时间。单位 `ms`。
end_time	number	结束时间。单位 `ms`。
used_avg_speed	number	统计的平均下载速度，单位 `Byte/s`。
used_time_len	number	统计的耗时，单位 `ms` 。