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

タブ ID

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

タイムスタンプ

OS が個別の Chrome プロセスを処理する際の技術的に奇妙な問題により、ブラウザ自体と拡張機能のプロセスの間で時間のずれが生じる可能性があることに注意することが重要です。つまり、WebNavigation イベントの timeStamp プロパティの 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 は変更されないため、特定のドキュメントで何かが発生したことを frameIds のみに関連付けることは困難です。ドキュメントごとに一意の識別子である documentId のコンセプトを導入します。フレームを移動して新しいドキュメントを開くと、識別子が変更されます。このフィールドは、同じままであるため、ページのライフサイクルの状態（事前レンダリング/アクティブ/キャッシュ済み）のタイミングを判断するのに役立ちます。

遷移タイプと修飾子

webNavigation onCommitted イベントには、transitionType プロパティと transitionQualifiers プロパティがあります。遷移タイプは、ブラウザがこの特定の URL に移動した方法を示す History API で使用されているものと同じです。さらに、ナビゲーションをさらに定義する遷移修飾子を返すこともできます。

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

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

例

この API を試すには、chrome-extension-samples リポジトリから webNavigation API の例をインストールします。

型

TransitionQualifier

Chrome 44 以降

Enum

"client_redirect"

TransitionType

Chrome 44 以降

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

Enum

"auto_subframe"

"manual_subframe"

"start_page"

"keyword_generated"

Methods

getAllFrames()

Promise 
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

        boolean

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

      • frameId

        数値

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

      • frameType

        FrameType

        Chrome 106 以降

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

      • parentDocumentId

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

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

      • processId

        数値

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

      • URL

        文字列

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

戻り値

  • Promise<object[]|undefined>

    Chrome 93 以降

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

getFrame()

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

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

パラメータ

  • 詳細

    オブジェクト

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

    • documentId

      string（省略可）

      Chrome 106 以降

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

    • frameId

      number（省略可）

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

    • processId

      number（省略可）

      Chrome 49 以降でサポートが終了

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

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

    • tabId

      number（省略可）

      フレームが表示されるタブの ID。

  • callback

    関数（省略可）

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

    (details?: object)=>void

    • 詳細

      オブジェクト 省略可

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

      • documentId

        文字列

        Chrome 106 以降

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

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 以降

        ドキュメントが存在するライフサイクル。

      • errorOccurred

        boolean

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

      • frameType

        FrameType

        Chrome 106 以降

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

      • parentDocumentId

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

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

      • URL

        文字列

        このフレームに現在関連付けられている URL（指定のタブ内のいずれかの時点で windowId によって識別されるフレームが存在する場合）。URL が特定の frameId に関連付けられているからといって、対応するフレームがまだ存在するとは限りません。

戻り値

  • Promise<object|undefined>

    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

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

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

      • processId

        数値

        Chrome 50 以降で非推奨

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

        -1 の値です。

      • tabId

        数値

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

      • timeStamp

        数値

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

      • URL

        文字列

  • フィルタ

    オブジェクト 省略可

    • 移動先の URL が満たす必要がある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

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

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

        Chrome 74 以降

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

      • processId

        数値

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

      • tabId

        数値

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

      • timeStamp

        数値

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

      • transitionQualifiers

        TransitionQualifier[]

        遷移修飾子のリスト。

      • transitionType

        TransitionType

        ナビゲーションの原因。

      • URL

        文字列

  • フィルタ

    オブジェクト 省略可

    • 移動先の URL が満たす必要がある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

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

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

        Chrome 74 以降

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

      • processId

        数値

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

      • tabId

        数値

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

      • timeStamp

        数値

        ドキュメントの読み込みが完了した時刻を示すエポックからのミリ秒単位の経過時間。

      • URL

        文字列

  • フィルタ

    オブジェクト 省略可

    • 移動先の URL が満たす必要がある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

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 が満たす必要がある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

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

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

        Chrome 74 以降

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

      • processId

        数値

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

      • tabId

        数値

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

      • timeStamp

        数値

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

      • URL

        文字列

  • フィルタ

    オブジェクト 省略可

    • 移動先の URL が満たす必要がある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onErrorOccurred

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

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

パラメータ

  • callback

    機能

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

    (details: object)=>void

    • 詳細

      オブジェクト

      • documentId

        文字列

        Chrome 106 以降

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

      • Chrome 106 以降

        ドキュメントが存在するライフサイクル。

      • error

        文字列

        エラーの説明。

      • frameId

        数値

        0 はタブ コンテンツ ウィンドウ内で移動することを示し、正の値はサブフレーム内で移動することを表します。フレーム ID はタブ内で一意です。

      • Chrome 106 以降

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

      • parentDocumentId

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

        Chrome 74 以降

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

      • processId

        数値

        Chrome 50 以降で非推奨

        このイベントの processId の設定が解除されました。

        -1 の値です。

      • tabId

        数値

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

      • timeStamp

        数値

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

      • URL

        文字列

  • フィルタ

    オブジェクト 省略可

    • 移動先の URL が満たす必要がある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

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

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

        Chrome 74 以降

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

      • processId

        数値

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

      • tabId

        数値

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

      • timeStamp

        数値

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

      • transitionQualifiers

        TransitionQualifier[]

        遷移修飾子のリスト。

      • transitionType

        TransitionType

        ナビゲーションの原因。

      • URL

        文字列

  • フィルタ

    オブジェクト 省略可

    • 移動先の URL が満たす必要がある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

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

        string（省略可）

        Chrome 106 以降

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

      • parentFrameId

        数値

        Chrome 74 以降

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

      • processId

        数値

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

      • tabId

        数値

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

      • timeStamp

        数値

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

      • transitionQualifiers

        TransitionQualifier[]

        遷移修飾子のリスト。

      • transitionType

        TransitionType

        ナビゲーションの原因。

      • URL

        文字列

  • フィルタ

    オブジェクト 省略可

    • 移動先の URL が満たす必要がある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onTabReplaced

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

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

パラメータ

  • callback

    機能

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

    (details: object)=>void

    • 詳細

      オブジェクト

      • replacedTabId

        数値

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

      • tabId

        数値

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

      • timeStamp

        数値

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