browser.history

说明

使用 chrome.history API 与浏览器的已访问网页记录进行交互。您可以在浏览器的历史记录中添加、移除和查询网址。如需使用您自己的版本替换历史记录页面，请参阅替换页面。

权限

history

如需与用户的浏览器历史记录进行交互，请使用 history API。

如需使用 History API，请在扩展程序清单中声明 "history" 权限。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

概念和用法

切换类型

History API 使用转换类型来描述浏览器在特定访问中如何导航到特定网址。例如，如果用户通过点击其他网页上的链接访问某个网页，则转换类型为“link”。如需查看过渡类型列表，请参阅参考内容。

示例

如需试用此 API，请从 chrome-extension-samples 代码库中安装历史记录 API 示例。

类型

HistoryItem

封装历史记录查询结果的对象。

属性

  • id

    字符串

    商品的唯一标识符。

  • lastVisitTime

    number 可选

    此网页的上次加载时间（以自纪元以来的毫秒数表示）。

  • title

    字符串 可选

    网页上次加载时的标题。

  • typedCount

    number 可选

    用户通过输入地址访问此页面的次数。

  • 网址

    字符串 可选

    用户访问的网址。

  • visitCount

    number 可选

    用户导航到此页面的次数。

TransitionType

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

此访问从其引荐来源网址的转换类型。

枚举

“link”
用户通过点击其他页面上的链接到达此页面。

“typed”
用户通过在地址栏中输入网址到达此网页。此方法也用于其他显式导航操作。

"auto_bookmark"
用户通过界面中的建议（例如通过菜单项）到达此页面。

"auto_subframe"
用户通过并非由其请求的子框架导航到达此网页，例如通过上一页中某个框架内加载的广告。这些操作不一定会生成新的后退和前进菜单导航条目。

"manual_subframe"
用户通过在子框架中选择某项内容而到达此页面。

"generated"
用户通过在地址栏中输入内容并选择一个看起来不像网址的条目（例如 Google 搜索建议）到达此网页。例如，匹配项可能包含 Google 搜索结果页面的网址，但对用户而言，它可能显示为“在 Google 中搜索…”。这些与输入网址导航不同，因为用户并未输入或看到目标网址。它们还与关键字导航相关。

"auto_toplevel"
该网页是在命令行中指定的，或者是起始页。

"form_submit"
用户通过在表单中填写值并提交表单到达此页面。并非所有表单提交都使用此转换类型。

"reload"
用户通过点击重新加载按钮或在地址栏中按 Enter 键重新加载了网页。会话恢复和重新打开已关闭的标签页也使用此转换类型。

“keyword”
此页面的网址是由默认搜索服务提供商以外的可替换关键字生成的。

"keyword_generated"
对应于由关键字促成的访问。

UrlDetails

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

属性

  • 网址

    字符串

    操作的网址。其格式必须与调用 history.search() 时返回的格式相同。

VisitItem

一个封装对某个网址的一次访问的对象。

属性

  • id

    字符串

    对应 history.HistoryItem 的唯一标识符。

  • isLocal

    布尔值

    Chrome 115 及更高版本 browser.*（自 Chrome 148 起）

    如果到访记录源自此设备，则为 True。如果它是从其他设备同步的，则为 false。

  • referringVisitId

    字符串

    引荐来源网址的访问 ID。

  • 此访问从其引荐来源网址的转换类型。

  • visitId

    字符串

    此访问的唯一标识符。

  • visitTime

    number 可选

    此次访问发生的时间，以自纪元以来的毫秒数表示。

方法

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

在当前时间向历史记录添加一个网址，其转换类型为“link”。

参数

返回

  • 承诺<void>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

deleteAll()

browser.history.deleteAll(): Promise<void>

从历史记录中删除所有内容。

返回

  • 承诺<void>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

从历史记录中移除指定日期范围内的所有内容。除非所有访问记录都在该范围内，否则系统不会从历史记录中移除相应网页。

参数

  • 范围

    对象

    • endTime

      数值

      在此日期之前添加到历史记录中的内容，以自新纪元开始算起的毫秒数表示。

    • startTime

      数值

      在此日期之后添加到历史记录中的内容，以自纪元以来的毫秒数表示。

返回

  • 承诺<void>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

从历史记录中移除给定网址的所有出现记录。

参数

返回

  • 承诺<void>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

检索网址访问信息。

参数

返回

  • Promise<VisitItem[]>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起） 
browser.history.search(
  query: object,
): Promise<HistoryItem[]>

在历史记录中搜索与查询匹配的每个网页的上次访问时间。

参数

  • 查询

    对象

    • endTime

      number 可选

      将结果限制为在此日期之前访问过的结果，以自纪元以来的毫秒数表示。

    • maxResults

      number 可选

      要检索的结果数上限。默认值为 100。

    • startTime

      number 可选

      将结果限制为在此日期之后访问过的结果，以自纪元以来的毫秒数表示。如果未指定属性，则默认为 24 小时。

    • text

      字符串

      向历史记录服务发出的自由文本查询。将此字段留空可检索所有页面。

返回

  • Promise<HistoryItem[]>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

事件

onVisited

browser.history.onVisited.addListener(
  callback: function,
)

在访问网址时触发，提供该网址的 HistoryItem 数据。此事件会在网页加载之前触发。

参数

onVisitRemoved

browser.history.onVisitRemoved.addListener(
  callback: function,
)

从历史记录中移除一个或多个网址时触发。当所有访问记录都被移除后，该网址就会从历史记录中清除。

参数

  • callback

    函数

    callback 参数如下所示： 

    (removed: object) => void

    • 已移除

      对象

      • allHistory

        布尔值

        如果所有历史记录均已移除，则为 True。如果为 true，则网址将为空。

      • 网址

        string[] 可选