Chrome 扩展开发 API实战：Downloads（四）

1. 引言

在开发 Chrome 扩展程序时，下载功能是一个非常常见的需求，而 chrome.downloads API 正是为此设计的。它允许开发者管理和操作浏览器中的下载任务，比如开始新下载、查询下载状态以及控制下载文件的行为。本篇文章将详细介绍 chrome.downloads API 的所有方法及其实际用法。

2. 权限声明

在 manifest.json 文件中声明 downloads 权限。例如：

{
  "name": "My Extension",
  "permissions": [
    "downloads"
  ]
}

声明了该权限后，扩展程序可以正常访问浏览器中的下载管理功能。

3. chrome.downloads.search

3.1 方法功能

搜索已有的下载任务。

3.2 使用方法

chrome.downloads.search(
  { query: ['example'] }, // Search query
  function(results) {
    console.log('Search results:', results);
  }
);

3.3 参数详解

query：匹配文件名或 URL 的字符串数组。
callback：返回匹配到的下载项数组。

3.4 实际样例

搜索名为 "example" 的所有下载任务：

chrome.downloads.search(
  { query: ['example'] },
  function(results) {
    console.log('Search results:', results);
  }
);

3.5 注意事项

查询条件支持多字段组合。
结果包括下载记录中的详细信息，例如状态、文件路径等。

4. chrome.downloads.pause

4.1 方法功能

暂停指定的下载任务。

4.2 使用方法

chrome.downloads.pause(downloadId, function() {
  console.log('Download paused:', downloadId);
});

4.3 参数详解

downloadId (必需)：需要暂停的下载任务 ID。

4.4 实际样例

暂停一个活动下载任务：

chrome.downloads.pause(123, function() {
  console.log('Download paused:', 123);
});

4.5 注意事项

下载任务必须处于活动状态，否则无法暂停。
一些任务可能因浏览器限制无法暂停。

5. chrome.downloads.resume

5.1 方法功能

恢复已暂停的下载任务。

5.2 使用方法

chrome.downloads.resume(downloadId, function() {
  console.log('Download resumed:', downloadId);
});

5.3 参数详解

downloadId (必需)：需要恢复的下载任务 ID。

5.4 实际样例

恢复一个已暂停的下载任务：

chrome.downloads.resume(123, function() {
  console.log('Download resumed:', 123);
});

5.5 注意事项

下载任务必须处于暂停状态，否则无法恢复。
确保下载任务的网络资源仍可访问。

6. chrome.downloads.cancel

6.1 方法功能

取消指定的下载任务。

6.2 使用方法

chrome.downloads.cancel(downloadId, function() {
  console.log('Download canceled:', downloadId);
});

6.3 参数详解

downloadId (必需)：需要取消的下载任务 ID。

6.4 实际样例

取消一个下载任务：

chrome.downloads.cancel(123, function() {
  console.log('Download canceled:', 123);
});

6.5 注意事项

已完成的下载任务无法取消。
取消任务后需手动清理相关文件。

7. chrome.downloads.erase

7.1 方法功能

从下载记录中移除符合查询条件的下载项。

7.2 使用方法

chrome.downloads.erase(
  { url: 'https://example.com/file.zip' },
  function(removedItems) {
    console.log('Removed downloads:', removedItems);
  }
);

7.3 参数详解

url：匹配的 URL。
callback：返回移除的下载项数量。

7.4 实际样例

移除特定 URL 的下载记录：

chrome.downloads.erase(
  { url: 'https://example.com/file.zip' },
  function(removedItems) {
    console.log('Removed downloads:', removedItems);
  }
);

7.5 注意事项

此操作不会删除硬盘上的文件。
仅移除记录数据，文件需用户手动管理。

8. 示例项目

以下是一个使用 chrome.downloads API 的实际例子，开发一个简单的下载管理扩展。

// Start a download
chrome.downloads.download(
  { url: 'https://example.com/file.zip' },
  function(downloadId) {
    console.log('Download started with ID:', downloadId);
  }
);

// Accept dangerous download
chrome.downloads.acceptDanger(1, function() {
  console.log('Dangerous download accepted');
});

// Remove file
chrome.downloads.removeFile(1, function() {
  console.log('File removed');
});

// Set UI options
chrome.downloads.setUiOptions({ showWhenStarting: false }, function() {
  console.log('UI options set');
});

// Show download in folder
chrome.downloads.show(1);

// Show default download folder
chrome.downloads.showDefaultFolder();

9. 额外说明

9.1 限制

API 仅适用于具有下载权限的扩展程序。
某些下载任务可能因安全策略被限制。

9.2 性能优化建议

合理使用事件监听，避免过多冗余操作。
避免频繁调用查询方法以减少资源消耗。

10. 总结

本篇文章详细介绍了 chrome.downloads API 的主要功能及用法，并通过示例展示了如何实现一个简单的下载管理工具。在下篇文章中，我们将进一步探讨如何结合 chrome.notifications API 为下载状态提供用户通知功能，敬请期待！