React 表单处理最佳实践

// 受控组件：状态即真相来源，支持实时验证
function ControlledForm() {
  const [formData, setFormData] = useState({
    username: '',
    email: '',
    password: ''
  });
  const [errors, setErrors] = useState({});
  const [touched, setTouched] = useState({});

  const validateField = (name, value) => {
    let error = '';
    switch (name) {
      case 'username':
        if (!value) error = 'Username is required';
        else if (value.length < 3) error = 'Username must be at least 3 characters';
        break;
      case 'email':
        if (!value) error = 'Email is required';
        else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) error = 'Invalid email';
        break;
      case 'password':
        if (!value) error = 'Password is required';
        else if (value.length < 8) error = 'Password must be at least 8 characters';
        break;
    }
    return error;
  };

  const handleChange = (e) => {
    const { name, value } = e.target;
    setFormData(prev => ({ ...prev, [name]: value }));
    // 只有被触碰过的字段才在输入时报错，避免一上来满屏红字
    if (touched[name]) {
      setErrors(prev => ({ ...prev, [name]: validateField(name, value) }));
    }
  };

  const handleBlur = (e) => {
    const { name, value } = e.target;
    setTouched(prev => ({ ...prev, [name]: true }));
    setErrors(prev => ({ ...prev, [name]: validateField(name, value) }));
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    // 提交时校验所有字段
    const nextErrors = {};
    Object.keys(formData).forEach(key => {
      nextErrors[key] = validateField(key, formData[key]);
    });
    setErrors(nextErrors);
    setTouched({ username: true, email: true, password: true });

    if (Object.values(nextErrors).every(msg => !msg)) {
      console.log('Form submitted:', formData);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label>Username</label>
        <input name="username" value={formData.username}
          onChange={handleChange} onBlur={handleBlur} />
        {touched.username && errors.username && <span>{errors.username}</span>}
      </div>
      <div>
        <label>Email</label>
        <input name="email" type="email" value={formData.email}
          onChange={handleChange} onBlur={handleBlur} />
        {touched.email && errors.email && <span>{errors.email}</span>}
      </div>
      <div>
        <label>Password</label>
        <input name="password" type="password" value={formData.password}
          onChange={handleChange} onBlur={handleBlur} />
        {touched.password && errors.password && <span>{errors.password}</span>}
      </div>
      <button type="submit">Submit</button>
    </form>
  );
}

// 非受控组件：ref 提交时读取，天然支持文件上传
function UncontrolledForm() {
  const usernameRef = useRef(null);
  const emailRef = useRef(null);
  const fileRef = useRef(null);

  const handleSubmit = (e) => {
    e.preventDefault();
    const formData = {
      username: usernameRef.current.value,
      email: emailRef.current.value,
      file: fileRef.current.files[0] // file input 只能非受控
    };
    console.log('Form submitted:', formData);
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label>Username</label>
        <input ref={usernameRef} defaultValue="" />
      </div>
      <div>
        <label>Email</label>
        <input ref={emailRef} type="email" defaultValue="" />
      </div>
      <div>
        <label>File</label>
        <input ref={fileRef} type="file" />
      </div>
      <button type="submit">Submit</button>
    </form>
  );
}

// React 19 的表单 Action + useActionState（服务端/客户端一体化）
// action 返回的对象会成为下一次的 state，pending 由框架托管
function NewsletterForm() {
  const [state, formAction, isPending] = useActionState(
    async (prevState, formData) => {
      const email = formData.get('email');
      if (!email) return { error: 'Email is required' };
      try {
        await fetch('/api/subscribe', { method: 'POST', body: formData });
        return { success: true };
      } catch {
        return { error: 'Subscription failed, try again' };
      }
    },
    { }
  );

  return (
    <form action={formAction}>
      <input name="email" type="email" placeholder="you@example.com" />
      <button type="submit" disabled={isPending}>
        {isPending ? 'Subscribing...' : 'Subscribe'}
      </button>
      {state.error && <span>{state.error}</span>}
      {state.success && <span>Subscribed!</span>}
    </form>
  );
}

// React Hook Form 基础用法：非受控 + 内置校验，重渲染极少
import { useForm } from 'react-hook-form';

function ReactHookForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
    reset
  } = useForm({
    mode: 'onBlur', // 校验时机：失焦校验，兼顾体验与性能
    defaultValues: { username: '', email: '', password: '' }
  });

  const onSubmit = async (data) => {
    try {
      await fetch('/api/register', {
        method: 'POST',
        body: JSON.stringify(data)
      });
      reset();
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label>Username</label>
        <input {...register('username', {
          required: 'Username is required',
          minLength: { value: 3, message: 'Username must be at least 3 characters' }
        })} />
        {errors.username && <span>{errors.username.message}</span>}
      </div>
      <div>
        <label>Email</label>
        <input type="email" {...register('email', {
          required: 'Email is required',
          pattern: { value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, message: 'Invalid email address' }
        })} />
        {errors.email && <span>{errors.email.message}</span>}
      </div>
      <div>
        <label>Password</label>
        <input type="password" {...register('password', {
          required: 'Password is required',
          minLength: { value: 8, message: 'Password must be at least 8 characters' }
        })} />
        {errors.password && <span>{errors.password.message}</span>}
      </div>
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Submitting...' : 'Submit'}
      </button>
    </form>
  );
}

// React Hook Form + Zod：一份 schema 同时提供校验和 TS 类型
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  username: z.string().min(3, 'Username must be at least 3 characters'),
  email: z.string().email('Invalid email address'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
  confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
  message: "Passwords don't match",
  path: ['confirmPassword']
});

// 从 schema 直接推导出表单类型，改 schema 类型自动同步
type FormValues = z.infer<typeof schema>;

function FormWithZod() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormValues>({
    resolver: zodResolver(schema)
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register('username')} />
      {errors.username && <span>{errors.username.message}</span>}
      <input type="email" {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}
      <input type="password" {...register('password')} />
      {errors.password && <span>{errors.password.message}</span>}
      <input type="password" {...register('confirmPassword')} />
      {errors.confirmPassword && <span>{errors.confirmPassword.message}</span>}
      <button type="submit">Submit</button>
    </form>
  );
}

// 异步校验：用户名是否已被占用（配合防抖）
import { useForm } from 'react-hook-form';

function SignupWithAsyncCheck() {
  const { register, handleSubmit, formState: { errors, isValidating } } = useForm({
    mode: 'onBlur'
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register('username', {
        required: 'Username is required',
        validate: async (value) => {
          const res = await fetch(`/api/check-username?u=${value}`);
          const { available } = await res.json();
          return available || 'Username already taken';
        }
      })} />
      {isValidating && <span>Checking...</span>}
      {errors.username && <span>{errors.username.message}</span>}
      <button type="submit">Submit</button>
    </form>
  );
}

// 复杂表单：动态字段（可增删的明细行），如订单、简历、问卷
import { useForm, useFieldArray } from 'react-hook-form';

function DynamicForm() {
  const { register, control, handleSubmit } = useForm({
    defaultValues: { items: [{ name: '', quantity: 1 }] }
  });

  const { fields, append, remove } = useFieldArray({ control, name: 'items' });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      {fields.map((field, index) => (
        <div key={field.id}>
          <input {...register(`items.${index}.name`)} placeholder="Item name" />
          <input type="number" {...register(`items.${index}.quantity`)} placeholder="Quantity" />
          <button type="button" onClick={() => remove(index)}>Remove</button>
        </div>
      ))}
      <button type="button" onClick={() => append({ name: '', quantity: 1 })}>
        Add Item
      </button>
      <button type="submit">Submit</button>
    </form>
  );
}

// 提交防重复 + 错误自动聚焦
function CheckoutForm() {
  const { register, handleSubmit, setFocus, formState: { errors, isSubmitting } } = useForm();

  const onValid = async (data) => {
    await placeOrder(data); // isSubmitting 期间按钮禁用，天然防重复提交
  };

  const onInvalid = (formErrors) => {
    // 聚焦到第一个出错的字段，提升可用性
    const firstError = Object.keys(formErrors)[0];
    if (firstError) setFocus(firstError);
  };

  return (
    <form onSubmit={handleSubmit(onValid, onInvalid)}>
      <input {...register('phone', { required: '请填写手机号' })} />
      {errors.phone && <span>{errors.phone.message}</span>}
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? '提交中...' : '提交订单'}
      </button>
    </form>
  );
}

// 把服务端返回的字段级错误回填到 React Hook Form
async function onSubmit(data) {
  const res = await fetch('/api/register', {
    method: 'POST', body: JSON.stringify(data)
  });
  if (!res.ok) {
    const { fieldErrors } = await res.json();
    // fieldErrors 形如 { email: 'already registered' }
    Object.entries(fieldErrors).forEach(([name, message]) => {
      setError(name, { type: 'server', message });
    });
  }
}

// 用 Controller 桥接受控的第三方组件，隔离重渲染
import { useForm, Controller } from 'react-hook-form';
import { Select } from 'antd';

function ProfileForm() {
  const { control, handleSubmit } = useForm();
  return (
    <form onSubmit={handleSubmit(console.log)}>
      <Controller
        name="country"
        control={control}
        rules={{ required: '请选择国家' }}
        render={({ field }) => (
          <Select {...field} options={[{ value: 'cn', label: '中国' }]} />
        )}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

// 防抖搜索：输入停止 300ms 后才真正查询
function SearchInput({ onSearch }) {
  const debounced = useMemo(
    () => debounce((value) => onSearch(value), 300),
    [onSearch]
  );
  // 卸载时取消未执行的防抖任务，防止内存泄漏
  useEffect(() => () => debounced.cancel(), [debounced]);

  return <input onChange={(e) => debounced(e.target.value)} />;
}

// useReducer 集中管理表单状态
function formReducer(state, action) {
  switch (action.type) {
    case 'change':
      return { ...state, values: { ...state.values, [action.name]: action.value } };
    case 'setError':
      return { ...state, errors: { ...state.errors, [action.name]: action.error } };
    case 'reset':
      return action.initial;
    default:
      return state;
  }
}

function ReducerForm({ initial }) {
  const [state, dispatch] = useReducer(formReducer, initial);
  const onChange = (e) =>
    dispatch({ type: 'change', name: e.target.name, value: e.target.value });
  return <form>{/* 字段绑定 onChange */}</form>;
}

// 混合模式示例：金额字段实时格式化（受控），其余字段非受控
import { useForm, Controller } from 'react-hook-form';

function InvoiceForm() {
  const { register, control, handleSubmit } = useForm({
    defaultValues: { title: '', amount: '' }
  });

  const formatMoney = (raw: string) => {
    // 去掉非数字，每三位加逗号
    const digits = raw.replace(/\D/g, '');
    return digits.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
  };

  return (
    <form onSubmit={handleSubmit(console.log)}>
      {/* 普通字段：非受控，输入零重渲染 */}
      <input {...register('title')} placeholder="发票标题" />

      {/* 金额字段：受控，输入时实时格式化 */}
      <Controller
        name="amount"
        control={control}
        render={({ field }) => (
          <input
            value={field.value}
            onChange={(e) => field.onChange(formatMoney(e.target.value))}
            placeholder="0"
            inputMode="numeric"
          />
        )}
      />
      <button type="submit">开票</button>
    </form>
  );
}

// 纯原生 FormData：无需为每个字段维护 state
function NativeFormDataForm() {
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);

    // 读取单个字段
    const email = formData.get('email');
    // 读取多值字段（如多选框、多文件）
    const hobbies = formData.getAll('hobby');
    // 一次性转成普通对象
    const data = Object.fromEntries(formData.entries());

    console.log({ email, hobbies, data });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" required />
      <label><input type="checkbox" name="hobby" value="reading" /> 阅读</label>
      <label><input type="checkbox" name="hobby" value="coding" /> 编程</label>
      <label><input type="checkbox" name="hobby" value="sports" /> 运动</label>
      <button type="submit">提交</button>
    </form>
  );
}

// 独立的提交按钮组件，自动感知 form 的 pending 状态
import { useFormStatus } from 'react-dom';

function SubmitButton({ children }: { children: React.ReactNode }) {
  const { pending, data } = useFormStatus();
  return (
    <button type="submit" disabled={pending} aria-busy={pending}>
      {pending ? '提交中...' : children}
    </button>
  );
}

// 使用时无需任何 props，按钮自己知道该禁用
function ContactForm({ action }: { action: (fd: FormData) => Promise<void> }) {
  return (
    <form action={action}>
      <input name="name" required />
      <textarea name="message" required />
      <SubmitButton>发送消息</SubmitButton>
    </form>
  );
}

// 评论区乐观更新：提交瞬间就显示新评论
import { useOptimistic, useRef } from 'react';

type Comment = { id: string; text: string; sending?: boolean };

function CommentList({ comments, addComment }: {
  comments: Comment[];
  addComment: (text: string) => Promise<void>;
}) {
  const formRef = useRef<HTMLFormElement>(null);
  const [optimisticComments, addOptimistic] = useOptimistic(
    comments,
    (state, newText: string) => [
      ...state,
      { id: 'temp-' + Date.now(), text: newText, sending: true }
    ]
  );

  const action = async (formData: FormData) => {
    const text = formData.get('text') as string;
    addOptimistic(text);       // 立即在 UI 上加一条（灰色"发送中"）
    formRef.current?.reset();
    await addComment(text);     // 真正落库，成功后 comments 更新，临时项被替换
  };

  return (
    <>
      <ul>
        {optimisticComments.map((c) => (
          <li key={c.id} style={{ opacity: c.sending ? 0.5 : 1 }}>
            {c.text} {c.sending && '(发送中...)'}
          </li>
        ))}
      </ul>
      <form action={action} ref={formRef}>
        <input name="text" required />
        <button type="submit">评论</button>
      </form>
    </>
  );
}

// app/actions.ts —— 服务端 Action（'use server'）
'use server';
import { z } from 'zod';

const schema = z.object({
  email: z.string().email('邮箱格式不正确'),
  age: z.coerce.number().min(18, '需年满 18 岁')
});

export async function register(prevState: unknown, formData: FormData) {
  const parsed = schema.safeParse({
    email: formData.get('email'),
    age: formData.get('age')
  });
  if (!parsed.success) {
    // 把 Zod 错误拍平成 { field: message }
    return { errors: parsed.error.flatten().fieldErrors };
  }
  await saveUser(parsed.data);
  return { success: true };
}

// app/register-form.tsx —— 客户端组件
'use client';
import { useActionState } from 'react';
import { register } from './actions';

function RegisterForm() {
  const [state, formAction, isPending] = useActionState(register, {});
  return (
    <form action={formAction}>
      <input name="email" type="email" />
      {state?.errors?.email && <span role="alert">{state.errors.email[0]}</span>}
      <input name="age" type="number" />
      {state?.errors?.age && <span role="alert">{state.errors.age[0]}</span>}
      <button disabled={isPending}>{isPending ? '注册中...' : '注册'}</button>
      {state?.success && <p>注册成功！</p>}
    </form>
  );
}

// register 的第二个参数是校验规则对象
<input {...register('email', {
  required: '邮箱必填',
  maxLength: { value: 100, message: '不超过 100 字符' },
  pattern: { value: /^\S+@\S+$/, message: '格式不正确' },
  validate: {
    notGmail: (v) => !v.endsWith('@gmail.com') || '不接受 gmail 邮箱',
    notBlacklisted: async (v) => {
      const ok = await checkBlacklist(v);
      return ok || '该邮箱在黑名单中';
    }
  },
  setValueAs: (v) => v.trim().toLowerCase() // 存入前统一格式化
})} />

// 依赖字段联动：省份变化时清空并重载城市列表
import { useForm, useWatch } from 'react-hook-form';

function CityField({ control, register, setValue }: any) {
  // 只有这个小组件在 province 变化时重渲染，表单其余部分不动
  const province = useWatch({ control, name: 'province' });
  const cities = useMemo(() => getCitiesByProvince(province), [province]);

  useEffect(() => {
    setValue('city', ''); // 省份变了，城市要清空
  }, [province, setValue]);

  return (
    <select {...register('city')}>
      {cities.map((c: any) => <option key={c.code} value={c.code}>{c.name}</option>)}
    </select>
  );
}

const { setValue, getValues, reset, trigger } = useForm();

// setValue：程序化赋值，第三参可控制是否触发校验和标脏
setValue('phone', '13800138000', { shouldValidate: true, shouldDirty: true });

// getValues：读取当前值（不触发订阅/重渲染），适合在事件回调里"顺手取一下"
const all = getValues();               // 全部
const email = getValues('email');       // 单个
const [a, b] = getValues(['a', 'b']);   // 多个

// reset：重置到给定值（常用于"编辑表单加载完远程数据后回填"）
useEffect(() => {
  if (userData) reset(userData); // 把接口返回的数据一次性填入并清除 dirty 状态
}, [userData, reset]);

// trigger：手动触发校验（多步表单里"下一步前校验当前步"必用）
const valid = await trigger(['name', 'email']);

// 简历教育经历：可增删、可上移排序、每行独立校验
import { useForm, useFieldArray } from 'react-hook-form';

type EduForm = {
  educations: { school: string; degree: string; year: number }[];
};

function ResumeForm() {
  const { register, control, handleSubmit, formState: { errors } } = useForm<EduForm>({
    defaultValues: { educations: [{ school: '', degree: '', year: 2020 }] }
  });

  const { fields, append, remove, move } = useFieldArray({
    control,
    name: 'educations'
  });

  return (
    <form onSubmit={handleSubmit(console.log)}>
      {fields.map((field, index) => (
        // 注意：key 必须用 field.id，不能用 index（否则删除中间行会错乱）
        <div key={field.id}>
          <input
            {...register(`educations.${index}.school`, { required: '学校必填' })}
            placeholder="学校"
          />
          {errors.educations?.[index]?.school && (
            <span>{errors.educations[index]?.school?.message}</span>
          )}

          <input
            {...register(`educations.${index}.degree`)}
            placeholder="学位"
          />
          <input
            type="number"
            {...register(`educations.${index}.year`, { valueAsNumber: true })}
          />

          <button type="button" onClick={() => remove(index)}>删除</button>
          {index > 0 && (
            <button type="button" onClick={() => move(index, index - 1)}>上移</button>
          )}
        </div>
      ))}

      <button type="button" onClick={() => append({ school: '', degree: '', year: 2024 })}>
        添加教育经历
      </button>
      <button type="submit">保存简历</button>
    </form>
  );
}

import { z } from 'zod';

// 丰富的 schema 定义
const userSchema = z.object({
  // 字符串约束
  username: z.string()
    .min(3, '至少 3 个字符')
    .max(20, '最多 20 个字符')
    .regex(/^[a-zA-Z0-9_]+$/, '只能包含字母数字下划线'),

  // 邮箱、URL 等内置校验
  email: z.string().email('邮箱格式不正确'),
  website: z.string().url('网址格式不正确').optional(),

  // 数字：coerce 会把表单里的字符串 "18" 自动转成数字 18
  age: z.coerce.number().int('必须是整数').min(18, '需年满 18').max(120),

  // 枚举
  role: z.enum(['admin', 'editor', 'viewer'], {
    errorMap: () => ({ message: '角色不合法' })
  }),

  // 嵌套对象
  address: z.object({
    province: z.string().min(1, '请选择省份'),
    city: z.string().min(1, '请选择城市'),
    detail: z.string().min(5, '详细地址至少 5 字')
  }),

  // 数组 + 元素约束
  tags: z.array(z.string()).min(1, '至少一个标签').max(5, '最多 5 个标签'),

  // 可选 + 默认值
  newsletter: z.boolean().default(false)
});

// 关键：从 schema 推导类型，schema 一改类型自动同步
type User = z.infer<typeof userSchema>;

const passwordSchema = z.object({
  password: z.string().min(8, '密码至少 8 位'),
  confirmPassword: z.string(),
  startDate: z.string(),
  endDate: z.string()
})
  // refine：单条跨字段规则，失败信息挂到指定 path
  .refine((data) => data.password === data.confirmPassword, {
    message: '两次密码不一致',
    path: ['confirmPassword']
  })
  // superRefine：可添加多条错误，逻辑更复杂时用
  .superRefine((data, ctx) => {
    if (new Date(data.endDate) <= new Date(data.startDate)) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: '结束日期必须晚于开始日期',
        path: ['endDate']
      });
    }
  });

const s = z.object({
  price: z.string().transform((v) => parseFloat(v)) // 输入 string，输出 number
});
type FormInput = z.input<typeof s>;   // { price: string }
type Parsed = z.output<typeof s>;      // { price: number }

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

const orderSchema = z.object({
  customer: z.object({
    name: z.string().min(2, '姓名至少 2 字'),
    phone: z.string().regex(/^1[3-9]\d{9}$/, '手机号格式不正确')
  }),
  items: z.array(z.object({
    product: z.string().min(1, '请选择商品'),
    quantity: z.coerce.number().int().min(1, '数量至少 1')
  })).min(1, '至少一件商品'),
  couponCode: z.string().optional(),
  agreeTerms: z.literal(true, {
    errorMap: () => ({ message: '需同意服务条款' })
  })
});

type OrderForm = z.infer<typeof orderSchema>;

function OrderCheckout() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting, isValid }
  } = useForm<OrderForm>({
    resolver: zodResolver(orderSchema),
    mode: 'onBlur',
    defaultValues: {
      customer: { name: '', phone: '' },
      items: [{ product: '', quantity: 1 }],
      agreeTerms: false as unknown as true
    }
  });

  const onSubmit = async (data: OrderForm) => {
    // data 已通过 Zod 校验且带完整类型，可直接发给后端
    await fetch('/api/orders', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('customer.name')} placeholder="姓名" />
      {errors.customer?.name && <span>{errors.customer.name.message}</span>}

      <input {...register('customer.phone')} placeholder="手机号" />
      {errors.customer?.phone && <span>{errors.customer.phone.message}</span>}

      <input {...register('items.0.product')} placeholder="商品" />
      <input type="number" {...register('items.0.quantity')} />

      <label>
        <input type="checkbox" {...register('agreeTerms')} />
        我已阅读并同意服务条款
      </label>
      {errors.agreeTerms && <span>{errors.agreeTerms.message}</span>}

      <button type="submit" disabled={isSubmitting || !isValid}>
        {isSubmitting ? '提交中...' : '提交订单'}
      </button>
    </form>
  );
}

// Formik 基础写法：受控、集中管理
import { Formik, Form, Field, ErrorMessage } from 'formik';
import * as Yup from 'yup';

const schema = Yup.object({
  email: Yup.string().email('邮箱格式不正确').required('必填'),
  password: Yup.string().min(8, '至少 8 位').required('必填')
});

function FormikLogin() {
  return (
    <Formik
      initialValues={{ email: '', password: '' }}
      validationSchema={schema}
      onSubmit={async (values, { setSubmitting }) => {
        await login(values);
        setSubmitting(false);
      }}
    >
      {({ isSubmitting }) => (
        <Form>
          <Field name="email" type="email" />
          <ErrorMessage name="email" component="span" />
          <Field name="password" type="password" />
          <ErrorMessage name="password" component="span" />
          <button type="submit" disabled={isSubmitting}>登录</button>
        </Form>
      )}
    </Formik>
  );
}

// 三步注册向导：单个 useForm 贯穿全程，trigger 分步校验
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const wizardSchema = z.object({
  // 第一步
  username: z.string().min(3, '至少 3 字'),
  email: z.string().email('邮箱不正确'),
  // 第二步
  company: z.string().min(1, '请填写公司'),
  role: z.string().min(1, '请填写职位'),
  // 第三步
  plan: z.enum(['free', 'pro', 'team'])
});
type Wizard = z.infer<typeof wizardSchema>;

// 每一步管辖哪些字段
const stepFields: Record<number, (keyof Wizard)[]> = {
  0: ['username', 'email'],
  1: ['company', 'role'],
  2: ['plan']
};

function RegisterWizard() {
  const [step, setStep] = useState(0);
  const { register, handleSubmit, trigger, formState: { errors } } = useForm<Wizard>({
    resolver: zodResolver(wizardSchema),
    mode: 'onBlur'
  });

  const next = async () => {
    // 只校验当前步的字段，全通过才允许进入下一步
    const ok = await trigger(stepFields[step]);
    if (ok) setStep((s) => Math.min(s + 1, 2));
  };
  const prev = () => setStep((s) => Math.max(s - 1, 0));

  const onSubmit = (data: Wizard) => console.log('最终提交', data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* 进度指示 */}
      <p>第 {step + 1} / 3 步</p>

      {step === 0 && (
        <>
          <input {...register('username')} placeholder="用户名" />
          {errors.username && <span>{errors.username.message}</span>}
          <input {...register('email')} placeholder="邮箱" />
          {errors.email && <span>{errors.email.message}</span>}
        </>
      )}
      {step === 1 && (
        <>
          <input {...register('company')} placeholder="公司" />
          {errors.company && <span>{errors.company.message}</span>}
          <input {...register('role')} placeholder="职位" />
          {errors.role && <span>{errors.role.message}</span>}
        </>
      )}
      {step === 2 && (
        <select {...register('plan')}>
          <option value="free">免费版</option>
          <option value="pro">专业版</option>
          <option value="team">团队版</option>
        </select>
      )}

      <div>
        {step > 0 && <button type="button" onClick={prev}>上一步</button>}
        {step < 2 && <button type="button" onClick={next}>下一步</button>}
        {step === 2 && <button type="submit">完成注册</button>}
      </div>
    </form>
  );
}

// 带进度条 + 大小/类型校验 + 可取消的文件上传
function FileUpload() {
  const [progress, setProgress] = useState(0);
  const [error, setError] = useState('');
  const xhrRef = useRef<XMLHttpRequest | null>(null);

  const MAX_SIZE = 5 * 1024 * 1024; // 5MB
  const ACCEPT = ['image/png', 'image/jpeg', 'application/pdf'];

  const handleFile = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // 前端预校验：类型 + 大小
    if (!ACCEPT.includes(file.type)) {
      setError('仅支持 PNG / JPG / PDF');
      return;
    }
    if (file.size > MAX_SIZE) {
      setError('文件不能超过 5MB');
      return;
    }
    setError('');

    const formData = new FormData();
    formData.append('file', file);

    const xhr = new XMLHttpRequest();
    xhrRef.current = xhr;
    xhr.open('POST', '/api/upload');

    // 关键：监听上传进度
    xhr.upload.onprogress = (evt) => {
      if (evt.lengthComputable) {
        setProgress(Math.round((evt.loaded / evt.total) * 100));
      }
    };
    xhr.onload = () => {
      if (xhr.status === 200) setProgress(100);
      else setError('上传失败');
    };
    xhr.onerror = () => setError('网络错误');
    xhr.send(formData);
  };

  const cancel = () => {
    xhrRef.current?.abort();
    setProgress(0);
  };

  return (
    <div>
      <input type="file" accept={ACCEPT.join(',')} onChange={handleFile} />
      {progress > 0 && progress < 100 && (
        <>
          <progress value={progress} max={100} /> {progress}%
          <button type="button" onClick={cancel}>取消</button>
        </>
      )}
      {progress === 100 && <span>上传完成</span>}
      {error && <span role="alert">{error}</span>}
    </div>
  );
}

// 条件字段：勾选开发票才显示并要求填写抬头
import { useForm } from 'react-hook-form';

function InvoiceOption() {
  const { register, watch, handleSubmit, formState: { errors } } = useForm({
    defaultValues: { needInvoice: false, invoiceTitle: '' }
  });

  const needInvoice = watch('needInvoice');

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <label>
        <input type="checkbox" {...register('needInvoice')} /> 需要发票
      </label>

      {needInvoice && (
        <div>
          <input
            {...register('invoiceTitle', {
              // 仅在需要发票时必填，用 validate 动态判断
              validate: (v) => !needInvoice || v.length > 0 || '请填写发票抬头'
            })}
            placeholder="发票抬头"
          />
          {errors.invoiceTitle && <span>{errors.invoiceTitle.message}</span>}
        </div>
      )}

      <button type="submit">提交</button>
    </form>
  );
}

// 自动保存草稿：变更后防抖 1000ms 落盘，进入时恢复
import { useForm } from 'react-hook-form';

const DRAFT_KEY = 'article-draft';

function ArticleEditor() {
  const { register, watch, reset, handleSubmit } = useForm({
    defaultValues: { title: '', body: '' }
  });

  // 进入时恢复草稿
  useEffect(() => {
    const saved = localStorage.getItem(DRAFT_KEY);
    if (saved) reset(JSON.parse(saved));
  }, [reset]);

  // 监听全表单变化，防抖后保存
  useEffect(() => {
    const debounced = debounce((value: unknown) => {
      localStorage.setItem(DRAFT_KEY, JSON.stringify(value));
    }, 1000);

    const subscription = watch((value) => debounced(value));
    return () => {
      subscription.unsubscribe();
      debounced.cancel();
    };
  }, [watch]);

  const onSubmit = (data: unknown) => {
    localStorage.removeItem(DRAFT_KEY); // 正式提交后清草稿
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('title')} placeholder="标题" />
      <textarea {...register('body')} placeholder="正文" rows={10} />
      <button type="submit">发布</button>
    </form>
  );
}

// 用翻译函数生成 schema，切换语言即切换错误文案
import { z } from 'zod';

type TFunc = (key: string, params?: Record<string, unknown>) => string;

function makeSchema(t: TFunc) {
  return z.object({
    email: z.string().email(t('errors.email')),
    password: z.string().min(8, t('errors.passwordMin', { min: 8 }))
  });
}

// 组件里根据当前语言生成 schema
function LoginForm() {
  const { t, locale } = useI18n();
  const schema = useMemo(() => makeSchema(t), [t, locale]);
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(schema)
  });
  // locale 变化时 schema 重建，错误文案随之切换
  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}
      <input type="password" {...register('password')} />
      {errors.password && <span>{errors.password.message}</span>}
      <button type="submit">{t('login.submit')}</button>
    </form>
  );
}

// 无障碍表单字段的完整写法
function A11yField({ register, name, label, error, required }: any) {
  const id = `field-${name}`;
  const errorId = `${id}-error`;
  return (
    <div>
      <label htmlFor={id}>
        {label}{required && <span aria-hidden="true"> *</span>}
      </label>
      <input
        id={id}
        {...register(name)}
        aria-required={required}
        aria-invalid={!!error}
        aria-describedby={error ? errorId : undefined}
      />
      {error && (
        <span id={errorId} role="alert">
          {error.message}
        </span>
      )}
    </div>
  );
}

// 虚拟化长表单：500 行只渲染可视的约 15 行
import { FixedSizeList } from 'react-window';
import { useFormContext } from 'react-hook-form';

function VirtualizedRows({ count }: { count: number }) {
  const { register } = useFormContext();
  return (
    <FixedSizeList height={400} itemCount={count} itemSize={48} width="100%">
      {({ index, style }) => (
        <div style={style}>
          <input {...register(`rows.${index}.value`)} placeholder={`第 ${index + 1} 行`} />
        </div>
      )}
    </FixedSizeList>
  );
}

// shared/schema.ts —— 前后端共享
import { z } from 'zod';
export const signupSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
});

// server route —— 服务端用同一 schema 校验
export async function POST(req: Request) {
  const body = await req.json();
  const parsed = signupSchema.safeParse(body);
  if (!parsed.success) {
    return Response.json(
      { fieldErrors: parsed.error.flatten().fieldErrors },
      { status: 400 }
    );
  }
  // 唯一性等只有服务端能做的校验
  if (await emailExists(parsed.data.email)) {
    return Response.json(
      { fieldErrors: { email: ['该邮箱已注册'] } },
      { status: 409 }
    );
  }
  await createUser(parsed.data);
  return Response.json({ ok: true });
}

// 测试登录表单：校验错误 + 成功提交
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { LoginForm } from './LoginForm';

test('空提交时展示校验错误', async () => {
  const user = userEvent.setup();
  render(<LoginForm onSubmit={jest.fn()} />);

  await user.click(screen.getByRole('button', { name: /登录/ }));

  // 错误用 role="alert"，可被 findByRole 捕获
  expect(await screen.findByText('邮箱不正确')).toBeInTheDocument();
  expect(screen.getByText('密码至少 8 位')).toBeInTheDocument();
});

test('填写正确并提交，回调收到数据', async () => {
  const user = userEvent.setup();
  const handleSubmit = jest.fn();
  render(<LoginForm onSubmit={handleSubmit} />);

  // 用 label 文本定位输入框，保证 a11y 同时测到
  await user.type(screen.getByLabelText('邮箱'), 'a@b.com');
  await user.type(screen.getByLabelText('密码'), 'password123');
  await user.click(screen.getByRole('button', { name: /登录/ }));

  expect(handleSubmit).toHaveBeenCalledWith(
    { email: 'a@b.com', password: 'password123' },
    expect.anything()
  );
});

test('异步用户名查重失败时报错', async () => {
  const user = userEvent.setup();
  // mock 接口返回不可用
  jest.spyOn(global, 'fetch').mockResolvedValue({
    json: async () => ({ available: false })
  } as Response);

  render(<SignupForm />);
  await user.type(screen.getByLabelText('用户名'), 'taken');
  await user.tab(); // 触发 blur

  expect(await screen.findByText('用户名已被占用')).toBeInTheDocument();
});