说明
使用 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 属性只能保证在内部
保持一致。将一个事件与另一个事件进行比较，可以得出事件之间的正确偏移量，
将其与扩展程序中的当前时间进行比较（例如，通过 (new Date()).getTime()）
都可能会出现意外结果
帧 ID
标签页中的帧可以通过帧 ID 进行标识。主框架的框架 ID 始终为 0， 子帧的 ID 是一个正数。在框架中构建文档后，其框架 ID 保持不变。从 Chrome 49 开始，对于 帧的生命周期（在多次导航中）。
由于 Chrome 具有多进程特性，因此一个标签页可能会使用不同的进程来呈现源代码
和目标网页。因此，如果导航在新进程中进行，您可能
同时从新页面和旧页面接收事件，直到提交新导航（即
系统会针对新的主框架发送 onCommitted 事件）。换言之，
多个具有相同 frameId 的待处理 webNavigation 事件序列。序列可以是
以 processId 键区分。
另请注意，在临时加载期间，该过程可能会多次切换。这种情况会发生
在加载被重定向到其他网站时触发在这种情况下，您将收到
onBeforeNavigate 和 onErrorOccurred 事件，直到您收到最终的 onCommitted 事件为止。
扩展程序存在问题的另一个概念是 帧。框架托管一个文档（该文档与提交的网址相关联）。 文档可以更改（例如通过导航），但 frameId 不会，因此它 难以将特定文档中发生的事情与 frameIds 中。我们引入了 documentId 的概念 每个文档的唯一标识符。如果某个帧已导航并打开一个 新文档，标识符会随之更改。此字段有助于确定 当页面更改其生命周期状态（在预渲染/活跃/缓存之间）时触发 因为它保持不变
过渡类型和限定符
webNavigation API 的 onCommitted 事件有一个 transitionType 和一个 transitionQualifiers
属性。过渡类型与 history API 中使用的相同，用于描述
浏览器导航到了此特定网址。此外，您可以使用多个过渡限定符，
以进一步定义导航。
存在以下过渡限定符：
| “过渡”限定符 | 说明 |
|---|---|
| “client_redirect” | 由网页上的 JavaScript 或元刷新标记引起的一个或多个重定向在导航过程中发生。 |
| “server_redirect” | 从服务器发送的 HTTP 标头引起的一个或多个重定向在导航期间发生。 |
| “forward_back” | 用户使用“前进”或“后退”按钮启动导航。 |
| "from_address_bar" | 用户从地址栏（也称为多功能框）启动导航。 |
示例
若要试用此 API，请安装 chrome-extension-samples 中的 webNavigation API 示例 存储库
类型
TransitionQualifier
枚举
"client_redirect"
“server_redirect”
"forward_back"
"from_address_bar"
TransitionType
导航的原因。所用的转换类型与历史记录 API 中定义的转换类型相同。这些过渡类型与 history API 中定义的相同，但使用 "start_page" 代替 "auto_toplevel"（以实现向后兼容性）。
枚举
“链接”
"typed"
"auto_bookmark"
“auto_subframe”
"manual_subframe"
"generated"
"start_page"
“form_submit”
"重新加载"
"关键字"
"keyword_generated"
方法
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
检索有关给定标签页的所有帧的信息。
参数
-
详细信息
对象
要从中检索所有帧的标签页的相关信息。
-
tabId
number
标签页的 ID。
-
-
callback
函数（可选）
callback参数如下所示：(details?: object[]) => void
-
详细信息
object[] 可选
指定标签页中的帧列表，如果指定的标签页 ID 无效，则返回 null。
-
documentId
字符串
Chrome 106 及更高版本已加载文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
errorOccurred
布尔值
如果此帧中的最后一次导航因错误而中断，即 onErrorOccurred 事件被触发，则为 true。
-
frameId
number
帧的 ID。0 表示这是主帧；正值表示子框架的 ID。
-
frameTypeChrome 106 及更高版本
导航发生的帧类型。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此框架的父文档的 UUID。如果没有父级，则不会设置此字段。
-
parentFrameId
number
父框架的 ID，如果这是主框架，则为
-1。 -
processId
number
为此帧运行渲染程序的进程的 ID。
-
网址
字符串
当前与此框架相关联的网址。
-
-
返回
-
Promise<object[] |未定义>
Chrome 93 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
getFrame()
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。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
errorOccurred
布尔值
如果此帧中的最后一次导航因错误而中断，即 onErrorOccurred 事件被触发，则为 true。
-
frameTypeChrome 106 及更高版本
导航发生的帧类型。
-
parentDocumentId
字符串（可选）
Chrome 106 及更高版本拥有此框架的父文档的 UUID。如果没有父级，则不会设置此字段。
-
parentFrameId
number
父框架的 ID，如果这是主框架，则为
-1。 -
网址
字符串
当前与此框架关联的网址（如果由 frameId 标识的框架存在于指定标签页中的某个点）。网址与给定 frameId 相关联并不表示对应的框架仍然存在。
-
-
返回
-
Promise<object |未定义>
Chrome 93 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
事件
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
在导航即将开始时触发。
参数
-
函数
callback参数如下所示：(details: object) => void
-
对象
-
Chrome 106 及更高版本
文档所处的生命周期。
-
number
0 表示导航发生在标签页内容窗口中；正值表示在子框架中导航。帧 ID 对于给定标签页和进程而言是唯一的。
-
Chrome 106 及更高版本
导航发生的帧类型。
-
字符串（可选）
Chrome 106 及更高版本拥有此框架的父文档的 UUID。如果没有父级，则不会设置此字段。
-
number
父框架的 ID，如果这是主框架，则为
-1。 -
number
<ph type="x-smartling-placeholder"></ph> 自 Chrome 50 起弃用不再为此事件设置 processId，因为在 onCommit 之前，渲染结果文档的进程是未知的。
-1 的值。
-
number
即将在其中进行导航的标签页的 ID。
-
number
浏览器即将开始导航的时间（以毫秒为单位，从 Epoch 起算）。
-
字符串
-
-
-
对象（可选）
-
要导航到的网址必须满足的条件。“架构”和“ports”对于此事件，系统会忽略 UrlFilter 的字段。
-
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
在提交导航时触发。文档（及其引用的资源）可能仍在下载，但至少一部分文档已经从服务器收到，浏览器决定切换到新文档。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
documentId
字符串
Chrome 106 及更高版本已加载文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
number
0 表示导航发生在标签页内容窗口中；正值表示在子框架中导航。帧 ID 在标签页中是唯一的。
-
frameTypeChrome 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。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
number
0 表示导航发生在标签页内容窗口中；正值表示在子框架中导航。帧 ID 在标签页中是唯一的。
-
frameTypeChrome 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参数如下所示：(details: object) => void
-
对象
-
number
包含 sourceTabId（在其中触发导航）的帧的 ID。0 表示主帧。
-
number
针对源帧运行渲染程序的进程的 ID。
-
number
在其中触发导航的标签页的 ID。
-
number
在其中打开网址的标签页的 ID
-
number
浏览器即将创建新视图的时间（以毫秒为单位，从 Epoch 起算）。
-
字符串
要在新窗口中打开的网址。
-
-
-
对象（可选）
-
要导航到的网址必须满足的条件。“架构”和“ports”对于此事件，系统会忽略 UrlFilter 的字段。
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
在网页的 DOM 已完全构建，但引用的资源可能未完成加载时触发。
参数
-
callback
函数
callback参数如下所示：(details: object) => void
-
详细信息
对象
-
documentId
字符串
Chrome 106 及更高版本已加载文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
number
0 表示导航发生在标签页内容窗口中；正值表示在子框架中导航。帧 ID 在标签页中是唯一的。
-
frameTypeChrome 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。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
错误
字符串
错误说明。
-
frameId
number
0 表示导航发生在标签页内容窗口中；正值表示在子框架中导航。帧 ID 在标签页中是唯一的。
-
frameTypeChrome 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。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
number
0 表示导航发生在标签页内容窗口中；正值表示在子框架中导航。帧 ID 在标签页中是唯一的。
-
frameTypeChrome 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。
-
documentLifecycleChrome 106 及更高版本
文档所处的生命周期。
-
frameId
number
0 表示导航发生在标签页内容窗口中；正值表示在子框架中导航。帧 ID 在标签页中是唯一的。
-
frameTypeChrome 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
替换发生的时间，以从公元纪年开始计算的毫秒数表示。
-
-