chrome.history

说明

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

权限

history

清单

您必须在扩展程序清单中声明“history”权限，才能使用 History API。例如：

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

过渡类型

History API 使用过渡类型来描述浏览器在特定访问会话中如何导航到特定网址。例如，如果用户通过点击另一网页上的链接访问某个网页，则过渡类型为“link”。

下表介绍了每种过渡类型。

过渡类型说明
“typed”用户通过在地址栏中输入网址访问了此网页。还用于其他显式导航操作。另请参阅 generated，该值用于用户选择的选项完全不像网址的情况。
"auto_bookmark"用户是通过界面中的建议（例如通过菜单项）进入此页面的。
"auto_subframe"子框架导航。这是指在非顶级框架中自动加载的任何内容。例如，如果某个网页包含多个包含广告的框架，则这些广告网址具有此过渡类型。用户可能甚至没有意识到这些网页中的内容是单独的框架，因此可能不会在意网址（另请参阅 manual_subframe）。
"manual_subframe"对于用户明确请求的子框架导航，会在“返回/前进”列表中生成新的导航条目。明确请求的帧可能比自动加载的帧更重要，因为用户可能很在意所请求的帧是否已加载。
“生成”用户通过在地址栏中输入内容并选择看起来不像网址的条目来访问此页面。例如，匹配项可能包含 Google 搜索结果页面的网址，但对用户而言，它可能显示为“在 Google 中搜索…”。这些匹配项与输入的导航不同，因为用户并未输入或看到目标网址。另请参阅关键字。
"auto_toplevel"该网页是在命令行中指定的，或者是起始网页。
"form_submit"用户在表单中填写了值并提交了表单。请注意，在某些情况下（例如表单使用脚本提交内容时），提交表单不会导致出现此过渡类型。
“重新加载”用户重新加载了网页，方法是点击重新加载按钮或在地址栏中按 Enter 键。会话恢复和重新打开已关闭的标签页也使用此过渡类型。
"关键字"该网址是根据默认搜索服务提供商以外的可替换关键字生成的。另请参阅 keyword_generated。
“keyword_generated”对应于为关键字生成的访问。另请参阅关键字。

示例

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

类型

HistoryItem

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

属性

  • id

    字符串

    商品的唯一标识符。

  • lastVisitTime

    number 可选

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

  • title

    字符串（选填）

    网页上次加载时的标题。

  • typedCount

    number 可选

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

  • 网址

    字符串（选填）

    用户访问的网址。

  • visitCount

    number 可选

    用户访问相应页面的次数。

TransitionType

Chrome 44 及更高版本

相应访问从其引荐来源网址开始的过渡类型。

枚举

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

“已输入”
用户通过在地址栏中输入网址到达此网页。此属性还用于其他明确的导航操作。

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

“auto_subframe”
用户是通过他们未请求的子框架导航到达此网页的，例如通过在上一网页的框架中加载的广告到达此网页。这些操作不一定会生成“后退”和“前进”菜单中的新导航条目。

“manual_subframe”
用户通过在子框架中选择内容到达此网页。

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

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

“form_submit”
用户通过填写表单中的值并提交表单来访问此网页。并非所有表单提交都使用此过渡类型。

“重新加载”
用户重新加载了网页，可能是通过点击重新加载按钮或在地址栏中按 Enter 键完成的。会话恢复和“重新打开关闭的标签页”功能也使用此过渡类型。

“keyword”
此网页的网址是从可替换的关键字（而非默认搜索服务提供商）生成的。

“keyword_generated”
与为关键字生成的访问相对应。

UrlDetails

Chrome 88 及更高版本

属性

  • 网址

    字符串

    相应操作的网址。必须采用从对 history.search() 的调用返回的格式。

VisitItem

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

属性

  • id

    字符串

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

  • isLocal

    布尔值

    Chrome 115 及更高版本

    如果相应访问源自此设备，则为 True。如果该内容是从其他设备同步的，则为 False。

  • referringVisitId

    字符串

    引荐来源的访问 ID。

  • 相应访问从其引荐来源网址开始的过渡类型。

  • visitId

    字符串

    相应访问的唯一标识符。

  • visitTime

    number 可选

    相应访问发生的时间，以自纪元开始计算的毫秒数表示。

方法

addUrl()

Promise 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

在当前时间向历史记录添加一个网址，并指定“link”的过渡类型。

参数

  • 详细信息

    UrlDetails

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 96 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

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

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 96 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

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

参数

  • 范围

    对象

    • endTime

      数值

      在此日期之前添加到历史记录中的项目（以毫秒为单位，从 Epoch 起算）。

    • startTime

      数值

      在此日期之后添加到历史记录中的项目（以自纪元开始算起的毫秒数表示）。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 96 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

deleteUrl()

Promise 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

参数

  • 详细信息

    UrlDetails

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 96 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

检索有关网址访问的信息。

参数

返回

  • Promise<VisitItem[]>

    Chrome 96 及更高版本

    仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

Promise 
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 数据。此事件在网页加载之前触发。

参数

onVisitRemoved

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (removed: object) => void

    • 已移除

      对象

      • allHistory

        布尔值

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

      • 网址

        string[] 可选