@k8ordo/form

サーバーAPI

@k8ordo/form/serverから使える関数と型の一覧です。どれもサーバーで呼ぶので、zodはブラウザに送られません。

このページの内容

formFields

import元 @k8ordo/form/server

スキーマから入力欄ごとの属性、文言、ルールを作ります。

ts
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を、スキーマで検証します。

ts
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で行います。
  • チェックの無いチェックボックスはfalseに、同じ名前で送られた複数の値は配列になります。parseFormは、この形にしてからスキーマに渡します。
  • スキーマにあるフィールドがFormDataに無いと、[@k8ordo/form] スキーマにあるフィールドが送信されていません: フィールド名のエラーになります。inputを入力欄に渡し忘れたときに出ます。ラジオボタンと<select>、チェックボックスは、何も選ばなければ値を送らないので対象外です。
  • パスワードとファイルの値は、state.valuesに入りません。

defineForm

import元 @k8ordo/form/server

スキーマに、複数の入力欄にまたがるルールを添えます。

ts
defineForm(schema: ZodObject, rules?: Rule[]): FormDefinition

引数

schemaZodObject
zodのオブジェクトスキーマ。
rulesRule[]
sameAs、minChecked、requiredWhenで作ったルール。入力欄のパスは型で確かめられます。

戻り値

FormDefinition — スキーマの代わりに、formFieldsとparseFormへ渡します。

注意

  • ブラウザとサーバーは、同じ処理でルールを判定します。1つの入力欄が複数のルールを満たさないときは、先に宣言したルールの文言が表示されます。

sameAs

import元 @k8ordo/form/server

fieldの値がotherの値と同じであることを求めます。パスワードの確認に使います。

ts
sameAs(field: FieldPath, other: FieldPath, message: RuleMessage): Rule

引数

fieldFieldPath
ルールを適用する入力欄のパス。ルールに違反したときのエラーは、この入力欄に表示されます。
otherFieldPath
比べる相手の入力欄のパス。
messagestring | (() => string)
ルールを満たさないときの文言。関数を渡すと、エラーを報告するときに呼ばれます。

戻り値

Rule — defineFormの2つ目の引数に並べます。

minChecked

import元 @k8ordo/form/server

同じ名前のチェックボックスのうち、min個以上がチェックされていることを求めます。

ts
minChecked(field: FieldPath, min: number, message: RuleMessage): Rule

引数

fieldFieldPath
ルールを適用する入力欄のパス。ルールに違反したときのエラーは、この入力欄に表示されます。
minnumber
チェックが必要な最小の数。
messagestring | (() => string)
ルールを満たさないときの文言。関数を渡すと、エラーを報告するときに呼ばれます。

戻り値

Rule — defineFormの2つ目の引数に並べます。

requiredWhen

import元 @k8ordo/form/server

whenの値がequalsであるあいだだけ、fieldを必須にします。

ts
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が読みます。

ts
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回の検証を見分けるための値。同じ内容の失敗が続いても、別の応答として扱えます。
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。