说明
使用 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 起算)。
-
-