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