SuperAPI AI Directory

forms-validation

General & other

View repository

Updated 10-16 09:55

About this skill

Forms & Validation

References: React Hook Form official, Zod official, VeeValidate official, Form Design Patterns (Adam Silver).

Applicable Scenarios

  • Various forms (login / registration / configuration / creation / editing)
  • Complex validation (dependent fields / async / backend validation)
  • Multi-step forms (wizards)
  • Dynamic fields (arrays / nested)
  • File upload
  • Draft saving

Core Principles

1. Schema-first
   定义 Zod / Yup schema → 自动生成类型 + 校验
  1. Form library performance is better than useState useState forms → every field input re-renders the whole form RHF / VeeValidate → localized updates

  2. Validation timing

    • onChange: real-time (poor performance)
    • onBlur: on blur (recommended)
    • onSubmit: on submit
  3. Friendly error messages Don't write "VALIDATION_FAILED", write "Email format is incorrect"

  4. Prevent duplicate submission Disable the button while isSubmitting Or: deduplication / idempotency key

  5. Backend validation is the fallback Frontend validation is only for UX, backend must validate again

  6. Field-level vs form-level errors Field-level: email format Form-level: "Username already exists" returned by the server


## React Hook Form + Zod(推荐)

### 基础表单

```typescript
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const formSchema = z.object({
  email: z.string().email('请输入有效邮箱'),
  password: z.string().min(8, '密码至少 8 个字符').max(64, '密码不超过 64 个字符'),
  remember: z.boolean().optional(),
});

type FormData = z.infer<typeof formSchema>;

function LoginForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting, isValid },
    setError,
  } = useForm<FormData>({
    resolver: zodResolver(formSchema),
    mode: 'onBlur',  // 失焦校验
    defaultValues: { email: '', password: '', remember: false },
  });
  
  const onSubmit = async (data: FormData) => {
    try {
      await api.login(data);
      navigate('/dashboard');
    } catch (err) {
      if (err.code === 'INVALID_CREDENTIALS') {
        setError('root', { message: '邮箱或密码错误' });
      } else {
        setError('root', { message: '登录失败,请稍后重试' });
      }
    }
  };
  
  return (
    <form onSubmit={handleSubmit(onSubmit)} noValidate>
      <div>
        <label htmlFor="email">邮箱</label>
        <input id="email" type="email" {...register('email')} aria-invalid={!!errors.email} />
        {errors.email && <p role="alert">{errors.email.message}</p>}
      </div>
      
      <div>
        <label htmlFor="password">密码</label>
        <input id="password" type="password" {...register('password')} aria-invalid={!!errors.password} />
        {errors.password && <p role="alert">{errors.password.message}</p>}
      </div>
      
      <label>
        <input type="checkbox" {...register('remember')} />
        记住我
      </label>
      
      {errors.root && <p role="alert">{errors.root.message}</p>}
      
      <button type="submit" disabled={isSubmitting || !isValid}>
        {isSubmitting ? '登录中...' : '登录'}
      </button>
    </form>
  );
}

Complex validation (dependent / async)

const registerSchema = z.object({
  username: z.string().min(3).max(20),
  email: z.string().email(),
  password: z.string().min(8),
  confirmPassword: z.string(),
})
.refine((data) => data.password === data.confirmPassword, {
  message: '密码不一致',
  path: ['confirmPassword'],
})
.refine(
  async (data) => {
    const res = await api.checkUsernameAvailable(data.username);
    return res.available;
  },
  {
    message: '用户名已被占用',
    path: ['username'],
  }
);

Dynamic fields (arrays)

import { useFieldArray } from 'react-hook-form';

const orderSchema = z.object({
  customer: z.string().min(1),
  items: z.array(
    z.object({
      productId: z.number().int().positive(),
      quantity: z.number().int().positive().max(100),
    })
  ).min(1, '至少 1 个商品'),
});

function OrderForm() {
  const { control, register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(orderSchema),
    defaultValues: { customer: '', items: [{ productId: 0, quantity: 1 }] },
  });
  
  const { fields, append, remove } = useFieldArray({ control, name: 'items' });
  
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('customer')} />
      
      {fields.map((field, index) => (
        <div key={field.id}>
          <input type="number" {...register(`items.${index}.productId`)} />
          <input type="number" {...register(`items.${index}.quantity`)} />
          <button type="button" onClick={() => remove(index)}>删除</button>
        </div>
      ))}
      
      <button type="button" onClick={() => append({ productId: 0, quantity: 1 })}>
        添加商品
      </button>
      
      <button type="submit">提交</button>
    </form>
  );
}

Multi-step forms

function MultiStepForm() {
  const [step, setStep] = useState(0);
  const methods = useForm<FullFormData>({ resolver: zodResolver(fullSchema) });
  
  const stepSchemas = [stepOneSchema, stepTwoSchema, stepThreeSchema];
  
  const next = async () => {
    const valid = await methods.trigger(stepFields[step]);  // 仅校验当前步
    if (valid) setStep(s => s + 1);
  };
  
  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        {step === 0 && <StepOne />}
        {step === 1 && <StepTwo />}
        {step === 2 && <StepThree />}
        
        <div>
          {step > 0 && <button onClick={() => setStep(s => s - 1)}>上一步</button>}
          {step < 2 && <button type="button" onClick={next}>下一步</button>}
          {step === 2 && <button type="submit">提交</button>}
        </div>
      </form>
    </FormProvider>
  );
}

File upload

const fileSchema = z.object({
  avatar: z.instanceof(FileList)
    .refine(files => files.length > 0, '请选择文件')
    .refine(files => files[0]?.size <= 5 * 1024 * 1024, '文件不超过 5MB')
    .refine(files => ['image/jpeg', 'image/png'].includes(files[0]?.type), '仅支持 JPG/PNG'),
});

function UploadForm() {
  const { register, handleSubmit, watch } = useForm({ resolver: zodResolver(fileSchema) });
  const file = watch('avatar')?.[0];
  
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input type="file" accept="image/*" {...register('avatar')} />
      {file && <img src={URL.createObjectURL(file)} alt="预览" />}
      <button type="submit">上传</button>
    </form>
  );
}

TanStack Form (next generation, ultimate types)

import { useForm } from '@tanstack/react-form';

function MyForm() {
  const form = useForm({
    defaultValues: { email: '', password: '' },
    onSubmit: async ({ value }) => {
      await api.login(value);
    },
    validators: {
      onChange: ({ value }) => formSchema.safeParse(value).error,
    },
  });
  
  return (
    <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
      <form.Field
        name="email"
        validators={{
          onBlur: z.string().email('请输入邮箱'),
        }}
        children={(field) => (
          <>
            <input
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
              onBlur={field.handleBlur}
            />
            {field.state.meta.errors.length > 0 && <span>{field.state.meta.errors[0]}</span>}
          </>
        )}
      />
    </form>
  );
}

Vue 3 + VeeValidate

<script setup lang="ts">
import { useForm } from 'vee-validate';
import { toTypedSchema } from '@vee-validate/zod';
import { z } from 'zod';

const schema = toTypedSchema(z.object({
  email: z.string().email('请输入邮箱'),
  password: z.string().min(8, '密码至少 8 个字符'),
}));

const { defineField, handleSubmit, errors, isSubmitting } = useForm({
  validationSchema: schema,
});

const [email, emailAttrs] = defineField('email');
const [password, passwordAttrs] = defineField('password');

const onSubmit = handleSubmit(async (values) => {
  await api.login(values);
});
</script>

<template>
  <form @submit="onSubmit" novalidate>
    <input v-model="email" v-bind="emailAttrs" type="email" />
    <p v-if="errors.email">{{ errors.email }}</p>
    
    <input v-model="password" v-bind="passwordAttrs" type="password" />
    <p v-if="errors.password">{{ errors.password }}</p>
    
    <button :disabled="isSubmitting">登录</button>
  </form>
</template>

Vue 3 + Formily (enterprise-grade, complex forms)

// 适合:动态表单、JSON Schema 驱动、可视化表单设计器
import { createForm } from '@formily/core';
import { FormProvider, FormItem, Input, Submit } from '@formily/antdv';

const form = createForm();

const schema = {
  type: 'object',
  properties: {
    email: {
      type: 'string',
      title: '邮箱',
      required: true,
      'x-validator': [{ format: 'email' }],
      'x-component': 'Input',
    },
  },
};

Angular Reactive Forms

@Component({
  selector: 'app-login',
  imports: [ReactiveFormsModule],
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      <input formControlName="email" type="email" />
      @if (form.get('email')?.errors?.['email']) {
        <p>请输入邮箱</p>
      }
      
      <input formControlName="password" type="password" />
      <button [disabled]="form.invalid || submitting()">登录</button>
    </form>
  `,
})
export class LoginComponent {
  fb = inject(FormBuilder);
  submitting = signal(false);
  
  form = this.fb.group({
    email: ['', [Validators.required, Validators.email]],
    password: ['', [Validators.required, Validators.minLength(8)]],
  });
  
  async onSubmit() {
    if (this.form.invalid) return;
    this.submitting.set(true);
    try {
      await this.authService.login(this.form.value);
    } finally {
      this.submitting.set(false);
    }
  }
}

SvelteKit Form Actions

<!-- routes/login/+page.svelte -->
<script lang="ts">
  import { enhance } from '$app/forms';
  
  let { form } = $props();
</script>

<form method="POST" use:enhance>
  <input name="email" type="email" required />
  {#if form?.errors?.email}<p>{form.errors.email}</p>{/if}
  
  <input name="password" type="password" required />
  
  <button>登录</button>
</form>

<!-- routes/login/+page.server.ts -->
<script lang="ts">
  import { fail, redirect } from '@sveltejs/kit';
  import { z } from 'zod';
  
  const schema = z.object({
    email: z.string().email(),
    password: z.string().min(8),
  });
  
  export const actions = {
    default: async ({ request }) => {
      const formData = Object.fromEntries(await request.formData());
      const result = schema.safeParse(formData);
      
      if (!result.success) {
        return fail(400, { errors: result.error.flatten().fieldErrors });
      }
      
      try {
        await login(result.data);
      } catch {
        return fail(401, { message: '邮箱或密码错误' });
      }
      
      throw redirect(303, '/dashboard');
    },
  };
</script>

Schema library comparison

Library Size TS Performance Recommendation
Zod 11KB Strong Medium ⭐⭐⭐⭐⭐
Yup 28KB Medium Medium ⭐⭐⭐
Valibot 1KB Strong High ⭐⭐⭐⭐⭐
Joi 145KB Weak Medium ⭐⭐
ArkType - Very strong High ⭐⭐⭐⭐

Choosing validation timing

onChange(每字符):
  ✅ 适合:密码强度提示、计数
  ❌ 不适合:异步校验(频繁请求)、长表单

onBlur(失焦):
  ✅ 适合:通用校验、邮箱格式
  ❌ 不适合:实时反馈

onSubmit(提交时):
  ✅ 适合:简单表单、确认操作
  ❌ 不适合:需要立即反馈

混合(推荐):
  - 第一次提交后切到 onChange
  - 默认 onBlur

Prevent duplicate submission

// React Hook Form
const { handleSubmit, formState: { isSubmitting } } = useForm();

// 自动 isSubmitting,按钮 disabled
<button disabled={isSubmitting}>提交</button>

// 自定义 + 节流
const onSubmit = useCallback(
  throttle(async (data) => {
    await api.submit(data);
  }, 1000),
  []
);

// 幂等键(重要操作)
const idempotencyKey = useMemo(() => crypto.randomUUID(), []);
const onSubmit = async (data) => {
  await api.createOrder(data, { headers: { 'Idempotency-Key': idempotencyKey } });
};

Draft saving

// LocalStorage 自动保存
function useDraft<T>(formId: string, watch: () => T) {
  const [restored, setRestored] = useState(false);
  const data = watch();
  
  useEffect(() => {
    const saved = localStorage.getItem(`draft:${formId}`);
    if (saved && !restored) {
      // 用 form.reset(JSON.parse(saved)) 恢复
      setRestored(true);
    }
  }, [formId]);
  
  useEffect(() => {
    if (restored) {
      localStorage.setItem(`draft:${formId}`, JSON.stringify(data));
    }
  }, [data, restored, formId]);
  
  const clearDraft = () => localStorage.removeItem(`draft:${formId}`);
  return { clearDraft };
}

Workflow

1. 设计表单 schema(Zod)
   - 字段 + 校验规则

2. 选择表单库(RHF / TanStack Form / VeeValidate)

3. 实现表单
   - 受控 vs 非受控
   - 校验时机
   - 错误展示

4. 防重复提交(isSubmitting / 幂等键)

5. 处理提交错误
   - 字段级 vs 表单级
   - 业务错误友好提示

6. 草稿保存(如长表单)

7. 测试
   - 校验规则
   - 提交成功 / 失败
   - 防重复

Supporting templates

  • templates/forms-checklist.md — form checklist + validation rules + error handling + tests

Quality self-check

□ Schema-first(Zod / Valibot)
□ 类型自动派生
□ 受控 / 非受控明确
□ 校验时机合理
□ 错误信息友好(用户语言)
□ 防重复提交
□ 异步校验防抖
□ Loading / Error 状态
□ 必填用 *
□ 错误用 aria-invalid
□ 标签关联(label htmlFor)
□ 焦点管理(首个错误聚焦)
□ 键盘可操作
□ 移动端友好(type / inputmode)
□ 草稿保存(如长表单)
□ 后端校验兜底

Common pitfalls

  1. Not preventing duplicate submission——duplicate creation
  2. Technical error messages——"VALIDATION_FAILED" instead of "Email format is incorrect"
  3. Validation only on the frontend——calling the API directly can still bypass it
  4. onChange validation has poor performance——large forms lag
  5. Not using a form library——useState forms re-render the whole form
  6. Cannot focus the first error——users can't find it in a long form
  7. type=email doesn't validate——the browser's native validation isn't strict
  8. No noValidate——the browser's default UI interferes
  9. Checkbox / radio handled incorrectly——RHF usage is wrong
  10. File upload doesn't restrict type / size——the backend gets attacked
  11. No draft saving— long forms are lost on refresh
  12. Disabled button without explanation— users don't know why
  13. Multi-step forms can't go back— poor experience
  14. iOS zoom issue— input font < 16px

Collaboration with other skills

上游:
  ui-ux-designer 工作流 → 表单设计 / 状态
  api-designer → 字段约束 / 错误码

下游:
  data-fetching → 提交 mutation
  state-management → 表单状态
  accessibility-implementation → ARIA / 焦点
  testing-frontend → 表单测试

Related references

  • Project root references/frontend-tech-stack-guide.md — form library