このページは Cloud Translation API によって翻訳されました。

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 の後でも）発生する可能性があります。

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

また、プロビジョニングロード中にプロセスが数回切り替えられる場合もあります。これは、負荷が別のサイトにリダイレクトされた場合に発生します。この場合、最終的な onCommitted イベントを受信するまで、onBeforeNavigate イベントと onErrorOccurred イベントが繰り返し送信されます。

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

切り替え効果のタイプと修飾子

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

次の移行修飾子があります。

移行の適格性	説明
"client_redirect"	ナビゲーション中に、ページ上の JavaScript または meta refresh タグが原因で 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 以降

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

列挙型

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"generated"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

メソッド

getAllFrames()

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

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

パラメータ

詳細

オブジェクト

すべてのフレームを取得するタブに関する情報。
- tabId
  
  数値
  
  タブの ID。

戻り値

Promise<object[] | undefined>

Chrome 93 以降

getFrame()

chrome.webNavigation.getFrame(
  details: object,
): 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。

戻り値

Promise<object | undefined>

Chrome 93 以降

イベント

onBeforeNavigate

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

ナビゲーションが開始されようとしているときに呼び出されます。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(details: object) => void
```
- 詳細
  
  オブジェクト
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 以降
    
    ドキュメントのライフサイクル。
  - frameId
    
    数値
    
    0 はタブコンテンツウィンドウでのナビゲーションを示し、正の値はサブフレームでのナビゲーションを示します。フレーム ID は、特定のタブとプロセスに対して一意です。
  - frameType
    
    extensionTypes.FrameType
    
    Chrome 106 以降
    
    ナビゲーションが発生したフレームのタイプ。
  - parentDocumentId
    
    文字列省略可
    
    Chrome 106 以降
    
    このフレームを所有する親ドキュメントの UUID。親がない場合、この値は設定されません。
  - parentFrameId
    
    数値
    
    親フレームの ID。これがメインフレームの場合は -1。
  - processId
    
    数値
    
    Chrome 50 以降で非推奨
    
    結果のドキュメントをレンダリングするプロセスは onCommit まで不明であるため、このイベントの processId は設定されなくなりました。
    値 -1。
  - tabId
    
    数値
    
    ナビゲーションが実行されようとしているタブの ID。
  - timeStamp
    
    数値
    
    ブラウザがナビゲーションを開始しようとした時間（エポックからのミリ秒単位）。
  - URL
    
    文字列
フィルタ

オブジェクト省略可
- URL
  
  events.UrlFilter[]
  
  移動先の URL が満たす必要のある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onCommitted

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

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

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(details: object) => void
```
- 詳細
  
  オブジェクト
  - documentId
    
    文字列
    
    Chrome 106 以降
    
    読み込まれたドキュメントの UUID。
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 以降
    
    ドキュメントのライフサイクル。
  - frameId
    
    数値
    
    0 はタブコンテンツウィンドウでのナビゲーションを示し、正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
  - frameType
    
    extensionTypes.FrameType
    
    Chrome 106 以降
    
    ナビゲーションが発生したフレームのタイプ。
  - parentDocumentId
    
    文字列省略可
    
    Chrome 106 以降
    
    このフレームを所有する親ドキュメントの UUID。親がない場合、この値は設定されません。
  - parentFrameId
    
    数値
    
    Chrome 74 以降
    
    親フレームの ID。これがメインフレームの場合は -1。
  - processId
    
    数値
    
    このフレームのレンダラを実行するプロセスの ID。
  - tabId
    
    数値
    
    ナビゲーションが発生したタブの ID。
  - timeStamp
    
    数値
    
    ナビゲーションがコミットされた時刻（エポックからのミリ秒単位）。
  - transitionQualifiers
    
    TransitionQualifier[]
    
    遷移修飾子のリスト。
  - transitionType
    
    TransitionType
    
    ナビゲーションの原因。
  - URL
    
    文字列
フィルタ

オブジェクト省略可
- URL
  
  events.UrlFilter[]
  
  移動先の URL が満たす必要のある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onCompleted

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

参照しているリソースを含め、ドキュメントが完全に読み込まれて初期化されたときに発生します。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(details: object) => void
```
- 詳細
  
  オブジェクト
  - documentId
    
    文字列
    
    Chrome 106 以降
    
    読み込まれたドキュメントの UUID。
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 以降
    
    ドキュメントのライフサイクル。
  - frameId
    
    数値
    
    0 はタブコンテンツウィンドウでのナビゲーションを示し、正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
  - frameType
    
    extensionTypes.FrameType
    
    Chrome 106 以降
    
    ナビゲーションが発生したフレームのタイプ。
  - parentDocumentId
    
    文字列省略可
    
    Chrome 106 以降
    
    このフレームを所有する親ドキュメントの UUID。親がない場合、この値は設定されません。
  - parentFrameId
    
    数値
    
    Chrome 74 以降
    
    親フレームの ID。これがメインフレームの場合は -1。
  - processId
    
    数値
    
    このフレームのレンダラを実行するプロセスの ID。
  - tabId
    
    数値
    
    ナビゲーションが発生したタブの ID。
  - timeStamp
    
    数値
    
    ドキュメントの読み込みが完了した時間（エポックからのミリ秒単位）。
  - URL
    
    文字列
フィルタ

オブジェクト省略可
- URL
  
  events.UrlFilter[]
  
  移動先の 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
  
  events.UrlFilter[]
  
  移動先の URL が満たす必要のある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onDOMContentLoaded

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

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

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(details: object) => void
```
- 詳細
  
  オブジェクト
  - documentId
    
    文字列
    
    Chrome 106 以降
    
    読み込まれたドキュメントの UUID。
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 以降
    
    ドキュメントのライフサイクル。
  - frameId
    
    数値
    
    0 はタブコンテンツウィンドウでのナビゲーションを示し、正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
  - frameType
    
    extensionTypes.FrameType
    
    Chrome 106 以降
    
    ナビゲーションが発生したフレームのタイプ。
  - parentDocumentId
    
    文字列省略可
    
    Chrome 106 以降
    
    このフレームを所有する親ドキュメントの UUID。親がない場合、この値は設定されません。
  - parentFrameId
    
    数値
    
    Chrome 74 以降
    
    親フレームの ID。これがメインフレームの場合は -1。
  - processId
    
    数値
    
    このフレームのレンダラを実行するプロセスの ID。
  - tabId
    
    数値
    
    ナビゲーションが発生したタブの ID。
  - timeStamp
    
    数値
    
    ページの DOM が完全に構築された時刻（エポックからのミリ秒単位）。
  - URL
    
    文字列
フィルタ

オブジェクト省略可
- URL
  
  events.UrlFilter[]
  
  移動先の URL が満たす必要のある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onErrorOccurred

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

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

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(details: object) => void
```
- 詳細
  
  オブジェクト
  - documentId
    
    文字列
    
    Chrome 106 以降
    
    読み込まれたドキュメントの UUID。
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 以降
    
    ドキュメントのライフサイクル。
  - エラー
    
    文字列
    
    エラーの説明。
  - frameId
    
    数値
    
    0 はタブコンテンツウィンドウでのナビゲーションを示し、正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
  - frameType
    
    extensionTypes.FrameType
    
    Chrome 106 以降
    
    ナビゲーションが発生したフレームのタイプ。
  - parentDocumentId
    
    文字列省略可
    
    Chrome 106 以降
    
    このフレームを所有する親ドキュメントの UUID。親がない場合、この値は設定されません。
  - parentFrameId
    
    数値
    
    Chrome 74 以降
    
    親フレームの ID。これがメインフレームの場合は -1。
  - processId
    
    数値
    
    Chrome 50 以降で非推奨
    
    このイベントの processId は設定されなくなりました。
    値 -1。
  - tabId
    
    数値
    
    ナビゲーションが発生したタブの ID。
  - timeStamp
    
    数値
    
    エラーが発生した時刻（エポックからのミリ秒数）。
  - URL
    
    文字列
フィルタ

オブジェクト省略可
- URL
  
  events.UrlFilter[]
  
  移動先の URL が満たす必要のある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onHistoryStateUpdated

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

フレームの履歴が新しい URL に更新されたときに発生します。そのフレームの以降のすべてのイベントで、更新された URL が使用されます。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(details: object) => void
```
- 詳細
  
  オブジェクト
  - documentId
    
    文字列
    
    Chrome 106 以降
    
    読み込まれたドキュメントの UUID。
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 以降
    
    ドキュメントのライフサイクル。
  - frameId
    
    数値
    
    0 はタブコンテンツウィンドウでのナビゲーションを示し、正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
  - frameType
    
    extensionTypes.FrameType
    
    Chrome 106 以降
    
    ナビゲーションが発生したフレームのタイプ。
  - parentDocumentId
    
    文字列省略可
    
    Chrome 106 以降
    
    このフレームを所有する親ドキュメントの UUID。親がない場合、この値は設定されません。
  - parentFrameId
    
    数値
    
    Chrome 74 以降
    
    親フレームの ID。これがメインフレームの場合は -1。
  - processId
    
    数値
    
    このフレームのレンダラを実行するプロセスの ID。
  - tabId
    
    数値
    
    ナビゲーションが発生したタブの ID。
  - timeStamp
    
    数値
    
    ナビゲーションがコミットされた時刻（エポックからのミリ秒単位）。
  - transitionQualifiers
    
    TransitionQualifier[]
    
    遷移修飾子のリスト。
  - transitionType
    
    TransitionType
    
    ナビゲーションの原因。
  - URL
    
    文字列
フィルタ

オブジェクト省略可
- URL
  
  events.UrlFilter[]
  
  移動先の URL が満たす必要のある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onReferenceFragmentUpdated

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

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

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(details: object) => void
```
- 詳細
  
  オブジェクト
  - documentId
    
    文字列
    
    Chrome 106 以降
    
    読み込まれたドキュメントの UUID。
  - documentLifecycle
    
    extensionTypes.DocumentLifecycle
    
    Chrome 106 以降
    
    ドキュメントのライフサイクル。
  - frameId
    
    数値
    
    0 はタブコンテンツウィンドウでのナビゲーションを示し、正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
  - frameType
    
    extensionTypes.FrameType
    
    Chrome 106 以降
    
    ナビゲーションが発生したフレームのタイプ。
  - parentDocumentId
    
    文字列省略可
    
    Chrome 106 以降
    
    このフレームを所有する親ドキュメントの UUID。親がない場合、この値は設定されません。
  - parentFrameId
    
    数値
    
    Chrome 74 以降
    
    親フレームの ID。これがメインフレームの場合は -1。
  - processId
    
    数値
    
    このフレームのレンダラを実行するプロセスの ID。
  - tabId
    
    数値
    
    ナビゲーションが発生したタブの ID。
  - timeStamp
    
    数値
    
    ナビゲーションがコミットされた時刻（エポックからのミリ秒単位）。
  - transitionQualifiers
    
    TransitionQualifier[]
    
    遷移修飾子のリスト。
  - transitionType
    
    TransitionType
    
    ナビゲーションの原因。
  - URL
    
    文字列
フィルタ

オブジェクト省略可
- URL
  
  events.UrlFilter[]
  
  移動先の URL が満たす必要のある条件。このイベントでは、UrlFilter の「schemes」フィールドと「ports」フィールドは無視されます。

onTabReplaced

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

タブの内容が別のタブ（通常は事前にレンダリングされたタブ）に置き換えられたときに発生します。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(details: object) => void
```
- 詳細
  
  オブジェクト
  - replacedTabId
    
    数値
    
    置き換えられたタブの ID。
  - tabId
    
    数値
    
    古いタブを置き換えたタブの ID。
  - timeStamp
    
    数値
    
    置換が行われた時間（エポックからのミリ秒単位）。

chrome.webNavigation コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

説明

権限

コンセプトと使用方法

イベントの順序

webRequest イベントとの関係

タブ ID

タイムスタンプ

フレーム ID

切り替え効果のタイプと修飾子

例

型

TransitionQualifier

列挙型

TransitionType

列挙型

メソッド

getAllFrames()

パラメータ

戻り値

getFrame()

パラメータ

戻り値

イベント

onBeforeNavigate

パラメータ

onCommitted

パラメータ

onCompleted

パラメータ

onCreatedNavigationTarget

パラメータ

onDOMContentLoaded

パラメータ

onErrorOccurred

パラメータ

onHistoryStateUpdated

パラメータ

onReferenceFragmentUpdated

パラメータ

onTabReplaced

パラメータ

chrome.webNavigation