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 免安装体验或网页即时看触发的，则完全加载的网页会交换到当前标签页中。在这种情况下，会触发 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 不会改变，因此很难将特定文档中发生的事件仅与 frameIds 联系起来。我们引入了 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 及更高版本

枚举

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 及更高版本

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

枚举

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"start_page"

"form_submit"

"keyword_generated"

方法

getAllFrames()

Promise

chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
)

检索关于指定标签页的所有帧的信息。

参数

• 明细

  对象

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

  • tabId

    number

    标签页的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (details?: object[])=>void

  • 明细

    对象 [] 可选

    给定标签页中的框架列表，如果指定的标签页 ID 无效，则返回 null。

    • documentId

      string

      Chrome 106 及更高版本

      已加载文档的 UUID。

    • documentLifecycle

      DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • errorOccurred

      boolean

      如果此帧中的最后一次导航被错误中断（即触发 onErrorOccurred 事件），则为 true。

    • frameId

      number

      帧的 ID。0 表示这是主帧；正值表示子帧的 ID。

    • frameType

      FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

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

    • processId

      number

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

    • 网址

      string

      当前与此框架相关联的网址。

返回

• Promise<object[]|undefined>

  Chrome 93 及更高版本

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

getFrame()

Promise

chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
)

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

参数

• 明细

  对象

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

  • documentId

    字符串（可选）

    Chrome 106 及更高版本

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

  • frameId

    数字可选

    给定标签页中框架的 ID。

  • processId

    数字可选

    从 Chrome 49 开始已废弃

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

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

  • tabId

    数字可选

    框架所在的标签页的 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (details?: object)=>void

  • 明细

    对象（可选）

    有关所请求框架的信息，如果指定的框架 ID 和/或标签页 ID 无效，则为 null。

    • documentId

      string

      Chrome 106 及更高版本

      已加载文档的 UUID。

    • documentLifecycle

      DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • errorOccurred

      boolean

      如果此帧中的最后一次导航被错误中断（即触发 onErrorOccurred 事件），则为 true。

    • frameType

      FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

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

    • 网址

      string

      当前与此框架相关联的网址（如果由 frameId 标识的框架存在于给定标签页中的某个点）。网址与给定 frameId 相关联并不意味着相应的框架仍然存在。

返回

• Promise<object|undefined>

  Chrome 93 及更高版本

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

活动

onBeforeNavigate

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

在即将进行导航时触发。

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • frameId

      number

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

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

    • processId

      number

      从 Chrome 50 开始已废弃

      不再为此事件设置 processId，因为在 onCommit 之前，呈现所生成文档的进程是未知的。

      -1 的值。

    • tabId

      number

      要在其中进行导航的标签页的 ID。

    • timeStamp

      number

      浏览器即将启动导航的时间（以毫秒为单位，从 Epoch 起算）。

    • 网址

      string

• 过滤条件

  对象（可选）

  • 网址

    events.UrlFilter[]

    要转到的网址必须满足的条件。对于此事件，系统将忽略 UrlFilter 的“schemes”和“ports”字段。

onCommitted

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

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

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • documentId

      string

      Chrome 106 及更高版本

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • frameId

      number

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

      Chrome 74 及更高版本

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

    • processId

      number

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

    • tabId

      number

      在其中进行导航的标签页的 ID。

    • timeStamp

      number

      导航的提交时间，以从公元纪年开始计算的毫秒数表示。

    • transitionQualifiers

      TransitionQualifier[]

      转换限定符列表。

    • transitionType

      TransitionType

      导航的原因。

    • 网址

      string

• 过滤条件

  对象（可选）

  • 网址

    events.UrlFilter[]

    要转到的网址必须满足的条件。对于此事件，系统将忽略 UrlFilter 的“schemes”和“ports”字段。

onCompleted

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

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

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • documentId

      string

      Chrome 106 及更高版本

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • frameId

      number

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

      Chrome 74 及更高版本

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

    • processId

      number

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

    • tabId

      number

      在其中进行导航的标签页的 ID。

    • timeStamp

      number

      文档加载完毕的时间（以毫秒为单位，从 Epoch 起算）。

    • 网址

      string

• 过滤条件

  对象（可选）

  • 网址

    events.UrlFilter[]

    要转到的网址必须满足的条件。对于此事件，系统将忽略 UrlFilter 的“schemes”和“ports”字段。

onCreatedNavigationTarget

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

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

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • sourceFrameId

      number

      使用 sourceTabId 来触发导航的帧的 ID。0 表示主帧。

    • sourceProcessId

      number

      为源帧运行渲染程序的进程的 ID。

    • sourceTabId

      number

      在其中触发导航的标签页的 ID。

    • tabId

      number

      打开网址的标签页的 ID

    • timeStamp

      number

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

    • 网址

      string

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

• 过滤条件

  对象（可选）

  • 网址

    events.UrlFilter[]

    要转到的网址必须满足的条件。对于此事件，系统将忽略 UrlFilter 的“schemes”和“ports”字段。

onDOMContentLoaded

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

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

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • documentId

      string

      Chrome 106 及更高版本

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • frameId

      number

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

      Chrome 74 及更高版本

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

    • processId

      number

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

    • tabId

      number

      在其中进行导航的标签页的 ID。

    • timeStamp

      number

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

    • 网址

      string

• 过滤条件

  对象（可选）

  • 网址

    events.UrlFilter[]

    要转到的网址必须满足的条件。对于此事件，系统将忽略 UrlFilter 的“schemes”和“ports”字段。

onErrorOccurred

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

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

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • documentId

      string

      Chrome 106 及更高版本

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • error

      string

      错误说明。

    • frameId

      number

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

      Chrome 74 及更高版本

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

    • processId

      number

      从 Chrome 50 开始已废弃

      不再为此事件设置 processId。

      -1 的值。

    • tabId

      number

      在其中进行导航的标签页的 ID。

    • timeStamp

      number

      错误发生的时间，以从公元纪年开始计算的毫秒数表示。

    • 网址

      string

• 过滤条件

  对象（可选）

  • 网址

    events.UrlFilter[]

    要转到的网址必须满足的条件。对于此事件，系统将忽略 UrlFilter 的“schemes”和“ports”字段。

onHistoryStateUpdated

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

在框架的历史记录更新为新网址时触发。该框架的所有将来事件都将使用更新后的网址。

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • documentId

      string

      Chrome 106 及更高版本

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • frameId

      number

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

      Chrome 74 及更高版本

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

    • processId

      number

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

    • tabId

      number

      在其中进行导航的标签页的 ID。

    • timeStamp

      number

      导航的提交时间，以从公元纪年开始计算的毫秒数表示。

    • transitionQualifiers

      TransitionQualifier[]

      转换限定符列表。

    • transitionType

      TransitionType

      导航的原因。

    • 网址

      string

• 过滤条件

  对象（可选）

  • 网址

    events.UrlFilter[]

    要转到的网址必须满足的条件。对于此事件，系统将忽略 UrlFilter 的“schemes”和“ports”字段。

onReferenceFragmentUpdated

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

在帧的引用片段更新时触发。该框架的所有将来事件都将使用更新后的网址。

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • documentId

      string

      Chrome 106 及更高版本

      已加载文档的 UUID。

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106 及更高版本

      文档所在的生命周期。

    • frameId

      number

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

    • frameType

      extensionTypes.FrameType

      Chrome 106 及更高版本

      发生导航的帧类型。

    • parentDocumentId

      字符串（可选）

      Chrome 106 及更高版本

      拥有此帧的父文档的 UUID。如果没有父级，则不设置此项。

    • parentFrameId

      number

      Chrome 74 及更高版本

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

    • processId

      number

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

    • tabId

      number

      在其中进行导航的标签页的 ID。

    • timeStamp

      number

      导航的提交时间，以从公元纪年开始计算的毫秒数表示。

    • transitionQualifiers

      TransitionQualifier[]

      转换限定符列表。

    • transitionType

      TransitionType

      导航的原因。

    • 网址

      string

• 过滤条件

  对象（可选）

  • 网址

    events.UrlFilter[]

    要转到的网址必须满足的条件。对于此事件，系统将忽略 UrlFilter 的“schemes”和“ports”字段。

onTabReplaced

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

标签页内容被其他（通常是预先呈现的）标签页替换时触发。

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • replacedTabId

      number

      被替换的标签页的 ID。

    • tabId

      number

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

    • timeStamp

      number

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