webNavigation

为导航的各个阶段添加事件监听器。导航是指浏览器中的一个框架从一个 URL 过渡到另一个 URL，通常（但不总是）响应用户操作，如点击链接或在地址栏输入 URL。

与 webRequest API 相比：导航通常会导致浏览器发出 Web 请求，但 webRequest API 关注的是 HTTP 层的低级视图，而 webNavigation API 更关注浏览器 UI 本身的视图。

每个事件对应导航中的一个特定阶段。事件序列如下：

• 主要流程是：

  • onBeforeNavigate
  • onCommitted
  • onDOMContentLoaded
  • onCompleted.

• 此外：

  • 如果浏览器需要为导航创建新标签页或窗口（例如，因为用户在新标签页中打开链接），则会在 onBeforeNavigate 之前触发 onCreatedNavigationTarget。
  • 如果页面使用 History API 更新浏览器地址栏中显示的 URL，则会触发 onHistoryStateUpdated。
  • 如果页面的 片段标识符发生更改，则会触发 onReferenceFragmentUpdated。
  • onErrorOccurred 可以在任何时候触发。

每次导航都是特定浏览器框架中的 URL 转换。浏览器框架由标签页 ID 和框架 ID 标识。框架可以是标签页中的顶层浏览上下文，也可以是作为 iframe 实现的嵌套浏览上下文。

每个事件的 addListener() 调用都接受一个可选的 filter 参数。filter 将指定一个或多个 URL 模式，然后事件仅为目标 URL 与其中一个模式匹配的导航触发。

onCommitted 事件监听器会传递两个附加属性：一个 TransitionType，指示导航的原因（例如，用户点击了链接，或用户选择了书签）；以及一个 TransitionQualifier，提供有关导航的进一步信息。

要使用此 API，您需要拥有 "webNavigation" 权限。