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