chrome.history

说明

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

权限

history

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

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

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

概念和用法

过渡类型

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

示例

若要试用此 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，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

deleteAll()

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

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 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，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 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，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getVisits()

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

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

参数

返回

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 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，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 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[] 选填