chrome.webNavigation

説明

chrome.webNavigation API を使用して、処理中のナビゲーション リクエストのステータスに関する通知を受け取ります。

権限

webNavigation

すべての chrome.webNavigation メソッドとイベントで "webNavigation" 権限を宣言する必要があります 拡張機能のマニフェスト内例:

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

コンセプトと使用方法

イベントの順序

ナビゲーションが正常に完了すると、イベントは次の順序で発生します。

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

プロセス中にエラーが発生すると、onErrorOccurred イベントが発生します。特定の onErrorOccurred の後にイベントは発生しません。

ナビゲーション フレームにサブフレームが含まれている場合、その子のどのフレームよりも前に onCommitted が呼び出されます。 onBeforeNavigate、一方、onCompleted は、その子のすべての onCompleted の後に発生します。

フレームの参照フラグメントが変更されると、onReferenceFragmentUpdated イベントが発生します。この イベントは、onDOMContentLoaded の後で、onCompleted の後でも発生します。

History API を使用してフレームの状態を変更する場合（例: history.pushState()、 onHistoryStateUpdated イベントが発生した。このイベントは、onDOMContentLoaded の後にいつでも発生します。

ナビゲーションによってバック フォワード キャッシュからページが復元された場合、onDOMContentLoaded イベントは は呼び出されません。ページの読み込み時にコンテンツの読み込みがすでに完了しているため、イベントは呼び出されません。 確認できます。

Chrome インスタント検索またはインスタント ページを使用してナビゲーションがトリガーされた場合は、 ページが現在のタブに差し替えられます。その場合は、onTabReplaced イベントが発生します。

webRequest イベントとの関係

webRequest API のイベントと webNavigation API。すでに取得されているフレームの webRequest イベントが依然として受信される可能性があります。 新しいナビゲーションが開始された、またはネットワーク リソースがすでに解放された後にのみナビゲーションが続行された 確認できます。

一般に、webNavigation イベントは、表示されるナビゲーション状態と密接に関連しています。 webRequest イベントはネットワーク スタックの状態に対応します。 通常はユーザーには見えません。

タブ ID

ナビゲーション タブがすべて Chrome の UI の実際のタブに対応しているわけではありません。たとえば、 渡されます。このようなタブは、Tabs API を使用してアクセスすることも、情報をリクエストすることもできません webNavigation.getFrame() または webNavigation.getAllFrames() を呼び出して情報を取得できます。そのようなタブが スワップインされ、onTabReplaced イベントが発生すると、これらの API を通じてアクセスできるようになります。

タイムスタンプ

重要な点として、個別の Chrome に対する OS の処理において、技術的なおかしな点が ブラウザ自体と拡張機能のプロセスとの間の時計にずれが生じることがあります。 WebNavigation イベントの timeStamp プロパティの timeStamp プロパティは、保証されたもののみであることを意味 内部的整合性を持たせます。あるイベントと別のイベントを比較することで、正しいオフセットが得られます ただし、拡張機能内の現在の時刻と比較します（(new Date()).getTime()、 予期しない結果が生じる可能性があります。

フレーム ID

タブ内のフレームはフレーム ID で識別できます。メインフレームのフレーム ID は常に 0 で、 子フレームの ID は正の数です。フレーム内にドキュメントが作成されると、そのフレーム ID が ドキュメントの存続中は変わりません。Chrome 49 以降では、この ID はすべての （複数のナビゲーションにわたって）フレームの存続期間。

Chrome のマルチプロセスという特性により、1 つのタブでソースの表示に異なるプロセスが使用される場合があります。 リダイレクトされますそのため、ナビゲーションが新しいプロセスで実行される場合は、 新しいナビゲーションが commit されるまで（ 新しいメインフレームに対して onCommitted イベントが送信されます）。言い換えれば、より多くの 同じ frameId を持つ、webNavigation イベントの保留中のシーケンスが複数存在します。シーケンスは、 processId キーで区別されます。

また、一時的な読み込み中に、プロセスは複数回切り替わる可能性があります。状況 別のサイトにリダイレクトされたとき。この場合は onBeforeNavigate イベントと onErrorOccurred イベント（最後の onCommitted イベントを受け取るまで）。

拡張機能のライフサイクルも クリックします。フレームはドキュメント（コミットされた URL に関連付けられたドキュメント）をホストします。 ドキュメントは変更できますが（ナビゲーションなど）、frameId は変更されないため、 特定のドキュメントで何かが発生したことを、 frameIds のみ）。documentId のコンセプトを導入しています。 ドキュメントごとの一意の識別子ですフレームを移動して ID が変更されます。このフィールドは ページのライフサイクル状態（事前レンダリング/アクティブ/キャッシュ）が変化したとき なぜならこの点は変わらないからです

遷移のタイプと修飾子

webNavigation onCommitted イベントには、transitionType と transitionQualifiers が含まれます。 プロパティです。遷移タイプは、History API で使用されているものと同じで、 ブラウザがこの URL にたどり着いたとしますまた、いくつかの遷移修飾子を ナビゲーションを定義します。

次の遷移修飾子が存在します。

遷移修飾子説明
「client_redirect」ナビゲーション中にページの JavaScript タグまたはメタ リフレッシュ タグによるリダイレクトが 1 つ以上発生しています。
「server_redirect」ナビゲーション中に、サーバーから送信された HTTP ヘッダーによるリダイレクトが 1 件以上発生しました。
「forward_back」ユーザーが [進む] ボタンまたは [戻る] ボタンを使用してナビゲーションを開始した。
"from_address_bar"ユーザーがアドレスバー（アドレスバー）からナビゲーションを開始した。

例

この API を試すには、chrome-extension-samples から webNavigation API の例をインストールしてください。 できます。

型

TransitionQualifier

Chrome 44 以降

列挙型

「client_redirect」

server_redirect

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 以降

ナビゲーションの原因。History API で定義されているのと同じ遷移タイプが使用されます。これらは History API の定義と同じですが、"auto_toplevel"（下位互換性のため）の代わりに "start_page" を使用している点が異なります。

列挙型

"リンク"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

「再読み込み」

"キーワード"

"keyword_generated"

メソッド

getAllFrames()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
)

指定したタブのすべてのフレームに関する情報を取得します。

パラメータ

  • 詳細

    オブジェクト

    すべてのフレームを取得するタブに関する情報。

    • tabId

      数値

      タブの ID。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (details?: object[]) => void

    • 詳細

      オブジェクト [] 省略可

      指定されたタブ内のフレームのリスト。指定されたタブ ID が無効な場合は null。

      • documentId

        文字列

        Chrome 106 以降

        読み込まれたドキュメントの UUID。

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 以降

        ドキュメントのライフサイクル。

      • errorOccurred

        ブール値

        このフレーム内の最後のナビゲーションがエラーによって中断された場合（onErrorOccurred イベントが発生したとき）は true。

      • frameId

        数値

        フレームの ID。0 はメインフレームであることを示します。正の値はサブフレームの ID を示します。

      • frameType

        FrameType

        Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        親フレームの ID。メインフレームの場合は -1。

      • processId

        数値

        このフレームのレンダラを実行するプロセスの ID。

      • URL

        文字列

        現在このフレームに関連付けられている URL。

戻り値

  • Promise&lt;object[] |未定義>

    Chrome 93 以降

    Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getFrame()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
)

指定されたフレームに関する情報を取得します。フレームが <iframe> を参照するまたは <frame>タブ ID とフレーム ID で識別されます。

パラメータ

  • 詳細

    オブジェクト

    情報を取得するフレームに関する情報。

    • documentId

      文字列（省略可）

      Chrome 106 以降

      ドキュメントの UUID。frameId や tabId を指定すると、指定したドキュメント ID で見つかったドキュメントと一致するかどうかが検証されます。

    • frameId

      数値（省略可）

      指定されたタブ内のフレームの ID。

    • processId

      数値（省略可）

      <ph type="x-smartling-placeholder"></ph> Chrome 49 以降非推奨

      フレームはタブ ID とフレーム ID によって一意に識別されるようになりました。プロセス ID は不要になったため無視されます。

      このタブのレンダラを実行するプロセスの ID。

    • tabId

      数値（省略可）

      フレームが含まれるタブの ID。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (details?: object) => void

    • 詳細

      オブジェクト（省略可）

      リクエストされたフレームに関する情報。指定されたフレーム ID やタブ ID が無効な場合は null。

      • documentId

        文字列

        Chrome 106 以降

        読み込まれたドキュメントの UUID。

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 以降

        ドキュメントのライフサイクル。

      • errorOccurred

        ブール値

        このフレーム内の最後のナビゲーションがエラーによって中断された場合（onErrorOccurred イベントが発生したとき）は true。

      • frameType

        FrameType

        Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        親フレームの ID。メインフレームの場合は -1。

      • URL

        文字列

        frameId によって識別されるフレームが特定のタブのある時点で存在した場合、このフレームに現在関連付けられている URL。URL が特定の frameId に関連付けられているからといって、対応するフレームが引き続き存在するとは限りません。

戻り値

  • Promise&lt;object |未定義>

    Chrome 93 以降

    Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

イベント

onBeforeNavigate

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

ナビゲーションが行われる際に呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • Chrome 106 以降

        ドキュメントのライフサイクル。

      • frameId

        数値

        0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID は、特定のタブとプロセスに対して一意です。

      • Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        親フレームの ID。メインフレームの場合は -1。

      • processId

        数値

        <ph type="x-smartling-placeholder"></ph> Chrome 50 以降非推奨

        結果のドキュメントをレンダリングするプロセスは onCommit まで不明なため、このイベントの processId は設定されません。

        -1 の値。

      • tabId

        数値

        ナビゲーションが行われる予定のタブの ID。

      • timeStamp

        数値

        ブラウザがナビゲーションを開始しようとした時刻（エポックからのミリ秒）。

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

    • 移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。

onCommitted

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

ナビゲーションが commit されたときに呼び出されます。ドキュメント（およびドキュメントが参照するリソース（画像やサブフレームなど））はまだダウンロード中である可能性がありますが、ドキュメントの少なくとも一部がサーバーから受信されており、ブラウザが新しいドキュメントへの切り替えを決定しました。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • documentId

        文字列

        Chrome 106 以降

        読み込まれたドキュメントの UUID。

      • Chrome 106 以降

        ドキュメントのライフサイクル。

      • frameId

        数値

        0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。

      • Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        Chrome 74 以降

        親フレームの ID。メインフレームの場合は -1。

      • processId

        数値

        このフレームのレンダラを実行するプロセスの ID。

      • tabId

        数値

        ナビゲーションが発生するタブの ID。

      • timeStamp

        数値

        ナビゲーションが commit された時刻（エポックからのミリ秒）。

      • transitionQualifiers

        TransitionQualifier[]

        遷移修飾子のリスト。

      • transitionType

        TransitionType

        ナビゲーションの原因。

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

    • 移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。

onCompleted

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

ドキュメント（参照先のリソースを含む）が完全に読み込まれ、初期化されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • documentId

        文字列

        Chrome 106 以降

        読み込まれたドキュメントの UUID。

      • Chrome 106 以降

        ドキュメントのライフサイクル。

      • frameId

        数値

        0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。

      • Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        Chrome 74 以降

        親フレームの ID。メインフレームの場合は -1。

      • processId

        数値

        このフレームのレンダラを実行するプロセスの ID。

      • tabId

        数値

        ナビゲーションが発生するタブの ID。

      • timeStamp

        数値

        ドキュメントの読み込みが完了した時刻（エポックからのミリ秒）。

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

    • 移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。

onCreatedNavigationTarget

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

ナビゲーションをホストするために、新しいウィンドウまたは既存のウィンドウ内の新しいタブが作成されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • sourceFrameId

        数値

        ナビゲーションがトリガーされる sourceTabId を持つフレームの ID。0 はメインフレームを示します。

      • sourceProcessId

        数値

        ソースフレームのレンダラを実行するプロセスの ID。

      • sourceTabId

        数値

        ナビゲーションがトリガーされるタブの ID。

      • tabId

        数値

        URL が開かれるタブの ID

      • timeStamp

        数値

        ブラウザが新しいビューを作成しようとした時刻（エポックからのミリ秒）。

      • URL

        文字列

        新しいウィンドウで開く URL。

  • フィルタ

    オブジェクト（省略可）

    • 移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。

onDOMContentLoaded

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

ページの DOM は完全に構築されていますが、参照されているリソースの読み込みは完了しない可能性があるときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • documentId

        文字列

        Chrome 106 以降

        読み込まれたドキュメントの UUID。

      • Chrome 106 以降

        ドキュメントのライフサイクル。

      • frameId

        数値

        0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。

      • Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        Chrome 74 以降

        親フレームの ID。メインフレームの場合は -1。

      • processId

        数値

        このフレームのレンダラを実行するプロセスの ID。

      • tabId

        数値

        ナビゲーションが発生するタブの ID。

      • timeStamp

        数値

        ページの DOM が完全に構築された時刻（エポックからのミリ秒）。

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

    • 移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。

onErrorOccurred

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

エラーが発生し、ナビゲーションが中断されたときに呼び出されます。ネットワーク エラーが発生したか、ユーザーが移動を中断した場合に発生することがあります。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • documentId

        文字列

        Chrome 106 以降

        読み込まれたドキュメントの UUID。

      • Chrome 106 以降

        ドキュメントのライフサイクル。

      • エラー

        文字列

        エラーの説明。

      • frameId

        数値

        0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。

      • Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        Chrome 74 以降

        親フレームの ID。メインフレームの場合は -1。

      • processId

        数値

        <ph type="x-smartling-placeholder"></ph> Chrome 50 以降非推奨

        このイベントには processId が設定されていません。

        -1 の値。

      • tabId

        数値

        ナビゲーションが発生するタブの ID。

      • timeStamp

        数値

        エラーが発生した時刻（エポックからのミリ秒）。

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

    • 移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。

onHistoryStateUpdated

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

フレームの履歴が新しい URL に更新されたときに呼び出されます。そのフレームの今後のすべてのイベントで、更新された URL が使用されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • documentId

        文字列

        Chrome 106 以降

        読み込まれたドキュメントの UUID。

      • Chrome 106 以降

        ドキュメントのライフサイクル。

      • frameId

        数値

        0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。

      • Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        Chrome 74 以降

        親フレームの ID。メインフレームの場合は -1。

      • processId

        数値

        このフレームのレンダラを実行するプロセスの ID。

      • tabId

        数値

        ナビゲーションが発生するタブの ID。

      • timeStamp

        数値

        ナビゲーションが commit された時刻（エポックからのミリ秒）。

      • transitionQualifiers

        TransitionQualifier[]

        遷移修飾子のリスト。

      • transitionType

        TransitionType

        ナビゲーションの原因。

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

    • 移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。

onReferenceFragmentUpdated

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

フレームの参照フラグメントが更新されたときに呼び出されます。そのフレームの今後のすべてのイベントで、更新された URL が使用されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • documentId

        文字列

        Chrome 106 以降

        読み込まれたドキュメントの UUID。

      • Chrome 106 以降

        ドキュメントのライフサイクル。

      • frameId

        数値

        0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。

      • Chrome 106 以降

        ナビゲーションが発生したフレームのタイプ。

      • parentDocumentId

        文字列（省略可）

        Chrome 106 以降

        このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。

      • parentFrameId

        数値

        Chrome 74 以降

        親フレームの ID。メインフレームの場合は -1。

      • processId

        数値

        このフレームのレンダラを実行するプロセスの ID。

      • tabId

        数値

        ナビゲーションが発生するタブの ID。

      • timeStamp

        数値

        ナビゲーションが commit された時刻（エポックからのミリ秒）。

      • transitionQualifiers

        TransitionQualifier[]

        遷移修飾子のリスト。

      • transitionType

        TransitionType

        ナビゲーションの原因。

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

    • 移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。

onTabReplaced

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

タブのコンテンツが別の（通常はプリレンダリングされた）タブに置き換わったときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • replacedTabId

        数値

        置き換えられたタブの ID。

      • tabId

        数値

        古いタブに置き換わったタブの ID。

      • timeStamp

        数値

        交換が行われた時刻（エポックからのミリ秒）。