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 注意事项
startTime和endTime的时间戳单位为毫秒。- 结果可能包含重复的 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 注意事项
- 某些字段如
transition提供了用户访问来源的信息，可用于行为分析。 - 当 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 注意事项
- 添加的 URL 必须为有效的链接，否则操作会失败。
- 添加的记录会立即出现在历史记录查询中。
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 注意事项
- 只删除记录，硬盘上的缓存文件不会受影响。
- 删除后，该链接不会出现在历史记录中。
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 注意事项
- 删除的范围需要精确指定，避免误删重要记录。
- 时间戳需与系统时间格式一致。
8. chrome.history.deleteAll
8.1 方法功能
清空所有历史记录。
8.2 实际使用场景
适用于开发一键清理工具，帮助用户快速清空浏览器的所有历史记录，释放存储空间。
8.3 参数
无。
8.4 示例
清空所有历史记录：
chrome.history.deleteAll(function() {
console.log('All history deleted');
});8.5 注意事项
- 该操作不可撤销，应确保用户确认清理。
- 删除后，历史记录查询将返回空结果。
9. 总结
本文详细说明了 chrome.history 提供的所有 API，包括搜索、获取详情、添加和删除操作。通过这些功能，开发者可以高效地管理用户的历史记录，构建更加智能的浏览器插件。下一篇文章将探讨 Chrome 扩展的其他模块及其应用场景，敬请期待。