refresh date: 2026-09-25 robots: noindex
说明
使用 chrome.history API 与浏览器的已访问网页记录进行交互。您可以在浏览器的历史记录中添加、移除和查询网址。如需使用您自己的版本替换历史记录页面，请参阅替换页面。
权限
history清单
必须在扩展程序清单中声明“history”权限，才能使用 History API。例如：
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
切换类型
History API 使用过渡类型来描述浏览器在特定访问中如何导航到特定网址。例如，如果用户通过点击另一个网页上的链接访问某个网页，则过渡类型为“link”。
下表介绍了每种过渡类型。
| 过渡类型 | 说明 |
|---|---|
| "link" | 用户通过点击另一个页面上的链接进入此页面。 |
| “输入” | 用户通过在地址栏中输入网址访问了此网页。也用于其他明确的导航操作。另请参阅生成的，该值用于用户选择的选项看起来完全不像网址的情况。 |
| "auto_bookmark" | 用户通过界面中的建议（例如，通过菜单项）进入此页面。 |
| "auto_subframe" | 子框架导航。这是指在非顶级框架中自动加载的任何内容。例如，如果某个网页由多个包含广告的框架组成，则这些广告网址会具有此过渡类型。用户甚至可能没有意识到这些网页中的内容是一个单独的框架，因此可能不会关心网址（另请参阅 manual_subframe）。 |
| "manual_subframe" | 对于由用户明确请求并在后退/前进列表中生成新导航条目的子框架导航。明确请求的框架可能比自动加载的框架更重要，因为用户可能更关心请求的框架是否已加载。 |
| “generated” | 用户通过在地址栏中输入内容并选择一个看起来不像网址的条目，进入了此页面。例如，匹配项可能包含 Google 搜索结果页面的网址，但对用户而言，它可能显示为“在 Google 中搜索…”。这些与输入导航不完全相同，因为用户并未输入或看到目标网址。另请参阅关键字。 |
| "auto_toplevel" | 该页面是在命令行中指定的，或者是起始页。 |
| "form_submit" | 用户在表单中填写了值并提交了表单。请注意，在某些情况下（例如，当表单使用脚本提交内容时），提交表单不会导致此过渡类型。 |
| “reload” | 用户通过点击重新加载按钮或在地址栏中按 Enter 键重新加载了网页。会话恢复和重新打开已关闭的标签页也使用此过渡类型。 |
| "关键字" | 该网址是通过默认搜索服务提供商以外的可替换关键字生成的。另请参阅 keyword_generated。 |
| "keyword_generated" | 对应于为关键字生成的访问。另请参阅关键字。 |
示例
如需试用此 API，请从 chrome-extension-samples 代码库中安装历史记录 API 示例。
类型
HistoryItem
封装历史记录查询结果的对象。
属性
-
id
字符串
商品的唯一标识符。
-
lastVisitTime
number 可选
此网页的上次加载时间（以自纪元以来的毫秒数表示）。
-
title
字符串 可选
网页上次加载时的标题。
-
typedCount
number 可选
用户通过输入地址访问此页面的次数。
-
网址
字符串 可选
用户访问的网址。
-
visitCount
number 可选
用户导航到此页面的次数。
枚举
“link”
用户通过点击其他页面上的链接到达此页面。
“typed”
用户通过在地址栏中输入网址到达此网页。此方法也用于其他显式导航操作。
"auto_bookmark"
用户通过界面中的建议（例如通过菜单项）到达此页面。
"auto_subframe"
用户通过并非由其请求的子框架导航到达此网页，例如通过上一页中某个框架内加载的广告。这些操作不一定会生成新的后退和前进菜单导航条目。
"manual_subframe"
用户通过在子框架中选择某项内容而到达此页面。
"generated"
用户通过在地址栏中输入内容并选择一个看起来不像网址的条目（例如 Google 搜索建议）到达此网页。例如，匹配项可能包含 Google 搜索结果页面的网址，但对用户而言，它可能显示为“在 Google 中搜索…”。这些与输入网址导航不同，因为用户并未输入或看到目标网址。它们还与关键字导航相关。
"auto_toplevel"
该网页是在命令行中指定的，或者是起始页。
"form_submit"
用户通过在表单中填写值并提交表单到达此页面。并非所有表单提交都使用此转换类型。
"reload"
用户通过点击重新加载按钮或在地址栏中按 Enter 键重新加载了网页。会话恢复和重新打开已关闭的标签页也使用此转换类型。
“keyword”
此页面的网址是由默认搜索服务提供商以外的可替换关键字生成的。
"keyword_generated"
对应于由关键字促成的访问。
UrlDetails
属性
-
网址
字符串
操作的网址。其格式必须与调用
history.search()时返回的格式相同。
VisitItem
一个封装对某个网址的一次访问的对象。
属性
-
id
字符串
对应
history.HistoryItem的唯一标识符。 -
isLocal
布尔值
Chrome 115 及更高版本如果到访记录源自此设备，则为 True。如果它是从其他设备同步的，则为 false。
-
referringVisitId
字符串
引荐来源网址的访问 ID。
-
此访问从其引荐来源网址的转换类型。
-
visitId
字符串
此访问的唯一标识符。
-
visitTime
number 可选
此次访问发生的时间，以自纪元以来的毫秒数表示。
方法
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
): Promise<void>
在当前时间向历史记录添加一个网址，其转换类型为“link”。
参数
-
详细信息
-
callback
函数可选
callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
deleteAll()
chrome.history.deleteAll(
callback?: function,
): Promise<void>
从历史记录中删除所有内容。
参数
-
callback
函数可选
callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
): Promise<void>
从历史记录中移除指定日期范围内的所有内容。除非所有访问记录都在该范围内，否则系统不会从历史记录中移除相应网页。
参数
-
范围
对象
-
endTime
数值
在此日期之前添加到历史记录中的内容，以自新纪元开始算起的毫秒数表示。
-
startTime
数值
在此日期之后添加到历史记录中的内容，以自纪元以来的毫秒数表示。
-
-
callback
函数可选
callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
): Promise<void>
从历史记录中移除给定网址的所有出现记录。
参数
-
详细信息
-
callback
函数可选
callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
): Promise<VisitItem[]>
检索网址访问信息。
参数
-
详细信息
-
callback
函数可选
callback参数如下所示：(results: VisitItem[]) => void
-
结果
-
返回
-
Promise<VisitItem[]>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
search()
chrome.history.search(
query: object,
callback?: function,
): Promise<HistoryItem[]>
在历史记录中搜索与查询匹配的每个网页的上次访问时间。
参数
-
查询
对象
-
endTime
number 可选
将结果限制为在此日期之前访问过的结果，以自纪元以来的毫秒数表示。
-
maxResults
number 可选
要检索的结果数上限。默认值为 100。
-
startTime
number 可选
将结果限制为在此日期之后访问过的结果，以自纪元以来的毫秒数表示。如果未指定属性，则默认为 24 小时。
-
text
字符串
向历史记录服务发出的自由文本查询。将此字段留空可检索所有页面。
-
-
callback
函数可选
callback参数如下所示：(results: HistoryItem[]) => void
-
结果
-
返回
-
Promise<HistoryItem[]>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
事件
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
在访问网址时触发，提供该网址的 HistoryItem 数据。此事件会在网页加载之前触发。
参数
-
callback
函数
callback参数如下所示：(result: HistoryItem) => void
-
结果
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
从历史记录中移除一个或多个网址时触发。当所有访问记录都被移除后，该网址就会从历史记录中清除。
参数
-
callback
函数
callback参数如下所示：(removed: object) => void
-
已移除
对象
-
allHistory
布尔值
如果所有历史记录均已移除，则为 True。如果为 true，则网址将为空。
-
网址
string[] 可选
-
-