Chrome 扩展开发 API实战：History（三）

Chrome.history API 技术文档

1. 引言

Chrome 扩展提供了一套强大的 API，用于处理浏览器历史记录操作。通过 chrome.history API，开发者可以高效地实现搜索、管理和清理历史记录的功能。本文档详细介绍了该模块的功能，适合初学者及希望深入了解浏览器扩展开发的用户。

---

2. 权限声明

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

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

声明了该权限后，扩展程序可以正常访问浏览器中的历史记录功能。

---

3. chrome.history.search

3.1 方法功能

搜索符合指定条件的历史记录。通过关键词或时间范围进行过滤，返回满足条件的记录。

3.2 实际使用场景

该方法可用于开发浏览器插件，帮助用户快速搜索并整理浏览器的访问记录，例如查找过去一周访问过的某些特定网站。

3.3 参数

chrome.history.search(
  {
    text: string,       // Search keywords
    startTime: number,  // Start time (timestamp)
    endTime: number,    // End time (timestamp)
    maxResults: number  // Maximum number of results
  },
  function(results) {   // Callback function
    console.log(results);
  }
);

3.4 示例

搜索过去 7 天访问过的包含 "example" 的历史记录：

chrome.history.search(
  {
    text: 'example',
    startTime: Date.now() - 7 * 24 * 60 * 60 * 1000, // Seven days ago
    maxResults: 10
  },
  function(results) {
    results.forEach(entry => console.log(entry.url));
  }
);

3.5 返回值

返回包含历史记录对象的数组：

{
  id: string,    // Unique identifier
  url: string,   // Link address
  title: string, // Page title
  lastVisitTime: number, // Last visit timestamp
  visitCount: number,    // Visit count
  typedCount: number     // Manually typed count
}

3.6 注意事项

1. startTime 和 endTime 的时间戳单位为毫秒。
2. 结果可能包含重复的 URL，需在插件逻辑中去重。

---

4. chrome.history.getVisits

4.1 方法功能

获取指定 URL 的访问详情，返回用户访问页面的方式及时间。

4.2 实际使用场景

可用于分析用户访问特定网页的行为模式，例如通过点击链接还是手动输入访问。

4.3 参数

chrome.history.getVisits(
  { url: string },
  function(visitItems) {
    console.log(visitItems);
  }
);

4.4 示例

获取指定 URL 的访问详情：

chrome.history.getVisits(
  { url: 'https://example.com' },
  function(visitItems) {
    visitItems.forEach(visit => console.log(visit.visitTime));
  }
);

4.5 返回值

返回包含访问详情对象的数组：

{
  visitId: string,       // Unique identifier
  visitTime: number,     // Visit timestamp
  referringVisitId: string, // Previous visit ID
  transition: string     // Transition type (e.g., link, typed)
}

4.6 注意事项

1. 某些字段如 transition 提供了用户访问来源的信息，可用于行为分析。
2. 当 URL 不在历史记录中时，返回的数组为空。

---

5. chrome.history.addUrl

5.1 方法功能

向历史记录中添加新链接，模拟用户访问过某页面的行为。

5.2 实际使用场景

在开发调试历史记录相关功能时，可使用该方法快速填充测试数据。

5.3 参数

chrome.history.addUrl(
  { url: string },
  function() {
    console.log('URL added');
  }
);

5.4 示例

向历史记录中添加一个新链接：

chrome.history.addUrl(
  { url: 'https://example.com' },
  function() {
    console.log('URL successfully added!');
  }
);

5.5 注意事项

1. 添加的 URL 必须为有效的链接，否则操作会失败。
2. 添加的记录会立即出现在历史记录查询中。

---

6. chrome.history.deleteUrl

6.1 方法功能

从历史记录中删除指定的链接。

6.2 实际使用场景

开发清理工具时，帮助用户移除敏感或多余的历史记录。

6.3 参数

chrome.history.deleteUrl(
  { url: string },
  function() {
    console.log('URL deleted');
  }
);

6.4 示例

从历史记录中删除一个链接：

chrome.history.deleteUrl(
  { url: 'https://example.com' },
  function() {
    console.log('Deleted from history!');
  }
);

6.5 注意事项

1. 只删除记录，硬盘上的缓存文件不会受影响。
2. 删除后，该链接不会出现在历史记录中。

---

7. chrome.history.deleteRange

7.1 方法功能

根据时间范围删除历史记录。

7.2 实际使用场景

帮助用户快速清理指定时间段内的浏览记录，例如清理过去一周的隐私数据。

7.3 参数

chrome.history.deleteRange(
  {
    startTime: number, // Start time
    endTime: number    // End time
  },
  function() {
    console.log('History range deleted');
  }
);

7.4 示例

删除过去 7 天的所有历史记录：

chrome.history.deleteRange(
  {
    startTime: Date.now() - 7 * 24 * 60 * 60 * 1000, // Seven days ago
    endTime: Date.now()
  },
  function() {
    console.log('Deleted history for the last 7 days');
  }
);

7.5 注意事项

1. 删除的范围需要精确指定，避免误删重要记录。
2. 时间戳需与系统时间格式一致。

---

8. chrome.history.deleteAll

8.1 方法功能

清空所有历史记录。

8.2 实际使用场景

适用于开发一键清理工具，帮助用户快速清空浏览器的所有历史记录，释放存储空间。

8.3 参数

无。

8.4 示例

清空所有历史记录：

chrome.history.deleteAll(function() {
  console.log('All history deleted');
});

8.5 注意事项

1. 该操作不可撤销，应确保用户确认清理。
2. 删除后，历史记录查询将返回空结果。

---

9. 总结

本文详细说明了 chrome.history 提供的所有 API，包括搜索、获取详情、添加和删除操作。通过这些功能，开发者可以高效地管理用户的历史记录，构建更加智能的浏览器插件。下一篇文章将探讨 Chrome 扩展的其他模块及其应用场景，敬请期待。