chrome.webNavigation (original) (raw)

説明

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

列挙型

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

ナビゲーションの原因。履歴 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>

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

パラメータ

戻り値

getFrame()

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

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

パラメータ

戻り値

イベント

onBeforeNavigate

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

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

パラメータ

onCommitted

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

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

パラメータ

onCompleted

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

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

パラメータ

onCreatedNavigationTarget

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

ナビゲーションをホストするために新しいウィンドウ、または既存のウィンドウの新しいタブが作成されたときに発生します。

パラメータ

onDOMContentLoaded

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

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

パラメータ

onErrorOccurred

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

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

パラメータ

onHistoryStateUpdated

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

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

パラメータ

onReferenceFragmentUpdated

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

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

パラメータ

onTabReplaced

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

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

パラメータ