chrome.history

说明

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

权限

history

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

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

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

概念和用法

过渡类型

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

示例

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

类型

HistoryItem

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

属性

  • id

    string

    商品的唯一标识符。

  • lastVisitTime

    数字可选

    此网页的上次加载时间，以自纪元起经过的毫秒数表示。

  • title

    字符串（可选）

    上次加载网页时的网页标题。

  • typedCount

    数字可选

    用户通过输入地址导航到此页面的次数。

  • 网址

    字符串（可选）

    用户已导航到的网址。

  • visitCount

    数字可选

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

TransitionType

Chrome 44 及更高版本

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

枚举

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

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

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

"auto_subframe"
用户通过未请求的子框架导航（例如通过上一页的框架中加载的广告）到达此页面。这些选项并非总是在后退和前进菜单中生成新的导航条目。

"manual_subframe"
用户在子框架中选择一些内容到达此页面。

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

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

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

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

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

"keyword_generated"
对应于针对某个关键字生成的访问。

UrlDetails

Chrome 88 及更高版本

属性

  • 网址

    string

    操作的网址。它必须采用调用 history.search() 所返回的格式。

VisitItem

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

属性

  • id

    string

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

  • isLocal

    boolean

    Chrome 115 及更高版本

    如果访问源自此设备，则为 true。如果是从其他设备上同步，则为 false。

  • referringVisitId

    string

    引荐来源网址的访问 ID。

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

  • visitId

    string

    此次访问的唯一标识符。

  • visitTime

    数字可选

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

方法

addUrl()

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

通过“链接”过渡类型，向当前历史记录添加网址。

参数

  • 明细

    UrlDetails

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

deleteAll()

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

删除历史记录中的所有项。

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

deleteRange()

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

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

参数

  • 范围

    对象

    • endTime

      number

      在此日期之前添加到历史记录的内容（以自纪元起经过的毫秒数表示）。

    • startTime

      number

      在此日期之后添加到历史记录的内容（以自纪元起经过的毫秒数表示）。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

deleteUrl()

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

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

参数

  • 明细

    UrlDetails

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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

参数

返回

  • Promise<VisitItem[]>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

Promise 
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，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onVisited

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

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

参数

onVisitRemoved

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

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

参数

  • callback

    功能

    callback 参数如下所示：

    (removed: object)=>void

    • 已删除

      对象

      • allHistory

        boolean

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

      • urls

        string[] 可选