chrome.webNavigation

Description

使用 chrome.webNavigation API 接收有关正在进行的导航请求状态的通知。

Permissions

webNavigation

# Manifest

所有 chrome.webNavigation 方法和事件都要求您在扩展清单(manifest)中声明“webNavigation”权限。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "webNavigation"
  ],
  ...
}

# Examples

您可以在 examples/api/webNavigation 目录中找到使用 tabs 模块的简单示例。有关其他示例和查看源代码的帮助，请参阅示例。

# Event order(事件顺序)

对于成功完成的导航，事件按以下顺序触发：

onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted

在此过程中发生的任何错误都会导致 onErrorOccurred 事件。对于特定导航，在 onErrorOccurred 之后不会触发其他事件。

如果导航框架包含子框架，则其 onCommitted 在其任何子框架的 onBeforeNavigate 之前触发；而 onCompleted 在其所有孩子的 onCompleted 之后被解雇。

如果帧的参考片段发生更改，则会触发 onReferenceFragmentUpdated 事件。这个事件可以在 onDOMContentLoaded 之后的任何时间触发，甚至在 onCompleted 之后。

如果历史 API 用于修改帧的状态（例如使用 history.pushState()，则会触发 onHistoryStateUpdated 事件。该事件可以在 onDOMContentLoaded 之后的任何时间触发。

如果导航从后向转发缓存中恢复了页面，则不会触发 onDOMContentLoaded 事件。该事件不会被触发，因为在第一次访问页面时内容已经完成加载。

如果导航是通过 Chrome Instant 或 Instant Pages 触发的，则完全加载的页面将交换到当前选项卡中。在这种情况下，将触发 onTabReplaced 事件。

# Relation to webRequest events(与 webRequest 事件的关系)

webRequest API 的事件和 webNavigation API 的事件之间没有定义的顺序。对于已经开始新导航的框架，仍有可能收到 webRequest 事件，或者只有在网络资源已经完全加载后才能进行导航。

通常，webNavigation 事件与 UI 中显示的导航状态密切相关，而 webRequest 事件对应于通常对用户不透明的网络堆栈状态。

# A note about tab IDs(关于选项卡 ID 的说明)

并非所有导航选项卡都对应于 Chrome 用户界面中的实际选项卡，例如，正在预渲染的选项卡。此类选项卡无法通过tabs API 访问，您也无法通过 webNavigation.getFrame 或 webNavigation.getAllFrames 请求有关它们的信息。一旦这样的选项卡被换入，就会触发 onTabReplaced 事件，并且它们可以通过这些 API 访问。

# A note about timestamps(关于时间戳的说明)

需要注意的是，操作系统在处理不同 Chrome 进程时的一些技术上的奇怪之处可能会导致浏览器本身和扩展进程之间的时钟出现偏差。这意味着 WebNavigation 的事件的 timeStamp 属性只能保证内部一致。将一个事件与另一个事件进行比较将为您提供它们之间的正确偏移量，但将它们与扩展中的当前时间进行比较（例如，通过 (new Date()).getTime()）可能会产生意想不到的结果。

# A note about frame IDs(关于帧|框架 ID 的说明)

选项卡内的框架可以通过框架 ID 进行标识。主框架的框架ID始终为0，子框架的ID为正数。一旦文档在框架中构建，它的框架 ID 在文档的生命周期内保持不变。从 Chrome 49 开始，这个 ID 在框架的生命周期内也是不变的（跨多个导航）。

由于 Chrome 的多进程特性，选项卡可能会使用不同的进程来呈现网页的源和目标。因此，如果导航发生在新进程中，您可能会收到来自新页面和旧页面的事件，直到提交新导航（即为新主框架发送 onCommitted 事件）。换句话说，可能有多个具有相同 frameId 的 webNavigation 事件未决序列。可以通过 processId 键区分序列。

另请注意，在临时加载期间，该过程可能会切换多次。当负载被重定向到不同的站点时会发生这种情况。在这种情况下，您将收到重复的 onBeforeNavigate 和 onErrorOccurred 事件，直到您收到最终的 onCommitted 事件。

# Transition types and qualifiers(转换类型和限定符)

webNavigation API 的 onCommitted 事件有一个 transitionType 和一个 transitionQualifiers 属性。转换类型与history API 中使用的相同，描述了浏览器如何导航到此特定 URL。此外，可以返回多个转换限定符，进一步定义导航。

存在以下转换限定符：

Transition qualifier(过渡限定符) Description
"client_redirect" 导航期间发生了由页面上的 JavaScript 或元刷新标记引起的一个或多个重定向。
"server_redirect" 导航期间发生了由服务器发送的 HTTP 标头引起的一个或多个重定向。
"forward_back" 用户使用前进或后退按钮启动导航。
"from_address_bar" 用户从地址栏（又名多功能框 aka Omnibox）启动导航。

Summary

Types

TransitionQualifier

Chrome 44+

TYPE

"client_redirect", "server_redirect", "forward_back", or "from_address_bar"

TransitionType

Chrome 44+

导航(navigation)的原因。使用历史 API（history API） 中定义的相同转换类型。这些与历史 API 中定义的转换类型相同，除了用“start_page”代替“auto_toplevel”（为了向后兼容）。

TYPE

"link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", or "keyword_generated"

Methods

getAllFrames 

chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
)

Promise

检索有关给定选项卡的所有框架的信息。

PARAMETERS

  • details

    object

    有关要从中检索所有帧的选项卡的信息。

    • tabId

      number

      选项卡的 ID。

  • callback

    function optional

    The callback parameter looks like:

    (details?: object[]) => void

    • details

      object[] optional

      给定选项卡中的框架列表，如果指定的选项卡 ID 无效，则为 null。

      • errorOccurred

        boolean

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

      • frameId

        number

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

      • parentFrameId

        number

        父框架的 ID，如果这是主框架，则为 -1。

      • processId

        number

        为该帧运行渲染器的进程的 ID。

      • url

        string

        当前与此框架关联的 URL。

RETURNS

  • Promise<object[] | undefined>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getFrame 

chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
)

Promise

检索有关给定帧的信息。框架是指网页的<iframe>或<frame>，由标签ID和框架ID标识。

PARAMETERS

  • details

    object

    有关要检索有关信息的框架的信息。

    • frameId

      number

      给定选项卡中框架的 ID。

    • processId

      number optional

      Deprecated since Chrome 49

      框架现在由它们的标签 ID 和框架 ID 唯一标识；不再需要进程 ID，因此被忽略。

      运行此选项卡的渲染器的进程的 ID。

    • tabId

      number

      框架所在的选项卡的 ID。

  • callback

    function optional

    The callback parameter looks like:

    (details?: object) => void

    • details

      object optional

      有关请求的框架的信息，如果指定的框架 ID 和/或选项卡 ID 无效，则为 null。

      • errorOccurred

        boolean

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

      • parentFrameId

        number

        父框架的 ID，如果这是主框架，则为 -1。

      • url

        string

        当前与此框架关联的 URL，如果由 frameId 标识的框架存在于给定选项卡中的某一点。 URL 与给定 frameId 相关联的事实并不意味着相应的框架仍然存在。

RETURNS

  • Promise<object | undefined>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

Events

onBeforeNavigate 

chrome.webNavigation.onBeforeNavigate.addListener(
  callback: function,
  filters?: object,
)

当导航即将发生时触发。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • frameId

        number

        0 表示导航发生在选项卡内容窗口中；正值表示子帧中的导航。帧 ID 对于给定的选项卡和进程是唯一的。

      • parentFrameId

        number

        父框架的 ID，如果这是主框架，则为 -1。

      • processId

        number

        Deprecated since Chrome 50

        不再为此事件设置 processId，因为在 onCommit 之前不知道将呈现结果文档的进程。

        -1 的值。

      • tabId

        number

        即将发生导航的选项卡的 ID。

      • timeStamp

        number

        浏览器即将开始导航的时间，自纪元以来的毫秒数。

      • url

        string

  • filters

    object optional

    • url

      events.UrlFilter[]

      被导航到的 URL 必须满足的条件。此事件将忽略 UrlFilter 的 'schemes' 和 'ports' 字段。

onCommitted 

chrome.webNavigation.onCommitted.addListener(
  callback: function,
  filters?: object,
)

提交导航时触发。文档（及其引用的资源，例如图像和子帧）可能仍在下载，但至少部分文档已从服务器接收，并且浏览器已决定切换到新文档。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • frameId

        number

        0 表示导航发生在选项卡内容窗口中；正值表示子帧中的导航。框架 ID 在选项卡中是唯一的。

      • parentFrameId

        number

        Chrome 74+

        父框架的 ID，如果这是主框架，则为 -1。

      • processId

        number

        为该帧运行渲染器的进程的 ID。

      • tabId

        number

        发生导航的选项卡的 ID。

      • timeStamp

        number

        提交导航的时间，自纪元以来的毫秒数。

      • transitionQualifiers

        TransitionQualifier[]

        转换限定符列表。

      • transitionType

        TransitionType

        导航的原因。

      • url

        string

  • filters

    object optional

    • url

      events.UrlFilter[]

      被导航到的 URL 必须满足的条件。此事件将忽略 UrlFilter 的 'schemes' 和 'ports' 字段。

onCompleted 

chrome.webNavigation.onCompleted.addListener(
  callback: function,
  filters?: object,
)

当文档（包括它所引用的资源）完全加载和初始化时触发。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • frameId

        number

        0 表示导航发生在选项卡内容窗口中；正值表示子帧中的导航。框架 ID 在选项卡中是唯一的。

      • parentFrameId

        number

        Chrome 74+

        父框架的 ID，如果这是主框架，则为 -1。

      • processId

        number

        为该帧运行渲染器的进程的 ID。

      • tabId

        number

        发生导航的选项卡的 ID。

      • timeStamp

        number

        文档完成加载的时间，自纪元以来的毫秒数。

      • url

        string

  • filters

    object optional

    • url

      events.UrlFilter[]

      被导航到的 URL 必须满足的条件。此事件将忽略 UrlFilter 的 'schemes' 和 'ports' 字段。

onCreatedNavigationTarget 

chrome.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

在创建新窗口或现有窗口中的新选项卡以承载导航时触发。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • sourceFrameId

        number

        触发导航的具有 sourceTabId 的框架的 ID。 0 表示主帧。

      • sourceProcessId

        number

        为源帧运行渲染器的进程的 ID。

      • sourceTabId

        number

        触发导航的选项卡的 ID。

      • tabId

        number

        在其中打开 url 的选项卡的 ID

      • timeStamp

        number

        浏览器即将创建新视图的时间，以纪元以来的毫秒数为单位。

      • url

        string

        要在新窗口中打开的 URL。

  • filters

    object optional

    • url

      events.UrlFilter[]

      被导航到的 URL 必须满足的条件。此事件将忽略 UrlFilter 的 'schemes' 和 'ports' 字段。

onDOMContentLoaded 

chrome.webNavigation.onDOMContentLoaded.addListener(
  callback: function,
  filters?: object,
)

当页面的 DOM 完全构建时触发，但引用的资源可能未完成加载。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • frameId

        number

        0 表示导航发生在选项卡内容窗口中；正值表示子帧中的导航。框架 ID 在选项卡中是唯一的。

      • parentFrameId

        number

        Chrome 74+

        父框架的 ID，如果这是主框架，则为 -1。

      • processId

        number

        为该帧运行渲染器的进程的 ID。

      • tabId

        number

        发生导航的选项卡的 ID。

      • timeStamp

        number

        页面 DOM 完全构建的时间，自纪元以来的毫秒数。

      • url

        string

  • filters

    object optional

    • url

      events.UrlFilter[]

      被导航到的 URL 必须满足的条件。此事件将忽略 UrlFilter 的 'schemes' 和 'ports' 字段。

onErrorOccurred 

chrome.webNavigation.onErrorOccurred.addListener(
  callback: function,
  filters?: object,
)

当发生错误并且导航中止时触发。如果发生网络错误或用户中止导航，就会发生这种情况。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • error

        string

        错误描述。

      • frameId

        number

        0 表示导航发生在选项卡内容窗口中；正值表示子帧中的导航。框架 ID 在选项卡中是唯一的。

      • parentFrameId

        number

        Chrome 74+

        父框架的 ID，如果这是主框架，则为 -1。

      • processId

        number

        Deprecated since Chrome 50

        不再为此事件设置 processId。

        -1 的值。

      • tabId

        number

        发生导航的选项卡的 ID。

      • timeStamp

        number

        错误发生的时间，自纪元以来的毫秒数。

      • url

        string

  • filters

    object optional

    • url

      events.UrlFilter[]

      被导航到的 URL 必须满足的条件。此事件将忽略 UrlFilter 的 'schemes' 和 'ports' 字段。

onHistoryStateUpdated 

chrome.webNavigation.onHistoryStateUpdated.addListener(
  callback: function,
  filters?: object,
)

当框架的历史记录更新为新的 URL 时触发。该框架的所有未来事件都将使用更新后的 URL。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • frameId

        number

        0 表示导航发生在选项卡内容窗口中；正值表示子帧中的导航。框架 ID 在选项卡中是唯一的。

      • parentFrameId

        number

        Chrome 74+

        父框架的 ID，如果这是主框架，则为 -1。

      • processId

        number

        为该帧运行渲染器的进程的 ID。

      • tabId

        number

        发生导航的选项卡的 ID。

      • timeStamp

        number

        提交导航的时间，自纪元以来的毫秒数。

      • transitionQualifiers

        TransitionQualifier[]

        转换限定符列表。

      • transitionType

        TransitionType

        导航的原因。

      • url

        string

  • filters

    object optional

    • url

      events.UrlFilter[]

      被导航到的 URL 必须满足的条件。此事件将忽略 UrlFilter 的 'schemes' 和 'ports' 字段。

onReferenceFragmentUpdated 

chrome.webNavigation.onReferenceFragmentUpdated.addListener(
  callback: function,
  filters?: object,
)

当帧的参考片段更新时触发。该框架的所有未来事件都将使用更新后的 URL。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • frameId

        number

        0 表示导航发生在选项卡内容窗口中；正值表示子帧中的导航。框架 ID 在选项卡中是唯一的。

      • parentFrameId

        number

        Chrome 74+

        父框架的 ID，如果这是主框架，则为 -1。

      • processId

        number

        为该帧运行渲染器的进程的 ID。

      • tabId

        number

        发生导航的选项卡的 ID。

      • timeStamp

        number

        提交导航的时间，自纪元以来的毫秒数。

      • transitionQualifiers

        TransitionQualifier[]

        转换限定符列表。

      • transitionType

        TransitionType

        导航的原因。

      • url

        string

  • filters

    object optional

    • url

      events.UrlFilter[]

      被导航到的 URL 必须满足的条件。此事件将忽略 UrlFilter 的 'schemes' 和 'ports' 字段。

onTabReplaced 

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

当选项卡的内容被其他（通常是先前预渲染的）选项卡替换时激发。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (details: object) => void

    • details

      object

      • replacedTabId

        number

        被替换的选项卡的 ID。

      • tabId

        number

        替换旧选项卡的选项卡的 ID。

      • timeStamp

        number

        替换发生的时间，自纪元以来的毫秒数。

By.一粒技术服务.

results matching ""

    No results matching ""