説明
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
プロパティは内部用であることが保証されています。
必要があります。あるイベントと別のイベントを比較すると、それらの間の正確なオフセットは示されますが、
拡張機能内の現在の時刻と比較します((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 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
列挙型
「client_redirect」
server_redirect
"forward_back"
"from_address_bar"
TransitionType
ナビゲーションの原因。History API で定義されているのと同じ遷移タイプが使用されます。これらは History API の定義と同じですが、"auto_toplevel"
(下位互換性のため)の代わりに "start_page"
を使用している点が異なります。
列挙型
"リンク"
"typed"
"auto_bookmark"
"auto_subframe"
"manual_subframe"
"generated"
"start_page"
"form_submit"
「再読み込み」
"キーワード"
"keyword_generated"
メソッド
getAllFrames()
chrome.webNavigation.getAllFrames(
details: object,
callback?: function,
)
指定したタブのすべてのフレームに関する情報を取得します。
パラメータ
-
詳細
オブジェクト
すべてのフレームを取得するタブに関する情報。
-
tabId
数値
タブの ID。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。(details?: object[]) => void
-
詳細
オブジェクト [] 省略可
指定されたタブ内のフレームのリスト。指定されたタブ ID が無効な場合は null。
-
documentId
文字列
Chrome 106 以降読み込まれたドキュメントの UUID。
-
documentLifecycleChrome 106 以降
ドキュメントのライフサイクル。
-
errorOccurred
ブール値
このフレーム内の最後のナビゲーションがエラーによって中断された場合(onErrorOccurred イベントが発生したとき)は true。
-
frameId
数値
フレームの ID。0 はメインフレームであることを示します。正の値はサブフレームの ID を示します。
-
frameTypeChrome 106 以降
ナビゲーションが発生したフレームのタイプ。
-
parentDocumentId
文字列(省略可)
Chrome 106 以降このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。
-
parentFrameId
数値
親フレームの ID。メインフレームの場合は
-1
。 -
processId
数値
このフレームのレンダラを実行するプロセスの ID。
-
URL
文字列
現在このフレームに関連付けられている URL。
-
-
戻り値
-
Promise<object[] |未定義>
Chrome 93 以降Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。
getFrame()
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。
-
documentLifecycleChrome 106 以降
ドキュメントのライフサイクル。
-
errorOccurred
ブール値
このフレーム内の最後のナビゲーションがエラーによって中断された場合(onErrorOccurred イベントが発生したとき)は true。
-
frameTypeChrome 106 以降
ナビゲーションが発生したフレームのタイプ。
-
parentDocumentId
文字列(省略可)
Chrome 106 以降このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。
-
parentFrameId
数値
親フレームの ID。メインフレームの場合は
-1
。 -
URL
文字列
frameId によって識別されるフレームが特定のタブのある時点で存在した場合、このフレームに現在関連付けられている URL。URL が特定の frameId に関連付けられているからといって、対応するフレームが引き続き存在するとは限りません。
-
-
戻り値
-
Promise<object |未定義>
Chrome 93 以降Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。
イベント
onBeforeNavigate
chrome.webNavigation.onBeforeNavigate.addListener(
callback: function,
filters?: object,
)
ナビゲーションが行われる際に呼び出されます。
パラメータ
-
関数
callback
パラメータは次のようになります。(details: object) => void
-
オブジェクト
-
Chrome 106 以降
ドキュメントのライフサイクル。
-
数値
0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID は、特定のタブとプロセスに対して一意です。
-
Chrome 106 以降
ナビゲーションが発生したフレームのタイプ。
-
文字列(省略可)
Chrome 106 以降このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。
-
数値
親フレームの ID。メインフレームの場合は
-1
。 -
数値
<ph type="x-smartling-placeholder"></ph> Chrome 50 以降非推奨結果のドキュメントをレンダリングするプロセスは onCommit まで不明なため、このイベントの processId は設定されません。
-1 の値。
-
数値
ナビゲーションが行われる予定のタブの ID。
-
数値
ブラウザがナビゲーションを開始しようとした時刻(エポックからのミリ秒)。
-
文字列
-
-
-
オブジェクト(省略可)
-
移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。
-
onCommitted
chrome.webNavigation.onCommitted.addListener(
callback: function,
filters?: object,
)
ナビゲーションが commit されたときに呼び出されます。ドキュメント(およびドキュメントが参照するリソース(画像やサブフレームなど))はまだダウンロード中である可能性がありますが、ドキュメントの少なくとも一部がサーバーから受信されており、ブラウザが新しいドキュメントへの切り替えを決定しました。
パラメータ
-
callback
関数
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
documentId
文字列
Chrome 106 以降読み込まれたドキュメントの UUID。
-
documentLifecycleChrome 106 以降
ドキュメントのライフサイクル。
-
frameId
数値
0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
-
frameTypeChrome 106 以降
ナビゲーションが発生したフレームのタイプ。
-
parentDocumentId
文字列(省略可)
Chrome 106 以降このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。
-
parentFrameId
数値
Chrome 74 以降親フレームの ID。メインフレームの場合は
-1
。 -
processId
数値
このフレームのレンダラを実行するプロセスの ID。
-
tabId
数値
ナビゲーションが発生するタブの ID。
-
timeStamp
数値
ナビゲーションが commit された時刻(エポックからのミリ秒)。
-
transitionQualifiers
遷移修飾子のリスト。
-
transitionType
ナビゲーションの原因。
-
URL
文字列
-
-
-
フィルタ
オブジェクト(省略可)
-
URL
移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。
-
onCompleted
chrome.webNavigation.onCompleted.addListener(
callback: function,
filters?: object,
)
ドキュメント(参照先のリソースを含む)が完全に読み込まれ、初期化されたときに呼び出されます。
パラメータ
-
callback
関数
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
documentId
文字列
Chrome 106 以降読み込まれたドキュメントの UUID。
-
documentLifecycleChrome 106 以降
ドキュメントのライフサイクル。
-
frameId
数値
0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
-
frameTypeChrome 106 以降
ナビゲーションが発生したフレームのタイプ。
-
parentDocumentId
文字列(省略可)
Chrome 106 以降このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。
-
parentFrameId
数値
Chrome 74 以降親フレームの ID。メインフレームの場合は
-1
。 -
processId
数値
このフレームのレンダラを実行するプロセスの ID。
-
tabId
数値
ナビゲーションが発生するタブの ID。
-
timeStamp
数値
ドキュメントの読み込みが完了した時刻(エポックからのミリ秒)。
-
URL
文字列
-
-
-
フィルタ
オブジェクト(省略可)
-
URL
移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。
-
onCreatedNavigationTarget
chrome.webNavigation.onCreatedNavigationTarget.addListener(
callback: function,
filters?: object,
)
ナビゲーションをホストするために、新しいウィンドウまたは既存のウィンドウ内の新しいタブが作成されたときに呼び出されます。
パラメータ
-
関数
callback
パラメータは次のようになります。(details: object) => void
-
オブジェクト
-
数値
ナビゲーションがトリガーされる sourceTabId を持つフレームの ID。0 はメインフレームを示します。
-
数値
ソースフレームのレンダラを実行するプロセスの ID。
-
数値
ナビゲーションがトリガーされるタブの ID。
-
数値
URL が開かれるタブの ID
-
数値
ブラウザが新しいビューを作成しようとした時刻(エポックからのミリ秒)。
-
文字列
新しいウィンドウで開く URL。
-
-
-
オブジェクト(省略可)
-
移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。
-
onDOMContentLoaded
chrome.webNavigation.onDOMContentLoaded.addListener(
callback: function,
filters?: object,
)
ページの DOM は完全に構築されていますが、参照されているリソースの読み込みは完了しない可能性があるときに呼び出されます。
パラメータ
-
callback
関数
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
documentId
文字列
Chrome 106 以降読み込まれたドキュメントの UUID。
-
documentLifecycleChrome 106 以降
ドキュメントのライフサイクル。
-
frameId
数値
0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
-
frameTypeChrome 106 以降
ナビゲーションが発生したフレームのタイプ。
-
parentDocumentId
文字列(省略可)
Chrome 106 以降このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。
-
parentFrameId
数値
Chrome 74 以降親フレームの ID。メインフレームの場合は
-1
。 -
processId
数値
このフレームのレンダラを実行するプロセスの ID。
-
tabId
数値
ナビゲーションが発生するタブの ID。
-
timeStamp
数値
ページの DOM が完全に構築された時刻(エポックからのミリ秒)。
-
URL
文字列
-
-
-
フィルタ
オブジェクト(省略可)
-
URL
移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。
-
onErrorOccurred
chrome.webNavigation.onErrorOccurred.addListener(
callback: function,
filters?: object,
)
エラーが発生し、ナビゲーションが中断されたときに呼び出されます。ネットワーク エラーが発生したか、ユーザーが移動を中断した場合に発生することがあります。
パラメータ
-
callback
関数
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
documentId
文字列
Chrome 106 以降読み込まれたドキュメントの UUID。
-
documentLifecycleChrome 106 以降
ドキュメントのライフサイクル。
-
エラー
文字列
エラーの説明。
-
frameId
数値
0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
-
frameTypeChrome 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
移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。
-
onHistoryStateUpdated
chrome.webNavigation.onHistoryStateUpdated.addListener(
callback: function,
filters?: object,
)
フレームの履歴が新しい URL に更新されたときに呼び出されます。そのフレームの今後のすべてのイベントで、更新された URL が使用されます。
パラメータ
-
callback
関数
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
documentId
文字列
Chrome 106 以降読み込まれたドキュメントの UUID。
-
documentLifecycleChrome 106 以降
ドキュメントのライフサイクル。
-
frameId
数値
0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
-
frameTypeChrome 106 以降
ナビゲーションが発生したフレームのタイプ。
-
parentDocumentId
文字列(省略可)
Chrome 106 以降このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。
-
parentFrameId
数値
Chrome 74 以降親フレームの ID。メインフレームの場合は
-1
。 -
processId
数値
このフレームのレンダラを実行するプロセスの ID。
-
tabId
数値
ナビゲーションが発生するタブの ID。
-
timeStamp
数値
ナビゲーションが commit された時刻(エポックからのミリ秒)。
-
transitionQualifiers
遷移修飾子のリスト。
-
transitionType
ナビゲーションの原因。
-
URL
文字列
-
-
-
フィルタ
オブジェクト(省略可)
-
URL
移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。
-
onReferenceFragmentUpdated
chrome.webNavigation.onReferenceFragmentUpdated.addListener(
callback: function,
filters?: object,
)
フレームの参照フラグメントが更新されたときに呼び出されます。そのフレームの今後のすべてのイベントで、更新された URL が使用されます。
パラメータ
-
callback
関数
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
documentId
文字列
Chrome 106 以降読み込まれたドキュメントの UUID。
-
documentLifecycleChrome 106 以降
ドキュメントのライフサイクル。
-
frameId
数値
0 はタブ コンテンツ ウィンドウでのナビゲーションを示します。正の値はサブフレームでのナビゲーションを示します。フレーム ID はタブ内で一意です。
-
frameTypeChrome 106 以降
ナビゲーションが発生したフレームのタイプ。
-
parentDocumentId
文字列(省略可)
Chrome 106 以降このフレームを所有する親ドキュメントの UUID。親が存在しない場合は設定されません。
-
parentFrameId
数値
Chrome 74 以降親フレームの ID。メインフレームの場合は
-1
。 -
processId
数値
このフレームのレンダラを実行するプロセスの ID。
-
tabId
数値
ナビゲーションが発生するタブの ID。
-
timeStamp
数値
ナビゲーションが commit された時刻(エポックからのミリ秒)。
-
transitionQualifiers
遷移修飾子のリスト。
-
transitionType
ナビゲーションの原因。
-
URL
文字列
-
-
-
フィルタ
オブジェクト(省略可)
-
URL
移動先の URL が満たす必要がある条件。「スキーム」「ports」UrlFilter のフィールドは無視されます。
-
onTabReplaced
chrome.webNavigation.onTabReplaced.addListener(
callback: function,
)
タブのコンテンツが別の(通常はプリレンダリングされた)タブに置き換わったときに呼び出されます。
パラメータ
-
callback
関数
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
replacedTabId
数値
置き換えられたタブの ID。
-
tabId
数値
古いタブに置き換わったタブの ID。
-
timeStamp
数値
交換が行われた時刻(エポックからのミリ秒)。
-
-