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 键区分。

另请注意,在临时加载期间,该过程可能会多次切换。这种情况会发生 在加载被重定向到其他网站时触发在这种情况下,您将收到 onBeforeNavigateonErrorOccurred 事件,直到您收到最终的 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
        Chrome 106 及更高版本

        文档所处的生命周期。

      • errorOccurred

        布尔值

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

      • frameId

        number

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

      • 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
        Chrome 106 及更高版本

        文档所处的生命周期。

      • errorOccurred

        布尔值

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

      • 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 起算)。

      • 网址

        字符串

  • 过滤条件

    对象(可选

    • 网址

      要导航到的网址必须满足的条件。“架构”和“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

        过渡限定符列表。

      • transitionType

        导航的原因。

      • 网址

        字符串

  • 过滤条件

    对象(可选

    • 网址

      要导航到的网址必须满足的条件。“架构”和“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 起算)。

      • 网址

        字符串

  • 过滤条件

    对象(可选

    • 网址

      要导航到的网址必须满足的条件。“架构”和“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 起算)。

      • 网址

        字符串

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

  • 过滤条件

    对象(可选

    • 网址

      要导航到的网址必须满足的条件。“架构”和“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 起算)。

      • 网址

        字符串

  • 过滤条件

    对象(可选

    • 网址

      要导航到的网址必须满足的条件。“架构”和“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

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

      • 网址

        字符串

  • 过滤条件

    对象(可选

    • 网址

      要导航到的网址必须满足的条件。“架构”和“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

        过渡限定符列表。

      • transitionType

        导航的原因。

      • 网址

        字符串

  • 过滤条件

    对象(可选

    • 网址

      要导航到的网址必须满足的条件。“架构”和“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

        过渡限定符列表。

      • transitionType

        导航的原因。

      • 网址

        字符串

  • 过滤条件

    对象(可选

    • 网址

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

onTabReplaced

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

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

参数

  • callback

    函数

    callback 参数如下所示:

    (details: object) => void

    • 详细信息

      对象

      • replacedTabId

        number

        被替换的标签页的 ID。

      • tabId

        number

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

      • timeStamp

        number

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