thinkstream

イベント

Inertia は、ライブラリのさまざまなライフサイクルイベントに「フック」できるイベントシステムを提供します。

リスナーの登録

イベントリスナーを登録するには、router.on() メソッドを使用します。

内部的には Inertia はネイティブのブラウザーイベントを使用しているため、すでに慣れ親しんでいる一般的なイベントメソッドを使って Inertia のイベントとやり取りすることもできます。ただし、イベント名の先頭に inertia: を付ける必要があります。

リスナーの削除

イベントリスナーを登録すると、Inertia は自動的に、そのリスナーを削除するために呼び出せるコールバックを返します。

フックと組み合わせることで、コンポーネントがアンマウントされた際に自動的にイベントリスナーを削除できます。

あるいは、ネイティブのブラウザーイベントを使用している場合は、removeEventListener() を使ってイベントリスナーを削除できます。

イベントのキャンセル

before、exception、invalid などの一部のイベントはキャンセルをサポートしており、Inertia のデフォルト動作を防ぐことができます。ネイティブイベントと同様に、いずれか 1 つのイベントリスナーが event.preventDefault() を呼び出すと、そのイベントはキャンセルされます。

利便性のため、router.on() を使ってイベントリスナーを登録している場合は、リスナーから false を返すことでイベントをキャンセルできます。

なお、ブラウザーはネイティブの popstate イベントのキャンセルを許可していないため、Inertia.js の使用中に履歴の前後移動を防ぐことはできません。

Before

before イベントは、サーバーへのリクエストが送信される直前に発火します。これは、訪問をインターセプトするのに役立ちます。

このイベントの主な目的は、訪問が実行されるのを防ぐことです。

Start

start イベントは、サーバーへのリクエストが開始されたときに発火します。これは、ローディングインジケーターを表示するのに便利です。

start イベントはキャンセルできません。

Progress

progress イベントは、ファイルアップロード中に進捗が増加するたびに発火します。

progress イベントはキャンセルできません。

Success

success イベントは、バリデーションエラーが存在しない場合に、ページ訪問が成功すると発火します。ただし、履歴による訪問は含まれません。

success イベントはキャンセルできません。

Flash

v2.3.3+

flash イベントは、サーバーから フラッシュデータ を受信したときに発火します。これは、トースト通知を表示したり、一時的なデータを中央集約的な場所で処理したりするのに便利です。

flash イベントはキャンセルできません。パーシャルリロード では、フラッシュデータが変更された場合にのみこのイベントが発火します。

Error

error イベントは、「成功した」ページ訪問においてバリデーションエラーが存在する場合に発火します。

error イベントはキャンセルできません。

Invalid

invalid イベントは、HTML や通常の JSON レスポンスなど、非 Inertia レスポンスがサーバーから返されたときに発火します。有効な Inertia レスポンスとは、X-Inertia ヘッダーが true に設定され、ページオブジェクト を含む json ペイロードを持つレスポンスのことです。

このイベントは、200、400、500 を含むすべてのレスポンスタイプで発火します。

invalid イベントをキャンセルすることで、Inertia が非 Inertia レスポンス用のモーダルを表示するのを防ぐことができます。

Exception

exception イベントは、ネットワーク中断などの予期しない XHR エラーが発生した場合に発火します。また、ページコンポーネントの解決時に生成されたエラーに対しても発火します。

exception イベントをキャンセルすることで、エラーがスローされるのを防ぐことができます。

このイベントは、400 や 500 レベルのレスポンスを受け取った XHR リクエストや、非 Inertia レスポンスに対しては発火しません。これらの状況は Inertia によって別の方法で処理されます。詳細については、エラーハンドリングのドキュメント を参照してください。

Finish

finish イベントは、「成功」「失敗」を問わず、XHR リクエストが完了した後に発火します。これは、ローディングインジケーターを非表示にするのに便利です。

finish イベントはキャンセルできません。

navigate イベントは、ページ訪問が成功したとき、および履歴を通じてナビゲーションしたときに発火します。

navigate イベントはキャンセルできません。

Prefetching

prefetching イベントは、ルーターがページのプリフェッチを開始したときに発火します。

prefetching イベントはキャンセルできません。

Prefetched

prefetched イベントは、ルーターがページのプリフェッチに成功したときに発火します。

prefetched イベントはキャンセルできません。

イベントコールバック

このページ全体で説明しているグローバルイベントに加えて、Inertia では、手動で Inertia の訪問を行う際に発火するいくつかの イベントコールバック も提供されています。