サーバーAPI
@k8ordo/form/serverから使える関数と型の一覧です。どれもサーバーで呼ぶので、zodはブラウザに送られません。
このページの内容
formFields
import元 @k8ordo/form/server
スキーマから入力欄ごとの属性、文言、ルールを作ります。
formFields(input: ZodObject | FormDefinition): FormFields引数
inputZodObject | FormDefinition- zodのオブジェクトスキーマ、または
defineFormで作った定義。
戻り値
FormFields — fields、arrays、rulesとdroppedを持つJSON。そのままuseFormに渡します。
注意
- Server Componentの中か、モジュールのトップレベルで呼びます。戻り値はJSONなので、propsでClient Componentに渡せます。
- 文言は呼んだ時点で決まります。リクエストの言語に合わせるなら、描画の中で呼びます。
- フォームで表せないスキーマ(
z.recordやタプル、z.number()など)を渡すと、[@k8ordo/form] 'フィールド名': 理由のエラーになります。 - HTMLの属性で表せない検証は
droppedに入り、サーバーだけで行われます。本番環境以外ではconsole.warnでも知らせます。
parseForm
import元 @k8ordo/form/server
送信されたFormDataを、スキーマで検証します。
parseForm(input: ZodObject | FormDefinition, formData: FormData): ParseResult引数
inputZodObject | FormDefinitionformFieldsに渡したものと同じスキーマか定義。formDataFormData- Server Actionが受け取った
FormData。
戻り値
ParseResult — 成功なら{ success: true, data, state }、失敗なら{ success: false, state }。dataはスキーマの出力の型です。
注意
- 送信された値はすべて文字列です。数への変換は、スキーマの
z.coerceで行います。 - チェックの無いチェックボックスは
falseに、同じ名前で送られた複数の値は配列になります。parseFormは、この形にしてからスキーマに渡します。 - スキーマにあるフィールドが
FormDataに無いと、[@k8ordo/form] スキーマにあるフィールドが送信されていません: フィールド名のエラーになります。inputを入力欄に渡し忘れたときに出ます。ラジオボタンと<select>、チェックボックスは、何も選ばなければ値を送らないので対象外です。 - パスワードとファイルの値は、
state.valuesに入りません。
defineForm
import元 @k8ordo/form/server
スキーマに、複数の入力欄にまたがるルールを添えます。
defineForm(schema: ZodObject, rules?: Rule[]): FormDefinition引数
schemaZodObject- zodのオブジェクトスキーマ。
rulesRule[]sameAs、minChecked、requiredWhenで作ったルール。入力欄のパスは型で確かめられます。
戻り値
FormDefinition — スキーマの代わりに、formFieldsとparseFormへ渡します。
注意
- ブラウザとサーバーは、同じ処理でルールを判定します。1つの入力欄が複数のルールを満たさないときは、先に宣言したルールの文言が表示されます。
sameAs
import元 @k8ordo/form/server
fieldの値がotherの値と同じであることを求めます。パスワードの確認に使います。
sameAs(field: FieldPath, other: FieldPath, message: RuleMessage): Rule引数
fieldFieldPath- ルールを適用する入力欄のパス。ルールに違反したときのエラーは、この入力欄に表示されます。
otherFieldPath- 比べる相手の入力欄のパス。
messagestring | (() => string)- ルールを満たさないときの文言。関数を渡すと、エラーを報告するときに呼ばれます。
戻り値
Rule — defineFormの2つ目の引数に並べます。
minChecked
import元 @k8ordo/form/server
同じ名前のチェックボックスのうち、min個以上がチェックされていることを求めます。
minChecked(field: FieldPath, min: number, message: RuleMessage): Rule引数
fieldFieldPath- ルールを適用する入力欄のパス。ルールに違反したときのエラーは、この入力欄に表示されます。
minnumber- チェックが必要な最小の数。
messagestring | (() => string)- ルールを満たさないときの文言。関数を渡すと、エラーを報告するときに呼ばれます。
戻り値
Rule — defineFormの2つ目の引数に並べます。
requiredWhen
import元 @k8ordo/form/server
whenの値がequalsであるあいだだけ、fieldを必須にします。
requiredWhen(field: FieldPath, when: FieldPath, equals: string, message: RuleMessage): Rule引数
fieldFieldPath- ルールを適用する入力欄のパス。ルールに違反したときのエラーは、この入力欄に表示されます。
whenFieldPath- 条件にする入力欄のパス。
equalsstringfieldを必須にする、whenの値。messagestring | (() => string)- ルールを満たさないときの文言。関数を渡すと、エラーを報告するときに呼ばれます。
戻り値
Rule — defineFormの2つ目の引数に並べます。
FormState
import元 @k8ordo/form/server
Server Actionがフォームに返す値です。parseFormが作り、useFormが読みます。
type FormState = {
errors?: Record<string, string>;
values?: Record<string, string | string[]>;
rows?: Record<string, number>;
formError?: string;
token?: string;
};フィールド
errorsRecord<string, string>- 入力欄ごとのエラー。キーは
items[1].nameのようなパスです。 valuesRecord<string, string | string[]>- 送信された値。送信に失敗したあとは、入力欄の既定値になります。
rowsRecord<string, number>- 配列ごとの行数。JavaScriptが無くても、送信時と同じ数の行で描画できます。
formErrorstring- どの入力欄にも属さないエラー。
tokenstring- 1回の検証を見分けるための値。同じ内容の失敗が続いても、別の応答として扱えます。