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

PDSClient提供了downloadFile和createDownloadTask两种下载单个文件的方法。本文将介绍如何利用这两种方法来从PDS服务中下载文件。

说明

关于Web端下载：

在使用Web端下载文件时，由于浏览器API的限制，当浏览器缓存不足时可能会报错且难以获取具体原因，因此目前不建议使用downloadFile和createDownloadTask两种方式进行Web端下载文件操作。

使用Web端下载文件时，推荐使用以下方式进行操作。

单个文件下载：
使用listFiles方法或getFile方法方法获取的文件IFileItem对象中包含download_url字段，可以直接在浏览器中打开该URL进行下载。此方法适用于单个文件的快速下载，不适用于批量文件或目录。
多个文件或目录下载：
递归遍历文件列表和目录中的每个文件的download_url，在前端下载并压缩成zip文件。这种方法适用于下载多个文件或整个目录，但会占用较大的内存，不适合下载大型文件或目录。

downloadFile方法

下载文件便捷方法。

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	Partial<IDownCheckpoint>	是	下载源对象。或者下载断点信息。
downloadTo	string	是	本地文件路径。如果是浏览器端下载，这个字段无效，一般传入空字符串""即可。
options	IDownloadOptions		下载配置（包括回调方法等）。

IDownCheckpoint字段说明

字段	类型	必选	说明
path_type	string	是	domain 的`path_type`属性。取值范围：`StandardMode`。
loc_id	string		（不推荐，请使用`drive_id`或者`share_id`替代）下载文件所在的`drive_id`或者`share_id`。
loc_type	string		下载文件所在的类型配合`loc_id`使用，取值范围： "`drive`" 或者 "`share`"。
file_key	string		下载文件唯一标识。file_key和file_id 必选其一。
drive_id	string		云盘ID。`drive_id`和`share_id`互斥，只需传一个即可。
share_id	string		分享ID。`drive_id`和`share_id`互斥，只需传一个即可。
file_id	string		要下载的文件ID。file_key和file_id 必选其一。
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 传入一种即可。

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方法

创建一个下载任务。

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` 。