chrome.webNavigation

说明

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

权限

webNavigation

所有 chrome.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 Instant 或 Instant Pages 触发的，则会将完全加载的网页替换到当前标签页中。在这种情况下，系统会触发 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 事件）为止。换句话说，可能会有多个具有相同 frameId 的待处理 webNavigation 事件序列。可以通过 processId 键区分序列。

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

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

过渡类型和限定符

webNavigation onCommitted 事件具有 transitionType 和 transitionQualifiers 属性。过渡类型与 History API 中使用的类型相同，用于描述浏览器如何导航到此特定网址。此外，还可以返回多个进一步定义导航的过渡限定符。

存在以下过渡限定符：

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

示例

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

类型

TransitionQualifier

Chrome 44 及更高版本

枚举

"client_redirect"

“server_redirect”

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 及更高版本

导航的原因。使用与 History API 中定义的相同的过渡类型。这些过渡类型与历史记录 API 中定义的过渡类型相同，只是将 "auto_toplevel" 替换为 "start_page"（为了实现向后兼容性）。

枚举

“链接”

“已输入”

"auto_bookmark"

“auto_subframe”

"manual_subframe"

"generated"

“start_page”

“form_submit”

“重新加载”

“关键字”

"keyword_generated"

方法

getAllFrames()

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

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

参数

  • 详细信息

    对象

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

    • tabId

      数值

      标签页的 ID。

返回

  • Promise<object[] | undefined>

    Chrome 93 及更高版本

getFrame()

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

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

参数

  • 详细信息

    对象

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

    • documentId

      字符串（选填）

      Chrome 106 及更高版本

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

    • frameId

      number 可选

      指定标签页中框架的 ID。

    • processId

      number 可选

      自 Chrome 49 起已弃用

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

      运行相应标签页的渲染器的进程的 ID。

    • tabId

      number 可选

      相应框架所在的标签页的 ID。

返回

  • Promise<object | undefined>

    Chrome 93 及更高版本

事件

onBeforeNavigate

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

在即将发生导航时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • Chrome 106 及更高版本

        相应文档所处的生命周期。

      • frameId

        数值

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

      • Chrome 106 及更高版本

        发生导航的框架的类型。

      • parentDocumentId

        字符串（选填）

        Chrome 106 及更高版本

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

      • parentFrameId

        数值

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

      • processId

        数值

        自 Chrome 50 起已弃用

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

        值为 -1。

      • tabId

        数值

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

      • timeStamp

        数值

        浏览器即将开始导航的时间，以自纪元以来的毫秒数表示。

      • 网址

        字符串

  • 过滤器

    对象（可选）

    • 网址

      events.UrlFilter[]

      正在导航到的网址必须满足的条件。对于此事件，系统会忽略 UrlFilter 的“schemes”和“ports”字段。

onCommitted

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        相应文档所处的生命周期。

      • frameId

        数值

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

      • Chrome 106 及更高版本

        发生导航的框架的类型。

      • parentDocumentId

        字符串（选填）

        Chrome 106 及更高版本

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

      • parentFrameId

        数值

        Chrome 74 及更高版本

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

      • processId

        数值

        运行相应帧的渲染器的进程的 ID。

      • tabId

        数值

        发生导航的标签页的 ID。

      • timeStamp

        数值

        导航提交的时间，以自纪元以来的毫秒数表示。

      • transitionQualifiers

        TransitionQualifier[]

        转换限定符的列表。

      • transitionType

        TransitionType

        导航的原因。

      • 网址

        字符串

  • 过滤器

    对象（可选）

    • 网址

      events.UrlFilter[]

      正在导航到的网址必须满足的条件。对于此事件，系统会忽略 UrlFilter 的“schemes”和“ports”字段。

onCompleted

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        相应文档所处的生命周期。

      • frameId

        数值

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

      • Chrome 106 及更高版本

        发生导航的框架的类型。

      • parentDocumentId

        字符串（选填）

        Chrome 106 及更高版本

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

      • parentFrameId

        数值

        Chrome 74 及更高版本

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

      • processId

        数值

        运行相应帧的渲染器的进程的 ID。

      • tabId

        数值

        发生导航的标签页的 ID。

      • timeStamp

        数值

        文档完成加载的时间，以自纪元以来的毫秒数表示。

      • 网址

        字符串

  • 过滤器

    对象（可选）

    • 网址

      events.UrlFilter[]

      正在导航到的网址必须满足的条件。对于此事件，系统会忽略 UrlFilter 的“schemes”和“ports”字段。

onCreatedNavigationTarget

chrome.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[]

      正在导航到的网址必须满足的条件。对于此事件，系统会忽略 UrlFilter 的“schemes”和“ports”字段。

onDOMContentLoaded

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        相应文档所处的生命周期。

      • frameId

        数值

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

      • Chrome 106 及更高版本

        发生导航的框架的类型。

      • parentDocumentId

        字符串（选填）

        Chrome 106 及更高版本

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

      • parentFrameId

        数值

        Chrome 74 及更高版本

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

      • processId

        数值

        运行相应帧的渲染器的进程的 ID。

      • tabId

        数值

        发生导航的标签页的 ID。

      • timeStamp

        数值

        网页的 DOM 完全构建的时间，以自纪元以来的毫秒数表示。

      • 网址

        字符串

  • 过滤器

    对象（可选）

    • 网址

      events.UrlFilter[]

      正在导航到的网址必须满足的条件。对于此事件，系统会忽略 UrlFilter 的“schemes”和“ports”字段。

onErrorOccurred

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

在发生错误并中止导航时触发。如果发生网络错误或用户中止了导航，则可能会出现这种情况。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        相应文档所处的生命周期。

      • 错误

        字符串

        错误说明。

      • frameId

        数值

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

      • Chrome 106 及更高版本

        发生导航的框架的类型。

      • parentDocumentId

        字符串（选填）

        Chrome 106 及更高版本

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

      • parentFrameId

        数值

        Chrome 74 及更高版本

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

      • processId

        数值

        自 Chrome 50 起已弃用

        此事件不再设置 processId。

        值为 -1。

      • tabId

        数值

        发生导航的标签页的 ID。

      • timeStamp

        数值

        发生错误的时间，以自纪元以来的毫秒数表示。

      • 网址

        字符串

  • 过滤器

    对象（可选）

    • 网址

      events.UrlFilter[]

      正在导航到的网址必须满足的条件。对于此事件，系统会忽略 UrlFilter 的“schemes”和“ports”字段。

onHistoryStateUpdated

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

当帧的历史记录更新为新网址时触发。相应框架的所有未来事件都将使用更新后的网址。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        相应文档所处的生命周期。

      • frameId

        数值

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

      • Chrome 106 及更高版本

        发生导航的框架的类型。

      • parentDocumentId

        字符串（选填）

        Chrome 106 及更高版本

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

      • parentFrameId

        数值

        Chrome 74 及更高版本

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

      • processId

        数值

        运行相应帧的渲染器的进程的 ID。

      • tabId

        数值

        发生导航的标签页的 ID。

      • timeStamp

        数值

        导航提交的时间，以自纪元以来的毫秒数表示。

      • transitionQualifiers

        TransitionQualifier[]

        转换限定符的列表。

      • transitionType

        TransitionType

        导航的原因。

      • 网址

        字符串

  • 过滤器

    对象（可选）

    • 网址

      events.UrlFilter[]

      正在导航到的网址必须满足的条件。对于此事件，系统会忽略 UrlFilter 的“schemes”和“ports”字段。

onReferenceFragmentUpdated

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

在帧的引用 fragment 更新时触发。相应框架的所有未来事件都将使用更新后的网址。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        相应文档所处的生命周期。

      • frameId

        数值

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

      • Chrome 106 及更高版本

        发生导航的框架的类型。

      • parentDocumentId

        字符串（选填）

        Chrome 106 及更高版本

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

      • parentFrameId

        数值

        Chrome 74 及更高版本

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

      • processId

        数值

        运行相应帧的渲染器的进程的 ID。

      • tabId

        数值

        发生导航的标签页的 ID。

      • timeStamp

        数值

        导航提交的时间，以自纪元以来的毫秒数表示。

      • transitionQualifiers

        TransitionQualifier[]

        转换限定符的列表。

      • transitionType

        TransitionType

        导航的原因。

      • 网址

        字符串

  • 过滤器

    对象（可选）

    • 网址

      events.UrlFilter[]

      正在导航到的网址必须满足的条件。对于此事件，系统会忽略 UrlFilter 的“schemes”和“ports”字段。

onTabReplaced

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • replacedTabId

        数值

        被替换的标签页的 ID。

      • tabId

        数值

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

      • timeStamp

        数值

        替换发生的时间，以自纪元以来的毫秒数表示。