跳到主要内容

downloads 下载

启动、监视、操作和搜索下载，此权限会触发警告

权限设置​

{
  "permissions": [
    "downloads"
  ],
}

方法​

setShelfEnabled() 设置下载栏是否可见​

设置下载栏是否可见。底部灰色下载栏。新版本使用setUiOptions

chrome.downloads.setShelfEnabled(enabled: boolean, callback?: function);

download() 下载链接​

下载文件

// 下载项信息
type downloadItemInfo = {
  // 曾下载文件的URL
  url: string;
  // 曾下载文件的文件名
  filename: string;
  // 曾下载文件的保存路径
  saveAs: boolean;
  // 曾下载文件的请求头
  headers: object[];
  // 曾下载文件的请求体
  body: object;
  // 曾下载文件的请求方法
  method: 'GET' | 'POST';
  // 曾下载文件的请求类型
  type: 'image' | 'video' | 'audio' | 'text' | 'application' | 'multipart' | 'other';
  // 曾下载文件的大小
  totalBytes: number;
  // 曾下载文件的状态
  state: 'in_progress' | 'interrupted' | 'complete';
  // 曾下载文件的状态信息
  paused: boolean;
  // 曾下载文件的错误信息
  error: string;
  // 曾下载文件的创建时间
  startTime: number;
  // 曾下载文件的结束时间
  endTime: number;
  // 曾下载文件的持续时间
  elapsedTime: number;
  // 曾下载文件的最后修改时间
  lastModified: number;
  // 曾下载文件的最后访问时间
  lastAccessed: number;
  // 曾下载文件的MIME类型
  mime: string;
  // 曾下载文件的SHA1哈希值
  sha1: string;
  // 曾下载文件的SHA256哈希值
  sha256: string;
  // 曾下载文件的MD5哈希值
  md5: string;
  // 曾下载文件的CRC32C哈希值
  crc32c: string;
  // 曾下载文件的安全状态
  danger: 'safe' | 'accepted' | 'accepted_with_warning' | 'unknown';
  // 曾下载文件的是否可恢复
  canResume: boolean;
  // 曾下载文件的是否已删除
  exists: boolean;
  // 曾下载文件的是否已打开
  opened: boolean;
  // 曾下载文件的是否已保存
  state: 'in_progress' | 'interrupted' | 'complete';
}

chrome.downloads.download(downloadItemInfo: downloadItemInfo, callback?: function);
// background.js
chrome.downloads.download({
  url: 'https://www.baidu.com',
  filename: 'baidu.html',
  saveAs: false,
  headers: [],
  body: {},
  method: 'GET',
  type: 'text',
  totalBytes: 0,
  state: 'in_progress',
  paused: false,
  error: '',
  startTime: 0,
  endTime: 0,
  elapsedTime: 0,
  lastModified: 0,
  lastAccessed: 0,
  mime: '',
  sha1: '',
  sha256: '',
  md5: '',
  crc32c: '',
  danger: 'safe',
  canResume: false,
  exists: false,
  opened: false,
}, (downloadItem) => {
  console.log('🍄  background: >>>>>>>>>>>>>>>>>> 下载文件', Date.now(), downloadItem);
});

search() 搜索​

搜索浏览器曾经下载过的所有文件

type DownloadQuery = {
  id: number;

  // 曾下载文件的URL
  url: string;
  urlRegex: string;
  finalUrl: string;
  finalUrlRegex: string;

  // 曾下载文件的文件名
  filename: string;
  filenameRegex: string;

  // 搜索结果的最大数量
  limit: number;

  // 搜索结果排序：orderBy = [‘ startTime’]按照开始时间升序，若要指定降序顺序，请在前缀中加上连字符: “-startTime”。
  orderBy: string[];

  // url链接参数
  query: string[];

  // 曾下载文件的状态
  state: 'in_progress' | 'interrupted' | 'complete';

  // 曾下载文件的MIME类型
  mime: string;

  // 曾下载文件的是否已删除
  exists: boolean;

  // 曾下载文件的状态信息
  paused: boolean;
  // 曾下载文件的错误信息
  error: string;

  // 曾下载文件的创建时间
  startTime: number;
  startedAfter: number;
  startedBefore: number;
  // 曾下载文件的结束时间
  endTime: number;
  endedAfter: number;
  endedBefore: number;
  // 曾下载文件的持续时间
  elapsedTime: number;
  // 曾下载文件的最后修改时间
  lastModified: number;
  // 曾下载文件的最后访问时间
  lastAccessed: number;
  // 曾下载文件的安全状态
  danger: 'safe' | 'accepted' | 'accepted_with_warning' | 'unknown';
  // 曾下载文件的大小
  fileSize: number;
  totalBytes: number;
  totalBytesGreater: number;
  totalBytesLess: number;
}
// 下载查询条件
// query: {} 查询所有
chrome.downloads.search(
  query: DownloadQuery,
  callback?: (res) => void,
)
// background.js
chrome.downloads.search({
  limit: 100,
  orderBy: ['-startTime'],
}, (downloadItems) => {
  console.log('🍄  background: >>>>>>>>>>>>>>>>>> 搜索下载文件', Date.now(), downloadItems);
});

open() 打开文件​

打开已下载的文件

chrome.downloads.open(
  downloadId: number,
  callback?: function,
)

pause() 暂停下载​

暂停下载

chrome.downloads.pause(
  downloadId: number,
  callback?: function,
)

resume() 恢复下载​

恢复下载

chrome.downloads.resume(
  downloadId: number,
  callback?: function,
)

cancel() 取消下载​

取消下载

chrome.downloads.cancel(
  downloadId: number,
  callback?: function,
)

erase() 删除下载​

删除下载

chrome.downloads.erase(
  query: DownloadQuery,
  callback?: function,
)

removeFile() 删除文件​

删除文件

chrome.downloads.removeFile(
  downloadId: number,
  callback?: function,
)

acceptDanger() 接受危险​

接受危险

chrome.downloads.acceptDanger(
  downloadId: number,
  callback?: function,
)

show() 显示下载​

显示下载

chrome.downloads.show(
  downloadId: number,
  callback?: function,
)

getFileIcon() 获取文件图标​

获取文件图标

chrome.downloads.getFileIcon(
  downloadId: number,
  options: {
    size: number,
  },
  callback?: function,
)

showDefaultFolder() 显示默认文件夹​

显示默认文件夹

chrome.downloads.showDefaultFolder()

事件​

onCreated 创建事件​

下载项被下载时触发

// background.js
chrome.downloads.onCreated.addListener((item) => {
  console.log('🍄  background: >>>>>>>>>>>>>>>>>> 监听创建事件', Date.now(), item);
});

onErased 删除事件​

当下载项被删除时触发

// background.js
chrome.downloads.onErased.addListener((item) => {
  console.log('🍄  background: >>>>>>>>>>>>>>>>>> 监听删除事件', Date.now(), item);
});

onChanged 更新事件​

当下载项的状态发生变化时触发，例如下载完成、下载失败、下载暂停、下载恢复、下载取消等

// background.js
chrome.downloads.onChanged.addListener((item) => {
  //   {
  //     "error": {
  //         "current": "USER_CANCELED"
  //     },
  //     "id": 254,
  //     "state": {
  //         "current": "interrupted",
  //         "previous": "in_progress"
  //     }
  //    }
  console.log('🍄  background: >>>>>>>>>>>>>>>>>> 监听更新事件', Date.now(), item);
});

onDeterminingFilename 取文件名事件​

当下载项的文件名需要确定时触发

// background.js
chrome.downloads.onDeterminingFilename.addListener((item, suggest) => {
  // 默认覆盖原文件名
  suggest({
    filename: item.filename,
    conflict_action: 'overwrite',
    conflictAction: 'overwrite'
  })
  console.log('🍄  background: >>>>>>>>>>>>>>>>>> 监听取文件名事件', Date.now(), item, suggest);
});