chrome.history

说明

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

权限

history

清单

您必须声明“历史记录”权限，以便使用 History API。例如：

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

过渡类型

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

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

过渡类型说明
"typed"用户通过在地址栏中输入网址来访问此页面。也用于其他显式导航操作。另请参阅生成，此选项适用于用户选择看起来不像网址的选项。
“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

    编号（选填）

    此页面的上次加载时间，以从公元纪年开始计算的毫秒数表示。

  • 标题

    字符串（可选）

    上次加载网页时的标题。

  • 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 及更高版本

属性

  • 网址

    字符串

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

VisitItem

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

属性

  • id

    字符串

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

  • isLocal

    布尔值

    Chrome 115 及更高版本

    如果访问源自此设备，则为“true”。如果数据是从其他设备同步过来的，则为 false。

  • referringVisitId

    字符串

    引荐来源网址的访问 ID。

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

  • visitId

    字符串

    此次访问的唯一标识符。

  • visitTime

    编号（选填）

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

方法

addUrl()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

将一个网址添加到当前时间点的历史记录中，过渡类型为“链接”。

参数

  • 详细信息

    UrlDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

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

deleteAll()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.history.deleteAll(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

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

deleteRange()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

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

参数

  • 范围

    对象

    • endTime

      number

      在此日期之前添加到历史记录的项数，以从公元纪年开始计算的毫秒数表示。

    • startTime

      number

      在此日期之后添加到历史记录的内容，以从公元纪年开始计算的毫秒数表示。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

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

deleteUrl()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

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

参数

  • 详细信息

    UrlDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

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

getVisits()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

检索与网址访问相关的信息。

参数

返回

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 及更高版本

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

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.history.search(
  query: object,
  callback?: function,
)

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

参数

  • 查询

    对象

    • endTime

      编号（选填）

      将结果限制为在此日期之前访问过的结果，以从公元纪年开始计算的毫秒数表示。

    • maxResults

      编号（选填）

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

    • startTime

      编号（选填）

      将结果限制为在此日期之后访问的那些结果，以从公元纪年开始计算的毫秒数表示。如果未指定该属性，则默认为 24 小时。

    • text

      字符串

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (results: HistoryItem[]) => void

返回

  • Promise&lt;HistoryItem[]&gt;

    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[] 选填