サーバー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でクライアントへ渡せます。
文言は呼んだ時点で決まります。リクエストの言語に合わせるなら、描画の中で呼んでください。
フォームで表せないスキーマ（z.recordやタプル、z.number()など）を渡すと、理由を添えてエラーを投げます。
HTMLの属性で表せない検証は、droppedに入ります。本番環境以外では、console.warnでも知らせます。

parseForm

import元 @k8ordo/form/server

送信されたFormDataを、スキーマで検証します。

コードをコピー

parseForm(input: ZodObject | FormDefinition, formData: FormData): ParseResult

引数

inputZodObject | FormDefinition: formFieldsに渡したものと同じスキーマか定義。
formDataFormData: Server Actionが受け取ったFormData。

戻り値

ParseResult — 成功なら{ success: true, data, state }、失敗なら{ success: false, state }。dataは型の付いた値です。

注意

チェックの無いチェックボックスや、同じ名前で送られた複数の値をまとめてから、スキーマに渡します。文字列から数への変換は、スキーマのz.coerceが受け持ちます。
スキーマにある入力欄がFormDataに無いと、エラーを投げます。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: 条件にする入力欄のパス。
equalsstring: fieldを必須にする、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回の検証を見分けるための値。同じ内容の失敗が続いても、別の返事として扱えます。