chrome.webNavigation

更新日: 2026-09-25 robots: noindex

説明

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 イベントは UI に表示されるナビゲーション状態と密接に関連していますが、webRequest イベントはネットワーク スタックの状態に対応しており、通常はユーザーには表示されません。

タブ ID

すべてのナビゲーション タブが Chrome の UI の実際のタブに対応しているわけではありません（例: 事前レンダリング中のタブ）。このようなタブには tabs API からアクセスできず、webNavigation.getFrame や webNavigation.getAllFrames を使用して情報をリクエストすることもできません。このようなタブがスワップインされると、onTabReplaced イベントが発生し、これらの API を介してアクセスできるようになります。

タイムスタンプ

なお、OS が個別の Chrome プロセスを処理する際の技術的な不具合により、ブラウザ自体と拡張機能プロセスの間でクロックがずれることがあります。つまり、WebNavigation のイベントの timeStamp プロパティは、内部的にのみ整合性が保証されます。あるイベントを別のイベントと比較すると、それらの間の正しいオフセットが得られますが、拡張機能内の現在の時刻（(new Date()).getTime() など）と比較すると、予期しない結果が生じることがあります。

フレーム ID

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

Chrome のマルチプロセス特性により、タブはウェブページのソースと宛先のレンダリングに異なるプロセスを使用することがあります。そのため、新しいプロセスでナビゲーションが行われると、新しいナビゲーションが commit されるまで（つまり、新しいメインフレームに onCommitted イベントが送信されるまで）、新しいページと古いページの両方からイベントを受け取ることがあります。つまり、同じ frameId を持つ webNavigation イベントの保留中のシーケンスが複数存在する可能性があります。シーケンスは processId キーで区別できます。

また、暫定的な読み込み中にプロセスが数回切り替わる可能性があることにも注意してください。これは、負荷が別のサイトにリダイレクトされる場合に発生します。この場合、最終的な onCommitted イベントを受信するまで、onBeforeNavigate イベントと onErrorOccurred イベントが繰り返し受信されます。

拡張機能で問題となるもう 1 つのコンセプトは、フレームのライフサイクルです。フレームはドキュメント（commit された URL に関連付けられている）をホストします。ドキュメントは変更される可能性がありますが（ナビゲーションなど）、frameId は変更されないため、frameId だけでは、特定のドキュメントで何かが発生したことを関連付けることは困難です。documentId のコンセプトを導入します。これは、ドキュメントごとに固有識別子です。フレームがナビゲートされて新しいドキュメントが開かれると、識別子が変更されます。このフィールドは、ページがライフサイクル状態（事前レンダリング、アクティブ、キャッシュ保存）を変更するタイミングを判断するのに役立ちます。これは、このフィールドが変更されないためです。

遷移タイプと修飾子

webNavigation API の 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 で定義されているものと同じ遷移タイプが使用されます。これらは、"auto_toplevel" の代わりに "start_page" が使用されている点を除き、History API で定義されているものと同じ遷移タイプです（下位互換性のため）。

列挙型

"link"

「入力」

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

「再読み込み」

"キーワード"

"keyword_generated"

メソッド

getAllFrames()

Promise 
chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
): Promise<object[] | undefined>

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

パラメータ

  • 詳細

    オブジェクト

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

    • tabId

      数値

      タブの ID。

  • callback

    function 省略可

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

    (details?: object[]) => void

    • 詳細

      object[] 省略可

      指定されたタブ内のフレームのリスト。指定されたタブ 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<object[] | undefined>

    Chrome 93 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getFrame()

Promise 
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
): Promise<object | undefined>

指定されたフレームに関する情報を取得します。フレームとは、ウェブページの <iframe> または <frame> を指し、タブ ID とフレーム ID で識別されます。

パラメータ

  • 詳細

    オブジェクト

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

    • documentId

      文字列 省略可

      Chrome 106 以降

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

    • frameId

      number 省略可

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

    • processId

      number 省略可

      Chrome 49 以降は非推奨

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

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

    • tabId

      number 省略可

      フレームが存在するタブの ID。

  • callback

    function 省略可

    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<object | undefined>

    Chrome 93 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

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

        数値

        Chrome 50 以降では非推奨

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

        値は -1 です。

      • tabId

        数値

        ナビゲーションが発生しようとしているタブの ID。

      • timeStamp

        数値

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

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

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

        文字列

  • フィルタ

    オブジェクト（省略可）

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

        文字列

  • フィルタ

    オブジェクト（省略可）

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。

  • フィルタ

    オブジェクト（省略可）

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

        文字列

  • フィルタ

    オブジェクト（省略可）

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

        数値

        Chrome 50 以降では非推奨

        このイベントに processId が設定されなくなりました。

        値は -1 です。

      • tabId

        数値

        ナビゲーションが発生したタブの ID。

      • timeStamp

        数値

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

      • URL

        文字列

  • フィルタ

    オブジェクト（省略可）

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

        文字列

  • フィルタ

    オブジェクト（省略可）

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

        文字列

  • フィルタ

    オブジェクト（省略可）

onTabReplaced

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

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

パラメータ

  • callback

    関数

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

    (details: object) => void

    • 詳細

      オブジェクト

      • replacedTabId

        数値

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

      • tabId

        数値

        古いタブを置き換えたタブの ID。

      • timeStamp

        数値

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