说明
使用 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
属性在内部保持一致。将一个事件与另一个事件进行比较可获取它们之间的正确偏移量,但将它们与扩展程序中的当前时间进行比较(例如,通过 (new Date()).getTime()
)可能会产生意外的结果。
帧 ID
标签页中的框架可以通过框架 ID 进行标识。主帧的帧 ID 始终为 0,子帧的 ID 是一个正数。在帧中构建文档后,其帧 ID 在文档的生命周期内保持不变。从 Chrome 49 开始,此 ID 在帧的生命周期内(多次导航中)也是常量。
由于 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
枚举
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
导航的原因。使用的过渡类型与历史记录 API 中定义的过渡类型相同。这些过渡类型与 history API 中定义的相同,但用 "start_page"
代替 "auto_toplevel"
(为了实现向后兼容性)。
枚举
"typed"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
"start_page"
"form_submit"
"keyword_generated"
方法
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
检索关于指定标签页的所有帧的信息。
参数
-
详细信息
对象
要从中检索所有帧的标签页的相关信息。
-
tabId
number
标签页的 ID。
-
-
callback
函数(可选)
callback
参数如下所示:(details?: object[]) => void
-
详细信息
对象 [] 可选
给定标签页中的框架列表,如果指定的标签页 ID 无效,则返回 null。
-
documentId
string
Chrome 106 及更高版本已加载文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
errorOccurred
boolean
如果此帧中的最后一次导航被错误中断(即触发 onErrorOccurred 事件),则为 true。
-
frameId
number
帧的 ID。0 表示这是主帧;正值表示子帧的 ID。
-
frameTypeChrome 106 及更高版本
发生导航的帧类型。
-
parentDocumentId
字符串(可选)
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级,则不设置此项。
-
parentFrameId
number
父框架的 ID,如果这是主框架,则为
-1
。 -
processId
number
为此帧运行渲染程序的进程的 ID。
-
网址
string
当前与此框架相关联的网址。
-
-
返回
-
Promise<object[] | undefined>
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
数字可选
从 Chrome 49 开始已废弃框架现在通过其标签页 ID 和框架 ID 进行唯一标识;不再需要进程 ID,因此该进程 ID 会被忽略。
运行此标签页的渲染程序的进程的 ID。
-
tabId
数字可选
框架所在的标签页的 ID。
-
-
callback
函数(可选)
callback
参数如下所示:(details?: object) => void
-
详细信息
对象(可选)
有关所请求框架的信息,如果指定的框架 ID 和/或标签页 ID 无效,则为 null。
-
documentId
string
Chrome 106 及更高版本已加载文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
errorOccurred
boolean
如果此帧中的最后一次导航被错误中断(即触发 onErrorOccurred 事件),则为 true。
-
frameTypeChrome 106 及更高版本
发生导航的帧类型。
-
parentDocumentId
字符串(可选)
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级,则不设置此项。
-
parentFrameId
number
父框架的 ID,如果这是主框架,则为
-1
。 -
网址
string
当前与此框架相关联的网址(如果由 frameId 标识的框架存在于给定标签页中的某个点)。网址与给定 frameId 相关联并不意味着相应的框架仍然存在。
-
-
返回
-
Promise<object | undefined>
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
从 Chrome 50 开始已废弃不再为此事件设置 processId,因为在 onCommit 之前,呈现所生成文档的进程是未知的。
-1 的值。
-
number
要在其中进行导航的标签页的 ID。
-
number
浏览器即将启动导航的时间(以毫秒为单位,从 Epoch 起算)。
-
string
-
-
-
对象(可选)
-
要转到的网址必须满足的条件。对于此事件,系统将忽略 UrlFilter 的“schemes”和“ports”字段。
-
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
在进行导航时触发。文档(及其对应的资源,例如图片和子框架)可能仍在下载,但服务器至少已收到文档的部分内容,并且浏览器已决定切换到新文档。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
documentId
string
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
导航的提交时间,以从公元纪年开始计算的毫秒数表示。
-
transitionQualifiers
转换限定符列表。
-
transitionType
导航的原因。
-
网址
string
-
-
-
过滤条件
对象(可选)
-
网址
要转到的网址必须满足的条件。对于此事件,系统将忽略 UrlFilter 的“schemes”和“ports”字段。
-
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
在文档(包括其引用的资源)已完全加载并初始化时触发。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
documentId
string
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 起算)。
-
网址
string
-
-
-
过滤条件
对象(可选)
-
网址
要转到的网址必须满足的条件。对于此事件,系统将忽略 UrlFilter 的“schemes”和“ports”字段。
-
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
为托管导航而创建新窗口或现有窗口中的新标签页时触发。
参数
-
功能
callback
参数如下所示:(details: object) => void
-
对象
-
number
使用 sourceTabId 来触发导航的帧的 ID。0 表示主帧。
-
number
为源帧运行渲染程序的进程的 ID。
-
number
在其中触发导航的标签页的 ID。
-
number
打开网址的标签页的 ID
-
number
浏览器即将创建新视图的时间,以自纪元以来的毫秒数表示。
-
string
要在新窗口中打开的网址。
-
-
-
对象(可选)
-
要转到的网址必须满足的条件。对于此事件,系统将忽略 UrlFilter 的“schemes”和“ports”字段。
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
在网页的 DOM 已完全构建,但引用的资源可能无法完成加载时触发。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
documentId
string
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 起算)。
-
网址
string
-
-
-
过滤条件
对象(可选)
-
网址
要转到的网址必须满足的条件。对于此事件,系统将忽略 UrlFilter 的“schemes”和“ports”字段。
-
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
在发生错误且导航中止时触发。如果发生网络连接错误或用户取消了导航,就可能会发生这种情况。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
documentId
string
Chrome 106 及更高版本已加载文档的 UUID。
-
documentLifecycleChrome 106 及更高版本
文档所在的生命周期。
-
error
string
错误说明。
-
frameId
number
0 表示导航发生在标签页内容窗口中;正值表示在子框架中导航。帧 ID 在标签页中是唯一的。
-
frameTypeChrome 106 及更高版本
发生导航的帧类型。
-
parentDocumentId
字符串(可选)
Chrome 106 及更高版本拥有此帧的父文档的 UUID。如果没有父级,则不设置此项。
-
parentFrameId
number
Chrome 74 及更高版本父框架的 ID,如果这是主框架,则为
-1
。 -
processId
number
从 Chrome 50 开始已废弃不再为此事件设置 processId。
-1 的值。
-
tabId
number
在其中进行导航的标签页的 ID。
-
timeStamp
number
错误发生的时间,以从公元纪年开始计算的毫秒数表示。
-
网址
string
-
-
-
过滤条件
对象(可选)
-
网址
要转到的网址必须满足的条件。对于此事件,系统将忽略 UrlFilter 的“schemes”和“ports”字段。
-
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
在框架的历史记录更新为新网址时触发。该框架的所有将来事件都将使用更新后的网址。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
documentId
string
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
导航的提交时间,以从公元纪年开始计算的毫秒数表示。
-
transitionQualifiers
转换限定符列表。
-
transitionType
导航的原因。
-
网址
string
-
-
-
过滤条件
对象(可选)
-
网址
要转到的网址必须满足的条件。对于此事件,系统将忽略 UrlFilter 的“schemes”和“ports”字段。
-
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
在帧的引用片段更新时触发。该框架的所有将来事件都将使用更新后的网址。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
documentId
string
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
导航的提交时间,以从公元纪年开始计算的毫秒数表示。
-
transitionQualifiers
转换限定符列表。
-
transitionType
导航的原因。
-
网址
string
-
-
-
过滤条件
对象(可选)
-
网址
要转到的网址必须满足的条件。对于此事件,系统将忽略 UrlFilter 的“schemes”和“ports”字段。
-
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
标签页内容被其他(通常是预先呈现的)标签页替换时触发。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
replacedTabId
number
被替换的标签页的 ID。
-
tabId
number
替换了旧标签页的标签页的 ID。
-
timeStamp
number
替换发生的时间(以毫秒为单位,从 Epoch 起算)。
-
-