Thinkstream

リンクの作成に加えて、JavaScript からプログラム的に Inertia の訪問／リクエストを手動で行うことも可能です。これは router.visit() メソッドを使用して実現します。

ただし、一般的には Inertia が提供するショートカットリクエストメソッドのいずれかを使用する方が便利です。これらのメソッドは、router.visit() と同じオプションをすべて共有します。

reload() メソッドは、preserveState と preserveScroll の両方を自動的に true に設定して現在のページを訪問する、便利なショートハンドメソッドです。現在のページのデータを単に再読み込みしたい場合に最適です。

メソッド

手動で訪問を行う際には、method オプションを使用してリクエストの HTTP メソッドを get、post、put、patch、delete に設定できます。デフォルトのメソッドは get です。

Laravel では、put や patch によるファイルアップロードはサポートされていません。代わりに、post を使用し、_method フィールドに put または patch を設定してリクエストを行ってください。これはフォームメソッドスプーフィングと呼ばれます。

Wayfinder

v2.1.2+

Wayfinder を使用している場合、生成されたオブジェクトをそのまま任意の router メソッドに渡すことができます。router は Wayfinder オブジェクトから HTTP メソッドと URL を自動的に推測します。

Wayfinder オブジェクトを渡しつつ method オプションも指定した場合は、method オプションが優先されます。

データ

data オプションを使用して、リクエストにデータを追加できます。

利便性のため、get()、post()、put()、patch() メソッドは、いずれも第 2 引数として data を受け取ります。

カスタムヘッダー

headers オプションを使用すると、リクエストにカスタムヘッダーを追加できます。

Inertia が内部で状態をサーバーに伝えるために使用するヘッダーは優先されるため、上書きすることはできません。

グローバル訪問オプション

Inertia アプリの初期化時に visitOptions コールバックを設定することで、すべてのリクエストに対して訪問オプションをグローバルに変更できます。このコールバックは対象 URL と現在の訪問オプションを受け取り、上書きしたいオプションを含むオブジェクトを返す必要があります。

ファイルアップロード

ファイルを含む訪問／リクエストを行う場合、Inertia はリクエストデータを自動的に FormData オブジェクトへ変換します。常に FormData オブジェクトを使用したい場合は、forceFormData オプションを使用できます。

ファイルアップロードの詳細については、専用のファイルアップロードドキュメントを参照してください。

ブラウザ履歴

訪問を行うと、Inertia は自動的にブラウザ履歴に新しいエントリを追加します。ただし、replace オプションを true に設定することで、現在の履歴エントリを置き換えることも可能です。

同じ URL への訪問では、replace は自動的に true に設定されます。

クライアントサイド訪問

router.push および router.replace メソッドを使用して、クライアントサイドのみの訪問を行うことができます。この方法は、サーバーリクエストを行わずにブラウザ履歴を更新したい場合に便利です。

すべてのパラメータは任意です。デフォルトでは、渡されたすべてのパラメータ（errorBag を除く）が現在のページとマージされます。つまり、現在のページの URL、コンポーネント、props を上書きする責任はあなたにあります。

現在のページの props にアクセスする必要がある場合は、props オプションに関数を渡すことができます。この関数は現在のページの props を引数として受け取り、新しい props を返す必要があります。

errorBag オプションを使用すると、onError コールバックでバリデーションエラーを処理する際に使用するエラーバッグを指定できます。

クライアントサイドで push するルートは、必ずサーバー側でも定義されている必要があります。ユーザーがページをリフレッシュした場合、サーバーはそのページをどのようにレンダリングするかを把握している必要があります。

Prop ヘルパー

Inertia は、サーバーリクエストを行わずにページの props を更新するための 3 つのヘルパーメソッドを提供しています。これらのメソッドは router.replace() のショートカットであり、preserveScroll と preserveState を自動的に true に設定します。

これら 3 つのメソッドはいずれも、ネストされた props に対してドット記法をサポートしており、現在の値を第 1 引数、現在のページの props を第 2 引数として受け取るコールバック関数を指定することもできます。

状態の保持

デフォルトでは、同じページへの訪問は新しいページコンポーネントインスタンスを作成します。これにより、フォーム入力、スクロール位置、フォーカス状態などのローカル状態は失われます。

しかし、状況によってはページコンポーネントの状態を保持する必要があります。たとえば、フォームを送信した際に、サーバー側でバリデーションエラーが発生した場合、フォームデータを保持する必要があります。

このため、post、put、patch、delete、reload メソッドは、デフォルトで preserveState オプションを true に設定しています。

get メソッド使用時にコンポーネントの状態を保持したい場合は、preserveState オプションを true に設定してください。

レスポンスにバリデーションエラーが含まれている場合のみ状態を保持したい場合は、preserveState オプションを "errors" に設定してください。

レスポンスに基づいて preserveState オプションを遅延評価するために、コールバックを指定することもできます。

スクロールの保持

ページ間を移動する際、Inertia はデフォルトのブラウザ挙動を模倣し、ドキュメントボディ（および定義されたスクロール領域）のスクロール位置を自動的にページ上部へリセットします。

この挙動を無効にしたい場合は、preserveScroll オプションを true に設定してください。

レスポンスにバリデーションエラーが含まれている場合のみスクロール位置を保持したい場合は、preserveScroll オプションを "errors" に設定してください。

レスポンスに基づいて preserveScroll オプションを遅延評価するために、コールバックを指定することもできます。

この機能の詳細については、スクロール管理ドキュメントを参照してください。

パーシャルリロード

only オプションを使用すると、同じページへの後続の訪問時に、サーバーから props（データ）の一部のみをリクエストできます。これにより、ページが更新を必要としないデータを取得する必要がなくなり、アプリケーションをより効率的にできます。

この機能の詳細については、パーシャルリロードドキュメントを参照してください。

ビュートランジション

viewTransition オプションを true に設定することで、訪問時にビュートランジションを有効にできます。これにより、ブラウザの View Transitions API を使用してページ遷移をアニメーション化します。

訪問のキャンセル

キャンセルトークンを使用して訪問をキャンセルできます。Inertia は訪問を行う前に、自動的にキャンセルトークンを生成し、onCancelToken() コールバックを通じて提供します。

訪問がキャンセルされた場合、onCancel() および onFinish() イベントコールバックが実行されます。

イベントコールバック

Inertia のグローバルイベントに加えて、訪問ごとに使用できる複数のイベントコールバックが提供されています。

onBefore() コールバックから false を返すと、訪問はキャンセルされます。

また、onSuccess() および onError() コールバックから Promise を返すことも可能です。その場合、Promise が解決されるまで「finish」イベントは遅延されます。