webNavigation

ナビゲーションのいろいろな段階でイベントリスナーを追加します。ナビゲーションにはある URL から他に移動するブラウザーフレームにより成り立っていて、それは(いつもではなく)通常はリンクのクリックやロケーションバーへの URL 入力といったユーザー操作の応答として発生します。

webRequest API と比較して: ナビゲーションは通常、ブラウザーにウェブリクエストを発生させますが、webRequest API は HTTP 層からの低レベルな観点に関心を持っており、一方で webNavigation API はブラウザー UI 自身に対して、より関心を持っています。

それぞれのイベントはナビゲーションの特定のステージに対応しています。イベントシーケンスは次の通りです:

• 主なフローは次の通り:
  • onBeforeNavigate
  • onCommitted
  • onDOMContentLoaded
  • onCompleted.
• 追加のものは次の通り:
  • onCreatedNavigationTarget は、ブラウザーがナビゲーション用にタブやウィンドウを作成する必要がある場合 (例えば、ユーザーがリンクを新しいタブで開いたために)、onBeforeNavigate の前に発火します。
  • onHistoryStateUpdated はページが history API を使ってブラウザーのロケーションバーに表示された URL を更新する場合に発火します。
  • onReferenceFragmentUpdated はページの fragment identifier が変更された場合に発火します。
  • onErrorOccurred はあらゆる場所で発火します。

それぞれのナビゲーションは特定のブラウザーフレーム内の URL の遷移です。ブラウザーフレームはタブ ID とフレーム ID で識別されます。フレームはタブ内の再上位のブラウジングコンテキストである場合や、iframe として実装されたネストされたブラウジングコンテキストである場合があります。

それぞれのイベントの addListener() の呼び出しはオプションの filter パラメーターを受け入れます。filter は 1 つ以上の URL パターンを指定し、イベントはターゲット URL がパターンにマッチしたナビゲーションの時だけに発火します。

onCommitted イベントリスナーには 2 つの追加プロパティが渡されます: ナビゲーションの原因 (例えばユーザーがリンクをクリックしたり、ユーザーがブックマークを選んだり) を示すTransitionType と、ナビゲーションの詳細情報を提供するTransitionQualifier です。

この API を使うには"webNavigation" パーミッションが必要です。