tanstack-vue-form-skilld

@tanstack/vue-form 1.33.5

Vue 3 向けのヘッドレスで型安全なフォーム状態管理です。このパッケージは @tanstack/form-core のすべてを再エクスポートし、Vue コンポーネントとフックを追加します（src/index.ts:1-5）。

環境

• 調査対象のバージョン：@tanstack/[email protected]。@tanstack/[email protected] と @tanstack/vue-store@^0.11.0 をバンドルします（package.json:39-42）。
• ピア依存関係：vue ^3.4.0（package.json:48-50）。テストマトリックスでは TypeScript 5.4 から 5.9 までを対象としています（package.json:54-60）。
• パッケージのルートからのみインポートしてください。サブパスのエクスポートは ./package.json だけです（package.json:21-33）。ESM/CJS のデュアル対応で、sideEffects: false です。
• 公式ドキュメント：https://tanstack.com/form/latest/docs/framework/vue/overview

最小限のフォーム

<script setup lang="ts">
import { useForm } from '@tanstack/vue-form'

const form = useForm({
  defaultValues: {
    fullName: '',
  },
  onSubmit: async ({ value }) => {
    console.log(value)
  },
})
</script>

<template>
  <form @submit.prevent.stop="form.handleSubmit">
    <form.Field name="fullName">
      <template v-slot="{ field }">
        <input
          :name="field.name"
          :value="field.state.value"
          @blur="field.handleBlur"
          @input="(e) => field.handleChange((e.target as HTMLInputElement).value)"
        />
      </template>
    </form.Field>
    <button type="submit">Submit</button>
  </form>
</template>

出典：公式クイックスタート、https://tanstack.com/form/latest/docs/framework/vue/quick-start

フィールドのバインド規則

• フィールドは form.Field コンポーネントで作成します。name プロパティには defaultValues の深いキーを指定する必要があります。たとえば、'details.email' や `people[${i}].name` のように指定します。
• スコープ付きスロットは { field, state } を受け取ります（src/useField.tsx:543-547）。field は FieldApi、state は field.state を反映します。
• 入力は制御します。:value="field.state.value" をバインドし、field.handleChange で更新を反映し、@blur="field.handleBlur" を設定します。
• 数値入力では、(e.target as HTMLInputElement).valueAsNumber を使用します。
• スロット内の入力に v-model を指定しないでください。状態は handleChange を通じて反映されます。
• form.Field はフィールドを作成する前に、プロパティとフォールスルー属性をマージします（src/useField.tsx:541）。そのため、バリデーターやリスナーはプロパティまたは属性として渡せます。

リアクティビティ

• <script setup> では、form.useSelector((state) => state.values.firstName) を使用します。これは Readonly<Ref<T>> を返します（src/useForm.tsx:155-189）。
• form.useStore は非推奨です。useSelector と同じ関数です。form.useSelector を使用してください（src/useForm.tsx:190-227, 336-337）。
• テンプレートでは、任意の selector プロパティを指定して <form.Subscribe> を使用します。selector を指定しない場合、スロットはフォーム状態全体を受け取ります（src/useForm.tsx:338-349）。
• リアクティビティのために useField フックを直接呼び出さないでください。このフックは form.Field 内で使うためのものです。代わりに form.useSelector を使用してください（公式の基本概念に関する注記：https://tanstack.com/form/latest/docs/framework/vue/guides/basic-concepts）。
• useSelector と useStore は、ストアへ直接アクセスするために @tanstack/vue-store から再エクスポートされています（src/index.ts:2）。

詳細：references/reactivity.md

バリデーションの基本

• バリデーターは form.Field の validators プロパティ、または useForm オプションの validators で渡します。フックは onMount、onChange、onBlur、onSubmit、onDynamic で、それぞれに Async 版があります。
• バリデーターは有効な場合に undefined を返し、それ以外の場合は任意の型のエラー（通常は文字列）を返します。エラーは field.state.meta.errors と field.state.meta.errorMap に格納されます。
• Standard Schema ライブラリはバリデーターとしてそのまま使用できます：Zod v3.24.0 以降、Valibot v1.0.0 以降、ArkType v2.1.20 以降、Yup v1.7.0 以降（公式の基本概念ガイド）。
• 非同期バリデーターのデバウンスには、async-debounce-ms プロパティ、またはバリデーターごとの onChangeAsyncDebounceMs を使用します。
• onDynamic バリデーターは、useForm オプションで validationLogic: revalidateLogic() を設定した場合にのみ実行されます。

<form.Field
  name="age"
  :validators="{
    onChange: z.number().gte(13, 'You must be 13 to make an account'),
  }"
>

詳細：references/validation.md

配列フィールド

• ラッパーとなるフィールドに mode="array" を指定します。配列モードでは、コンポーネントは値ではなく state.meta._arrayVersion を追跡するため、子フィールドの編集によってリスト全体が再レンダリングされることはありません（src/useField.tsx:258-267, src/types.ts:12-15）。
• field.state.value を対象に v-for を使い、`people[${i}].name` のような深い名前でサブフィールドを描画します。
• 配列のメソッドで変更します：pushValue、removeValue、swapValues、moveValue、insertValue、replaceValue、clearValues。

詳細：references/array-fields.md

フォームグループ

• <form.FormGroup name="step1" v-slot="{ group }"> は、フォームデータの1つのキーに対するサブフォームを構築します。スロットには { group, state } が渡されます（src/useFormGroup.tsx:525-529）。
• group.handleSubmit() はグループのみを送信して検証します。form.handleSubmit() はフォーム全体を送信します。
• グループバリデーターは { group, fields } を返すことができます。fields のキーはグループからの相対パスで、Standard Schema はステップごとに合成できます。

詳細：references/form-groups.md

バージョン固有のルール

• v1.28.0 以降の破壊的変更：field.state.meta.errors はデフォルトでフラット化されるため、[['err']] ではなく ['err'] になります。フィールドオプションで disableErrorFlat: true を指定すると、以前のフィールドごとのネスト形式に戻せます。リリース：https://github.com/TanStack/form/releases/tag/%40tanstack%2Fvue-form%401.28.0
• 非推奨：form.useStore の代わりに form.useSelector を使用してください（src/useForm.tsx:190-192, 336-337）。
• 非推奨：field.getValue() の代わりに field.state.value を読み取ってください（公式 FieldApi リファレンス、https://tanstack.com/form/latest/docs/reference/classes/FieldApi）。
• Field は mode: 'value' | 'array' を受け付けます。配列モードはリストの再レンダリングを避けるためのものです。https://github.com/TanStack/form/issues/1925 を参照してください（src/useField.tsx:258-259）。
• useForm は、利用可能な場合は Vue の useId を使用して SSR に安全なフォーム ID を生成し、利用できない場合は uuid にフォールバックすることで、サーバーのマークアップとクライアントのハイドレーションを一致させます（src/useForm.tsx:272, src/useFormId.ts:18-24）。useFormId 自体は内部用で、エクスポートされていません（dist/esm/index.js）。
• 再利用可能なオプションセット：form-core の formOptions({ defaultValues }) を useForm に展開して使用します。

注意点

• Standard Schema の変換は保持されません。onSubmit は常に入力データを受け取ります。変換後の出力を得るには、onSubmit 内で schema.parse(value) を呼び出してください（公式送信ガイド、https://tanstack.com/form/latest/docs/framework/vue/guides/submission-handling）。
• フォームレベルのバリデーターがフィールドに対して返したエラーは、そのフィールド独自のバリデーターによって上書きされることがあります。フィールドのバリデーションは、フォームレベルのフィールドエラーが設定された後に実行されます（公式バリデーションガイド）。
• 同期バリデーターが先に実行されます。同期バリデーションが失敗すると、対応する Async バリデーターはスキップされます。ただし、asyncAlways: true の場合は除きます。
• フォームが操作されるまでは、canSubmit は true です。操作が始まる前に送信ボタンを無効にするには、!canSubmit || isPristine を組み合わせてください。アクセシビリティのため、disabled より aria-disabled を優先してください（公式バリデーションガイド）。
• Field コンポーネントと FormGroup コンポーネントは、親フォームを自動的に渡します。スタンドアロンの Field と FormGroup のエクスポートのみ、明示的な form オプションが必要です。
• 非同期のデフォルト値：reactive と computed の ref でラップしてください（TanStack Query のパターン、https://tanstack.com/form/latest/docs/framework/vue/guides/async-initial-values）。

参考資料

• references/api-surface.md：エクスポート、フック、コンポーネント、コアクラスのメソッドとソースコードへの参照。
• references/reactivity.md：セレクター、Subscribe、リスナー、リアクティブなメタデータの追跡。
• references/validation.md：バリデーター、スキーマ、動的バリデーション、リンクされたフィールド、送信処理。
• references/array-fields.md：配列フィールドと配列の変更メソッド。
• references/form-groups.md：サブフォーム、グループのバリデーション、グループの状態。