说明
使用 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
枚举
"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,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 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,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 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
替换发生的时间,以从公元纪年开始计算的毫秒数表示。
-
-