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 一样。对于已经加载的帧， 启动了新的导航，或者导航操作只有在网络资源配置完毕后才继续进行。 完全加载

一般来说，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 开始，对于 帧的生命周期（在多次导航中）。

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

枚举

"client_redirect"

“server_redirect”

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 及更高版本

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

枚举

“链接”

"typed"

"auto_bookmark"

“auto_subframe”

"manual_subframe"

"generated"

"start_page"

“form_submit”

"重新加载"

"关键字"

"keyword_generated"

方法

getAllFrames()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
)

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

参数

  • 详细信息

    对象

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

    • tabId

      number

      标签页的 ID。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (details?: object[]) => void

    • 详细信息

      object[] 可选

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

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 及更高版本

        文档所处的生命周期。

      • errorOccurred

        布尔值

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

      • frameId

        number

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

      • frameType

        FrameType

        Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

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

      • processId

        number

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

      • 网址

        字符串

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

返回

  • Promise&lt;object[] |未定义>

    Chrome 93 及更高版本

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

getFrame()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
)

检索有关给定帧的信息。框架引用 <iframe>或 <frame>并且通过标签页 ID 和框架 ID 进行标识。

参数

  • 详细信息

    对象

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

    • documentId

      字符串（可选）

      Chrome 106 及更高版本

      文档的 UUID。如果提供了 frameId 和/或 tabId，则将对其进行验证，以与提供的文档 ID 找到的文档匹配。

    • frameId

      编号（选填）

      指定标签页中帧的 ID。

    • processId

      编号（选填）

      <ph type="x-smartling-placeholder"></ph> 自 Chrome 49 起弃用

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

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

    • tabId

      编号（选填）

      帧所在标签页的 ID。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (details?: object) => void

    • 详细信息

      对象（可选）

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

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 及更高版本

        文档所处的生命周期。

      • errorOccurred

        布尔值

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

      • frameType

        FrameType

        Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

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

      • 网址

        字符串

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

返回

  • Promise&lt;object |未定义>

    Chrome 93 及更高版本

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

事件

onBeforeNavigate

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

在导航即将开始时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • Chrome 106 及更高版本

        文档所处的生命周期。

      • frameId

        number

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

      • Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

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

      • processId

        number

        <ph type="x-smartling-placeholder"></ph> 自 Chrome 50 起弃用

        不再为此事件设置 processId，因为在 onCommit 之前，渲染结果文档的进程是未知的。

        -1 的值。

      • tabId

        number

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

      • timeStamp

        number

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

      • 网址

        字符串

  • 过滤条件

    对象（可选）

    • 网址

      events.UrlFilter[]

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

onCommitted

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        文档所处的生命周期。

      • frameId

        number

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

      • Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

        Chrome 74 及更高版本

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

      • processId

        number

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

      • tabId

        number

        发生导航的标签页的 ID。

      • timeStamp

        number

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

      • transitionQualifiers

        TransitionQualifier[]

        过渡限定符列表。

      • transitionType

        TransitionType

        导航的原因。

      • 网址

        字符串

  • 过滤条件

    对象（可选）

    • 网址

      events.UrlFilter[]

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

onCompleted

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        文档所处的生命周期。

      • frameId

        number

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

      • Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

        Chrome 74 及更高版本

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

      • processId

        number

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

      • tabId

        number

        发生导航的标签页的 ID。

      • timeStamp

        number

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

      • 网址

        字符串

  • 过滤条件

    对象（可选）

    • 网址

      events.UrlFilter[]

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

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

        浏览器即将创建新视图的时间（以毫秒为单位，从 Epoch 起算）。

      • 网址

        字符串

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

  • 过滤条件

    对象（可选）

    • 网址

      events.UrlFilter[]

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

onDOMContentLoaded

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        文档所处的生命周期。

      • frameId

        number

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

      • Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

        Chrome 74 及更高版本

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

      • processId

        number

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

      • tabId

        number

        发生导航的标签页的 ID。

      • timeStamp

        number

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

      • 网址

        字符串

  • 过滤条件

    对象（可选）

    • 网址

      events.UrlFilter[]

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

onErrorOccurred

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        文档所处的生命周期。

      • 错误

        字符串

        错误说明。

      • frameId

        number

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

      • Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

        Chrome 74 及更高版本

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

      • processId

        number

        <ph type="x-smartling-placeholder"></ph> 自 Chrome 50 起弃用

        不再为此事件设置 processId。

        -1 的值。

      • tabId

        number

        发生导航的标签页的 ID。

      • timeStamp

        number

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

      • 网址

        字符串

  • 过滤条件

    对象（可选）

    • 网址

      events.UrlFilter[]

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

onHistoryStateUpdated

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        文档所处的生命周期。

      • frameId

        number

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

      • Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

        Chrome 74 及更高版本

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

      • processId

        number

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

      • tabId

        number

        发生导航的标签页的 ID。

      • timeStamp

        number

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

      • transitionQualifiers

        TransitionQualifier[]

        过渡限定符列表。

      • transitionType

        TransitionType

        导航的原因。

      • 网址

        字符串

  • 过滤条件

    对象（可选）

    • 网址

      events.UrlFilter[]

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

onReferenceFragmentUpdated

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

在帧的参考 fragment 更新时触发。该框架今后的所有活动都将使用更新后的网址。

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • documentId

        字符串

        Chrome 106 及更高版本

        已加载文档的 UUID。

      • Chrome 106 及更高版本

        文档所处的生命周期。

      • frameId

        number

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

      • Chrome 106 及更高版本

        导航发生的帧类型。

      • parentDocumentId

        字符串（可选）

        Chrome 106 及更高版本

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

      • parentFrameId

        number

        Chrome 74 及更高版本

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

      • processId

        number

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

      • tabId

        number

        发生导航的标签页的 ID。

      • timeStamp

        number

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

      • transitionQualifiers

        TransitionQualifier[]

        过渡限定符列表。

      • transitionType

        TransitionType

        导航的原因。

      • 网址

        字符串

  • 过滤条件

    对象（可选）

    • 网址

      events.UrlFilter[]

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

onTabReplaced

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

      • replacedTabId

        number

        被替换的标签页的 ID。

      • tabId

        number

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

      • timeStamp

        number

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