クライアントAPI
Client Componentで使う、@k8ordo/formのフックとコンポーネント、型の一覧です。サーバーで呼ぶ関数は「サーバーAPI」のページにあります。
このページの内容
useForm
import元 @k8ordo/form
formFieldsが作った入力欄の情報を、<form>とその中の入力欄に結び付けます。
コードをコピー
useForm(fields: FormFields, state?: FormState): UseFormReturn引数
fieldsFormFields- Server Componentで
formFieldsを呼んだ結果。propsで受け取ったものをそのまま渡します。 stateFormState- Server Actionが返した
FormState。useActionStateが返す1つ目の値です。アクションの無いGETのフォームでは省きます。
戻り値
UseFormReturn — <form>に展開するpropsと、入力欄ごとの表示を返す関数。
フィールド
props{ onSubmit, onBlur, onInput, onReset, ref }<form>に展開するイベントハンドラとref。ほかの要素には付けません。field(path) => FieldView- パスを渡すと、その入力欄の
FieldViewを返します。入れ子のフィールドはuser.emailのようにドットでつなぎます。 array(path) => ArrayView- 繰り返し行の配列のパスを渡すと、その
ArrayViewを返します。 formErrorFormErrorView- どの入力欄にも属さないエラーと、それを表示する要素に展開するprops。
isDirtyboolean- どれかの入力欄の値が描画したときから変わっていれば
true。行の追加や削除も含みます。 revalidate(control) => void- 入力欄の検証の結果を読み直し、入力欄から離れたときと同じように文言を表示します。
useAsyncCheckに渡します。
注意
- 入力された値はReactのstateに保存せず、DOMから読みます。キー入力のたびに再描画されることはありません。
- 展開したあとに自分の
onSubmitを書くと、props.onSubmitが上書きされます。自分の処理の中からform.props.onSubmit(event)を呼んでください。 noValidateはマウント時にJavaScriptで付け、サーバーが返すHTMLには含めません。JavaScriptを読み込むまでは、ブラウザが入力を検証します。- 新しい
stateを受け取ると、エラーのある箇所のうち画面上で最初のものへフォーカスを移します。対象は、検証に失敗した入力欄と、formErrorや配列のエラーを表示する要素です。stateは中身とtokenで見分けるので、手で作るときはtokenも変えます。
talk-form.tsxコードをコピー
const [state, formAction] = useActionState(createTalk, {});
const form = useForm(fields, state);
const title = form.field('title');
<form {...form.props} action={formAction}>
<input {...title.input} />
{title.error !== undefined && <p>{title.error}</p>}
</form>FieldView
import元 @k8ordo/form
form.field()が返す、1つの入力欄の表示に使う値です。
コードをコピー
type FieldView = {
input: FieldInput;
error: string | undefined;
invalid: boolean;
required: boolean;
};フィールド
inputFieldInput- 入力欄に展開する属性。
nameやtype、requiredなどです。送信に失敗したあとは、送った値がdefaultValueに入ります。 errorstring | undefined- いま表示するエラー文言。ブラウザの検証かサーバーの検証の結果です。無ければ
undefinedです。 invalidbooleanerrorがあるときにtrue。aria-invalidなどに渡します。requiredboolean- スキーマが空の送信を受け付けないときに
true。ラベルに必須の印を付けるのに使います。
注意
- サーバーのエラーは、その入力欄を書き換えるまで残ります。ブラウザの検証のエラーがあれば、そちらを優先します。
z.stringbool()の入力欄だけは、inputにvalueが入ります。チェックしたときに送る文字列です。
ArrayView
import元 @k8ordo/form
form.array()が返す、繰り返し行の表示に使う値です。
コードをコピー
type ArrayView = {
rows: RowView[];
add: () => void;
canAdd: boolean;
canRemove: boolean;
error: string | undefined;
errorProps: { id: string; tabIndex: -1 };
};フィールド
rowsRowView[]- いま表示している行。1行ずつが
RowViewです。 add() => void- 末尾に行を1つ追加します。
canAddboolean- 行数がスキーマの
.max()より少なければtrue。 canRemoveboolean- 行数がスキーマの
.min()より多ければtrue。 errorstring | undefined- 配列そのもののエラー。行数が
.min()や.max()に合わないときに入ります。行の入力欄には表示されません。 errorProps{ id: string; tabIndex: -1 }errorを表示する要素に展開するidとtabIndex={-1}。送信に失敗したとき、この要素にフォーカスを移せるようにします。
order-form.tsxコードをコピー
const items = form.array('items');
{items.rows.map((row) => (
<div key={row.key}>
<input {...row.field('name').input} />
{items.canRemove && (
<button onClick={row.remove} type="button">
Remove
</button>
)}
</div>
))}
{items.canAdd && (
<button onClick={items.add} type="button">
Add a row
</button>
)}RowView
import元 @k8ordo/form
繰り返し行の1行です。
コードをコピー
type RowView = {
key: string;
index: number;
field: (itemKey?: string) => FieldView;
remove: () => void;
};フィールド
keystring- 行を見分ける値で、
keyに渡します。行を削除しても、ほかの行のkeyは変わりません。 indexnumber- いまの位置。0から数えます。
field(itemKey?: string) => FieldView- 行の中の入力欄のキーを渡すと、その
FieldViewを返します。nameはitems[0].nameの形になります。文字列などの配列では引数を省きます。 remove() => void- この行を削除します。
注意
- 行の中のキーは、パスと違って型で確かめません。書き間違えると、描画したときにエラー
[@k8ordo/form] 配列 'items' に 'nmae' がありません。になります。
FormErrorView
import元 @k8ordo/form
form.formErrorの型です。スキーマ全体の.refine()のエラーのように、どの入力欄にも属さないエラーを持ちます。
コードをコピー
type FormErrorView = {
message: string | undefined;
props: { id: string; tabIndex: -1 };
};フィールド
messagestring | undefinedstate.formErrorの文言。無ければundefined。props{ id: string; tabIndex: -1 }- 文言を表示する要素に展開する
idとtabIndex={-1}。送信に失敗したとき、この要素にフォーカスを移せるようにします。
useAsyncCheck
import元 @k8ordo/form
入力欄から離れたときに、その値をサーバーに問い合わせます。名前がすでに使われていないかなど、サーバーにしか分からない検証に使います。
コードをコピー
useAsyncCheck(
check: (value: string) => Promise<string | undefined>,
revalidate: UseFormReturn['revalidate'],
): AsyncCheck引数
check(value: string) => Promise<string | undefined>- 値を受け取り、表示する文言を返す関数。問題が無ければ
undefinedを返します。Server Actionをそのまま渡せます。 revalidateUseFormReturn['revalidate']useFormが返すrevalidate。結果を受け取ったら、これで入力欄の文言を表示します。
戻り値
AsyncCheck — 入力欄に展開するpropsと、問い合わせの途中かどうか。
フィールド
props{ onBlur, ref }- 入力欄に展開する
onBlurとref。field().inputと並べて展開します。 isCheckingboolean- 結果を待っている間は
true。送信ボタンを無効にするのに使います。
注意
- 返された文言は
setCustomValidityで入力欄に設定され、ほかのエラーと同じくerrorに入ります。 - 結果が前後して返っても、最後に問い合わせた値の結果だけを使います。最後に結果を受け取った値のまま入力欄を離れても、問い合わせ直しません。
- 入力欄を空にして離れると、前の結果は消えます。関数が失敗したときは何も付けず、送信後のサーバーの検証に任せます。失敗したときのエラーは
reportErrorでブラウザに報告します。
slug-field.tsxコードをコピー
const slug = form.field('slug');
const taken = useAsyncCheck(checkSlugAvailable, form.revalidate);
<input {...slug.input} {...taken.props} />
<button disabled={taken.isChecking} type="submit">Save</button>HiddenValue
import元 @k8ordo/form
<input name>を描画しないコンポーネントの値を、フォームの送信に含めます。リッチテキストエディタなどに使います。
コードをコピー
<HiddenValue name={string} value={string} />引数
namestring- 送信するときの名前。スキーマでのパスと同じにします。
valuestring- 送信する値。コンポーネントのstateをそのまま渡します。
注意
- 値が変わるたびに
inputイベントを発火するので、複数の入力欄にまたがるルールやisDirtyがキー入力と同じように反応します。 - リセットしても値は戻りません。値は呼び出し側のstateなので、そちらも戻してください。
post-form.tsxコードをコピー
<Editor onChange={setBody} value={body} />
<HiddenValue name="body" value={body} />FormFields
import元 @k8ordo/form
formFieldsが返し、useFormが受け取る値の型です。中身はJSONなので、Server Componentからpropsで渡せます。
コードをコピー
type FormFields<FieldPath, ArrayPath, StringCheckboxPath> = {
fields: Record<FieldPath, DerivedField>;
arrays: Record<ArrayPath, DerivedArray>;
rules: DerivedRule[];
dropped: DroppedCheck[];
};フィールド
fieldsRecord<FieldPath, DerivedField>- パスごとのフィールドの情報。入力欄の属性と、検証ごとの文言を持ちます。
arraysRecord<ArrayPath, DerivedArray>- パスごとの繰り返し行の情報。行数の上限と下限、1行分の入力欄を持ちます。
rulesDerivedRule[]defineFormで宣言した、複数の入力欄にまたがるルール。文言はformFieldsを呼んだ時点で決まっています。droppedDroppedCheck[]- ブラウザでは確かめない検証の一覧。HTMLの属性で表せないものが入ります。サーバーでは確かめます。
注意
- 型引数は3つです。フィールドのパスと配列のパス、
z.stringbool()のフィールドのパスです。formFieldsの戻り値から推論されるので、ふつうは書きません。 @k8ordo/formと@k8ordo/form/serverのどちらからもimportできます。