Svelte入門：リファレンス $app/forms -Vol.2-

よっしー

こんにちは。よっしーです(^^)

今日は、SvelteKitのリファレンスについて解説しています。

背景
$app/forms
1. deserialize
  1. 解説
2. enhance
  1. 解説
おわりに

背景

SvelteKitのリファレンスについて調査する機会がありましたので、その時の内容を備忘として記事に残しました。

$app/forms

import { applyAction, deserialize, enhance } from '$app/forms';

この行は $app/forms モジュールから3つの関数をインポートしています。このモジュールは SvelteKit でフォーム処理を強化するためのユーティリティを提供します。

applyAction – サーバーアクションの結果をクライアント側で適用するための関数です。フォーム送信後のリダイレクト、ページ更新、フォームリセットなどの処理を行います。
deserialize – サーバーから返されたシリアライズされたデータをクライアント側で元の形式に戻す関数です。通常はフォームアクションから返されたデータを処理する際に使用します。
enhance – HTML フォームを JavaScript で強化するための関数です。これを使用すると、フォーム送信をインターセプトして AJAX リクエストとして処理したり、送信中のローディング状態を管理したりできます。

これらの関数は特に SvelteKit のフォームアクション機能と組み合わせて使用され、従来のフォーム送信をより柔軟で使いやすいものにします。クライアントサイドの JavaScript が有効な場合でもフォームが機能するプログレッシブエンハンスメントのアプローチを実現します。

deserialize

この関数はフォーム送信からのレスポンスをデシリアライズするために使用します。

使用例：

import { deserialize } from '$app/forms';

async function handleSubmit(event) {
	const response = await fetch('/form?/action', {
		method: 'POST',
		body: new FormData(event.target)
	});

	const result = deserialize(await response.text());
	// ...
}

function deserialize
	Success extends Record<string, unknown> | undefined,
	Failure extends Record<string, unknown> | undefined
>(
	result: string
): import('@sveltejs/kit').ActionResult<Success, Failure>;

解説

この関数は、サーバーサイドのフォームアクションから返されたシリアライズされた結果を、クライアント側で使いやすいオブジェクト形式に変換します。

パラメータ：

result: string – サーバーからの応答テキスト（通常はシリアライズされたJSON）

戻り値：

ActionResult<Success, Failure> – デシリアライズされたアクション結果オブジェクト

この関数は主に、通常の fetch API を使用してフォームアクションにアクセスする場合に使用されます。SvelteKit の enhance 関数を使用せずにカスタムフォーム処理を実装する際に役立ちます。

使用例では、フォームを手動で送信し、レスポンスをテキストとして取得した後、deserialize を使用してSvelteKitのアクション結果オブジェクトに変換しています。このオブジェクトには通常、type（成功/リダイレクト/エラーなど）や、サーバーから返されたデータが含まれます。

enhance

この関数は、JavaScriptがなくても機能する <form> 要素を強化します。 submit 関数は、指定された FormData と、トリガーされるべき action を使用して送信時に呼び出されます。もし cancel が呼ばれると、フォームは送信されません。別の送信が開始された場合、controller を使用して送信をキャンセルすることができます。関数が返される場合、その関数はサーバーからのレスポンスで呼び出されます。何も返されない場合は、フォールバックが使用されます。この関数またはその戻り値が設定されていない場合、以下のようになります：

フォームと同じページにアクションがある場合、返されたデータで form プロパティを更新するフォールバック処理を行います
page.status を更新します
リダイレクトレスポンスのない成功した送信の場合、<form> 要素をリセットし、すべてのデータを無効化します
リダイレクトレスポンスの場合、リダイレクトします
予期しないエラーの場合、最も近いエラーページにリダイレクトしますコールバック付きのカスタム関数を提供し、デフォルトの動作を使用したい場合は、コールバック内で update を呼び出します。これはオプションオブジェクトを受け入れます
成功した送信後に <form> の値をリセットしたくない場合は reset: false
送信後にアクションが invalidateAll を呼び出さないようにする場合は invalidateAll: false

function enhance
	Success extends Record<string, unknown> | undefined,
	Failure extends Record<string, unknown> | undefined
>(
	form_element: HTMLFormElement,
	submit?: import('@sveltejs/kit').SubmitFunction
		Success,
		Failure
	>
): {
	destroy(): void;
};

解説

この関数は SvelteKit のフォーム処理におけるプログレッシブエンハンスメントを実現するための中心的な機能です。通常の HTML フォームに JavaScript による強化を加えます。

パラメータ：

form_element: HTMLFormElement – 強化するフォーム要素
submit?: SubmitFunction<Success, Failure> – カスタムの送信ハンドラ関数（オプション）

戻り値：

{ destroy(): void; } – クリーンアップ用のメソッドを持つオブジェクト

この関数の主な特徴：

プログレッシブエンハンスメント – JavaScript が無効な場合でも基本的なフォーム機能が動作します
カスタマイズ可能な送信処理 – submit パラメータで独自の送信ロジックを実装できます
デフォルトの動作 – カスタム処理が指定されていない場合、SvelteKit の標準的なフォーム処理が実行されます
クリーンアップ – 返される destroy メソッドを使用して、コンポーネントのアンマウント時などにフォームの強化をクリーンアップできます

通常は Svelte コンポーネント内で use:enhance ディレクティブとして使用されることが多いです：

<form method="POST" use:enhance>
  <!-- フォームの内容 -->
</form>

またはカスタム処理を追加する場合：

<form method="POST" use:enhance={({ form, data, action, cancel, submitter }) => {
  // 送信時の前処理
  
  return ({ result, update }) => {
    // 結果処理
    
    // デフォルト処理を実行
    update();
  };
}}>
  <!-- フォームの内容 -->
</form>