browser.webNavigation

说明

使用 chrome.webNavigation API 接收有关正在进行的导航请求状态的通知。

权限

webNavigation

所有 browser.webNavigation 方法和事件都要求您在扩展程序清单中声明 "webNavigation" 权限。例如：

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

概念和用法

活动顺序

对于成功完成的导航，事件会按以下顺序触发：

onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted

在此过程中发生的任何错误都会导致 onErrorOccurred 事件。对于特定导航，在 onErrorOccurred 之后不会再触发任何事件。

如果导航框架包含子框架，则其 onCommitted 会在其任何子框架的 onBeforeNavigate 之前触发；而 onCompleted 会在其所有子框架的 onCompleted 之后触发。

如果帧的引用 fragment 发生更改，则会触发 onReferenceFragmentUpdated 事件。此事件可在 onDOMContentLoaded 之后的任何时间触发，甚至可在 onCompleted 之后触发。

如果使用 history API 修改框架的状态（例如使用 history.pushState()），则会触发 onHistoryStateUpdated 事件。此事件可在 onDOMContentLoaded 之后的任何时间触发。

如果导航从往返缓存中恢复了网页，则不会触发 onDOMContentLoaded 事件。由于内容在首次访问页面时已完成加载，因此不会触发该事件。

如果导航是使用 Chrome 即搜即得 或即时网页触发的，则系统会将完全加载的网页换入当前标签页。在这种情况下，系统会触发 onTabReplaced 事件。

与 webRequest 事件的关系

webRequest API 的事件与 webNavigation API 的事件之间没有定义的顺序。对于已开始新导航的框架，可能仍会收到 webRequest 事件，或者只有在网络资源已完全加载后，导航才会继续。

一般来说，webNavigation 事件与界面中显示的导航状态密切相关，而 webRequest 事件则对应于网络栈的状态，而网络栈通常对用户不透明。

标签页 ID

并非所有导航标签页都对应于 Chrome 界面中的实际标签页，例如正在预渲染的标签页。此类标签页无法使用 tabs API 访问，您也无法通过调用 webNavigation.getFrame() 或 webNavigation.getAllFrames() 请求有关这些标签页的信息。此类标签页换入后，系统会触发 onTabReplaced 事件，并且这些标签页可通过这些 API 访问。

时间戳

请务必注意，操作系统在处理不同 Chrome 进程时存在一些技术上的异常，这可能会导致浏览器本身与扩展程序进程之间的时钟出现偏差。这意味着，WebNavigation 事件 timeStamp 属性的 timeStamp 属性只能保证内部一致性。将一个事件与另一个事件进行比较，可以得出它们之间的正确偏移量，但将它们与扩展程序内的当前时间进行比较（例如，使用 (new Date()).getTime()）可能会产生意外结果。

框架 ID

标签页中的框架可通过框架 ID 进行标识。主框架的框架 ID 始终为 0，子框架的 ID 为正数。在框架中构建文档后，其框架 ID 在文档的生命周期内保持不变。从 Chrome 49 开始，此 ID 在框架的生命周期内（跨多个导航）也保持不变。

由于 Chrome 具有多进程特性，标签页可能会使用不同的进程来呈现网页的来源和目标。因此，如果导航发生在新进程中，您可能会同时收到来自新页面和旧页面的事件，直到新导航提交（即针对新主框架发送 onCommitted 事件）。换句话说，可能有多个待处理的 webNavigation 事件序列具有相同的 frameId。这些序列可以通过 processId 键进行区分。

另请注意，在临时加载期间，进程可能会切换多次。当负载重定向到其他网站时，就会发生这种情况。在这种情况下，您将收到重复的 onBeforeNavigate 和 onErrorOccurred 事件，直到您收到最终的 onCommitted 事件。

扩展程序的另一个问题是框架的生命周期。框架托管文档（与已提交的网址相关联）。 文档可能会发生变化（例如通过导航），但 frameId 不会发生变化，因此很难仅通过 frameId 将特定文档中发生的事情关联起来。我们引入了 documentId 的概念，它是每个文档的唯一标识符。如果框架被导航并打开新文档，则标识符会发生变化。此字段有助于确定网页何时更改其生命周期状态（在预渲染/活跃/缓存之间），因为它保持不变。

过渡类型和限定符

webNavigation onCommitted 事件具有 transitionType 和 transitionQualifiers 属性。transition type 与 history API 中使用的类型相同，用于描述浏览器如何导航到此特定网址。此外，系统还会返回多个转换限定符，用于进一步定义导航。

存在以下转换限定符：

转换限定符	说明
"client_redirect"	在导航期间，页面上的 JavaScript 或元刷新标记导致了一次或多次重定向。
"server_redirect"	在导航期间，发生了由服务器发送的 HTTP 标头引起的一个或多个重定向。
"forward_back"	用户使用“前进”或“返回按钮”发起了导航。
"from_address_bar"	用户从地址栏（也称为多功能框）发起了导航。

示例

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

类型

TransitionQualifier

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

枚举

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

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

导航的原因。使用与 History API 中定义的相同的过渡类型。这些过渡类型与 History API 中定义的过渡类型相同，只是用 "start_page" 代替了 "auto_toplevel"（为了向后兼容）。

枚举

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

方法

getAllFrames()

browser.webNavigation.getAllFrames(
  details: object,
): Promise<object[] | undefined>

检索给定标签页的所有框架的相关信息。

参数

• 详细信息

  对象

  要从中检索所有框架的标签页的相关信息。

  • tabId

    数值

    标签页的 ID。

返回

• Promise<object[] | undefined>

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

getFrame()

browser.webNavigation.getFrame(
  details: object,
): Promise<object | undefined>

检索有关给定帧的信息。框架是指网页的 <iframe> 或 <frame>，由标签页 ID 和框架 ID 标识。

参数

• 详细信息

  对象

  要检索其相关信息的帧的相关信息。

  • documentId

    字符串 可选

    Chrome 106+ browser.*（自 Chrome 148 起）

    文档的 UUID。如果提供了 frameId 和/或 tabId，系统会验证它们是否与通过提供的文档 ID 找到的文档匹配。

  • frameId

    number 可选

    给定标签页中框架的 ID。

  • processId

    number 可选

    自 Chrome 49 起已弃用

    现在，框架由其标签页 ID 和框架 ID 唯一标识；不再需要进程 ID，因此会被忽略。

    为此标签页运行渲染器的进程的 ID。

  • tabId

    number 可选

    框架所在标签页的 ID。

返回

• Promise<object | undefined>

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

事件

onBeforeNavigate

browser.webNavigation.onBeforeNavigate.addListener(
  callback: function,
  filters?: object,
)

在即将发生导航时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+ browser.*（自 Chrome 148 起）

      文档所处的生命周期。

    • frameId

      数值

      0 表示导航发生在标签页内容窗口中；正值表示导航发生在子框架中。框架 ID 对于给定的标签页和进程是唯一的。

    • frameType

      extensionTypes.FrameType

      Chrome 106+ browser.*（自 Chrome 148 起）

      发生导航的框架类型。

    • parentDocumentId

      字符串 可选

      Chrome 106+ browser.*（自 Chrome 148 起）

      拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

    • parentFrameId

      数值

      父级框架的 ID；如果这是主框架，则为 -1。

    • processId

      数值

      自 Chrome 50 起已弃用

      系统不再为此事件设置 processId，因为在 onCommit 之前，无法知道将呈现结果文档的进程。

      值为 -1。

    • tabId

      数值

      即将发生导航的标签页的 ID。

    • timeStamp

      数值

      浏览器即将开始导航的时间（以毫秒为单位，从纪元算起）。

    • 网址

      字符串

• 过滤器

  对象（可选）

  • 网址

    events.UrlFilter[]

    所导航到的网址必须满足的条件。

onCommitted

browser.webNavigation.onCommitted.addListener(
  callback: function,
  filters?: object,
)

在导航提交时触发。文档（及其引用的资源，例如图片和子框架）可能仍在下载中，但浏览器已从服务器收到文档的至少一部分，并决定切换到新文档。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • documentId

      字符串

      Chrome 106+ browser.*（自 Chrome 148 起）

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+ browser.*（自 Chrome 148 起）

      文档所处的生命周期。

    • frameId

      数值

      0 表示导航发生在标签页内容窗口中；正值表示导航发生在子框架中。框架 ID 在标签页中是唯一的。

    • frameType

      extensionTypes.FrameType

      Chrome 106+ browser.*（自 Chrome 148 起）

      发生导航的框架类型。

    • parentDocumentId

      字符串 可选

      Chrome 106+ browser.*（自 Chrome 148 起）

      拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

    • parentFrameId

      数值

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

      父级框架的 ID；如果这是主框架，则为 -1。

    • processId

      数值

      为此帧运行渲染器的进程的 ID。

    • tabId

      数值

      发生导航的标签页的 ID。

    • timeStamp

      数值

      导航提交时间（以毫秒为单位，从 Epoch 算起）。

    • transitionQualifiers

      TransitionQualifier[]

      转换限定符列表。

    • transitionType

      TransitionType

      导航的原因。

    • 网址

      字符串

• 过滤器

  对象（可选）

  • 网址

    events.UrlFilter[]

    所导航到的网址必须满足的条件。

onCompleted

browser.webNavigation.onCompleted.addListener(
  callback: function,
  filters?: object,
)

在文档（包括其引用的资源）完全加载并初始化后触发。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • documentId

      字符串

      Chrome 106+ browser.*（自 Chrome 148 起）

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+ browser.*（自 Chrome 148 起）

      文档所处的生命周期。

    • frameId

      数值

      0 表示导航发生在标签页内容窗口中；正值表示导航发生在子框架中。框架 ID 在标签页中是唯一的。

    • frameType

      extensionTypes.FrameType

      Chrome 106+ browser.*（自 Chrome 148 起）

      发生导航的框架类型。

    • parentDocumentId

      字符串 可选

      Chrome 106+ browser.*（自 Chrome 148 起）

      拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

    • parentFrameId

      数值

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

      父级框架的 ID；如果这是主框架，则为 -1。

    • processId

      数值

      为此帧运行渲染器的进程的 ID。

    • tabId

      数值

      发生导航的标签页的 ID。

    • timeStamp

      数值

      文档加载完成的时间（自纪元开始算起，以毫秒为单位）。

    • 网址

      字符串

• 过滤器

  对象（可选）

  • 网址

    events.UrlFilter[]

    所导航到的网址必须满足的条件。

onCreatedNavigationTarget

browser.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

在创建新窗口或现有窗口中的新标签页以托管导航时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • sourceFrameId

      数值

      触发导航的框架（具有 sourceTabId）的 ID。0 表示主框架。

    • sourceProcessId

      数值

      运行源框架渲染程序的进程的 ID。

    • sourceTabId

      数值

      触发导航的标签页的 ID。

    • tabId

      数值

      打开网址的标签页的 ID

    • timeStamp

      数值

      浏览器即将创建新视图的时间（以自纪元以来的毫秒数表示）。

    • 网址

      字符串

      要在新窗口中打开的网址。

• 过滤器

  对象（可选）

  • 网址

    events.UrlFilter[]

    所导航到的网址必须满足的条件。

onDOMContentLoaded

browser.webNavigation.onDOMContentLoaded.addListener(
  callback: function,
  filters?: object,
)

在网页的 DOM 完全构建完毕时触发，但引用的资源可能尚未完成加载。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • documentId

      字符串

      Chrome 106+ browser.*（自 Chrome 148 起）

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+ browser.*（自 Chrome 148 起）

      文档所处的生命周期。

    • frameId

      数值

      0 表示导航发生在标签页内容窗口中；正值表示导航发生在子框架中。框架 ID 在标签页中是唯一的。

    • frameType

      extensionTypes.FrameType

      Chrome 106+ browser.*（自 Chrome 148 起）

      发生导航的框架类型。

    • parentDocumentId

      字符串 可选

      Chrome 106+ browser.*（自 Chrome 148 起）

      拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

    • parentFrameId

      数值

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

      父级框架的 ID；如果这是主框架，则为 -1。

    • processId

      数值

      为此帧运行渲染器的进程的 ID。

    • tabId

      数值

      发生导航的标签页的 ID。

    • timeStamp

      数值

      网页 DOM 完全构建完成的时间（以毫秒为单位，从纪元时间算起）。

    • 网址

      字符串

• 过滤器

  对象（可选）

  • 网址

    events.UrlFilter[]

    所导航到的网址必须满足的条件。

onErrorOccurred

browser.webNavigation.onErrorOccurred.addListener(
  callback: function,
  filters?: object,
)

在发生错误且导航中止时触发。如果发生网络连接错误或用户中止了导航，就可能会发生这种情况。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • documentId

      字符串

      Chrome 106+ browser.*（自 Chrome 148 起）

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+ browser.*（自 Chrome 148 起）

      文档所处的生命周期。

    • 错误

      字符串

      错误说明。

    • frameId

      数值

      0 表示导航发生在标签页内容窗口中；正值表示导航发生在子框架中。框架 ID 在标签页中是唯一的。

    • frameType

      extensionTypes.FrameType

      Chrome 106+ browser.*（自 Chrome 148 起）

      发生导航的框架类型。

    • parentDocumentId

      字符串 可选

      Chrome 106+ browser.*（自 Chrome 148 起）

      拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

    • parentFrameId

      数值

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

      父级框架的 ID；如果这是主框架，则为 -1。

    • processId

      数值

      自 Chrome 50 起已弃用

      此事件不再设置 processId。

      值为 -1。

    • tabId

      数值

      发生导航的标签页的 ID。

    • timeStamp

      数值

      错误发生的时间（以毫秒为单位，从 Epoch 算起）。

    • 网址

      字符串

• 过滤器

  对象（可选）

  • 网址

    events.UrlFilter[]

    所导航到的网址必须满足的条件。

onHistoryStateUpdated

browser.webNavigation.onHistoryStateUpdated.addListener(
  callback: function,
  filters?: object,
)

当框架的历史记录更新为新网址时触发。该相框的所有后续活动都将使用更新后的网址。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • documentId

      字符串

      Chrome 106+ browser.*（自 Chrome 148 起）

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+ browser.*（自 Chrome 148 起）

      文档所处的生命周期。

    • frameId

      数值

      0 表示导航发生在标签页内容窗口中；正值表示导航发生在子框架中。框架 ID 在标签页中是唯一的。

    • frameType

      extensionTypes.FrameType

      Chrome 106+ browser.*（自 Chrome 148 起）

      发生导航的框架类型。

    • parentDocumentId

      字符串 可选

      Chrome 106+ browser.*（自 Chrome 148 起）

      拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

    • parentFrameId

      数值

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

      父级框架的 ID；如果这是主框架，则为 -1。

    • processId

      数值

      为此帧运行渲染器的进程的 ID。

    • tabId

      数值

      发生导航的标签页的 ID。

    • timeStamp

      数值

      导航提交时间（以毫秒为单位，从 Epoch 算起）。

    • transitionQualifiers

      TransitionQualifier[]

      转换限定符列表。

    • transitionType

      TransitionType

      导航的原因。

    • 网址

      字符串

• 过滤器

  对象（可选）

  • 网址

    events.UrlFilter[]

    所导航到的网址必须满足的条件。

onReferenceFragmentUpdated

browser.webNavigation.onReferenceFragmentUpdated.addListener(
  callback: function,
  filters?: object,
)

在帧的参考片段更新时触发。该相框的所有后续活动都将使用更新后的网址。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • documentId

      字符串

      Chrome 106+ browser.*（自 Chrome 148 起）

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+ browser.*（自 Chrome 148 起）

      文档所处的生命周期。

    • frameId

      数值

      0 表示导航发生在标签页内容窗口中；正值表示导航发生在子框架中。框架 ID 在标签页中是唯一的。

    • frameType

      extensionTypes.FrameType

      Chrome 106+ browser.*（自 Chrome 148 起）

      发生导航的框架类型。

    • parentDocumentId

      字符串 可选

      Chrome 106+ browser.*（自 Chrome 148 起）

      拥有此框架的父级文档的 UUID。如果没有父级，则不设置此字段。

    • parentFrameId

      数值

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

      父级框架的 ID；如果这是主框架，则为 -1。

    • processId

      数值

      为此帧运行渲染器的进程的 ID。

    • tabId

      数值

      发生导航的标签页的 ID。

    • timeStamp

      数值

      导航提交时间（以毫秒为单位，从 Epoch 算起）。

    • transitionQualifiers

      TransitionQualifier[]

      转换限定符列表。

    • transitionType

      TransitionType

      导航的原因。

    • 网址

      字符串

• 过滤器

  对象（可选）

  • 网址

    events.UrlFilter[]

    所导航到的网址必须满足的条件。

onTabReplaced

browser.webNavigation.onTabReplaced.addListener(
  callback: function,
)

当标签页的内容被其他（通常是之前预渲染的）标签页替换时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • replacedTabId

      数值

      被替换的标签页的 ID。

    • tabId

      数值

      替换旧标签页的新标签页的 ID。

    • timeStamp

      数值

      替换发生的时间（以毫秒为单位，从 Epoch 算起）。