スキーマ関連 / parseWithZod

parseWithZod

提供された zod スキーマを使用してフォームデータを解析し、送信内容の概要を返すヘルパーです。

1const submission = parseWithZod(payload, options);

#パラメータ

payload

フォームの送信方法に応じて、 FormData オブジェクトまたは URLSearchParams オブジェクトのいずれかになります。

options

schema

Zod スキーマ、または Zod スキーマを返す関数のいずれかです。

async

safeParse の代わりに zod スキーマから safeParseAsync メソッドを使用してフォームデータを解析したい場合は、 true に設定してください。

errorMap

フォームデータを解析する際に使用される zod の エラーマップ です。

formatError

エラー構造をカスタマイズし、必要に応じて追加のメタデータを含めることができる関数です。

#

1import { parseWithZod } from '@conform-to/zod';
2import { useForm } from '@conform-to/react';
3import { z } from 'zod';
4
5const schema = z.object({
6  email: z.string().email(),
7  password: z.string(),
8});
9
10function Example() {
11  const [form, fields] = useForm({
12    onValidate({ formData }) {
13      return parseWithZod(formData, { schema });
14    },
15  });
16
17  // ...
18}

#Tips

自動型変換

Conform は空の値を除去し、スキーマを内省することでフォームデータを期待される型に強制し、追加の前処理ステップを注入します。以下のルールが適用されます:

  1. 値が空の文字列 / ファイルである場合、スキーマに undefined を渡します。
  2. スキーマが z.string() の場合、値をそのまま渡します。
  3. スキーマが z.number() の場合、値をトリムして Number コンストラクタでキャストします。
  4. スキーマが z.boolean() の場合、値が on に等しい場合には true として扱います。
  5. スキーマが z.date() の場合、値を Date コンストラクタでキャストします。
  6. スキーマが z.bigint() の場合、値を BigInt コンストラクタでキャストします。

この挙動は、スキーマ内で独自の z.preprocess ステップを設定することで上書きすることができます。

注意: v3.22 以降、 z.preprocess の挙動に関して Zod のリポジトリには複数のバグレポートがあります。例えば、 https://github.com/colinhacks/zod/issues/2671 および <br> https://github.com/colinhacks/zod/issues/2677 があります。問題を経験している場合は、v3.21.4 にダウングレードしてください。

1const schema = z.object({
2  amount: z.preprocess((value) => {
3    // 値が提供されていない場合は、 `undefined` を返します。
4    if (!value) {
5      return undefined;
6    }
7
8    // 書式をクリアして値を数値に変換します。
9    return Number(value.trim().replace(/,/g, ''));
10  }, z.number()),
11});

デフォルト値

Conform はすでに空の値を undefined に前処理しています。 .default() をスキーマに追加して、代わりに返されるデフォルト値を定義します。

Zod は、前処理後の入力が undefined の場合、デフォルト値を返します。これはスキーマの戻り値の型を変更する効果もあります。

1const schema = z.object({
2  foo: z.string(), // string | undefined
3  bar: z.string().default('bar'), // string
4  baz: z.string().nullable().default(null), // string | null
5});