做过一个售后退款的工单页,三十多个字段。最早的做法很直接:每个字段一个 useState,每个 onChange 里顺手做一次格式校验。在开发的 Mac 上一切正常,上线后客服反馈,在仓库的旧安卓平板上输入备注,字要慢半拍才出来。打开 React DevTools 的渲染高亮,每敲一个键,整个表单三十个输入框全部重新渲染,外加八条正则重新跑一遍。

校验的问题更乱。手机号格式在 onChange 里校验一次,在 onBlur 里再校验一次,提交时又遍历整个表单校验一次。三处写的正则还不一样,一个允许带区号,一个不允许,提示文案也有三种。用户把手机号改对了,红色提示却不消失,因为只有「校验失败」的分支,没有「校验通过就清除」的分支。提交失败时只弹了个 toast「保存失败」,三十个字段里哪个有问题,用户只能自己一个个试。

这篇把表单拆成几件独立的事:值由谁持有、状态怎么组织、校验放在哪一层、错误提示怎么显示、提交时怎么防止重复和丢失输入。React 示例按 React 18 写,Vue 示例按 Vue 3 写,两边分开讲,不混在同一段代码里。

受控与非受控:值归谁管,卡顿从哪来

受控的意思是,输入框显示的值来自框架状态,用户每敲一个键,先触发回调,回调更新状态,状态再驱动输入框显示。非受控的意思是,值存在 DOM 自己的内部状态里,框架只在需要的时候通过 ref 或表单提交去读。两者的差别不只是写法,而是「谁持有值、什么时候读值、能不能在输入过程中干预」。

// React 18:受控写法,值放在 React state 里
function PhoneField() {
  const [phone, setPhone] = useState("");
  return (
    <input
      value={phone}
      onChange={(event) => setPhone(event.target.value)}
    />
  );
}

// 非受控写法,值在 DOM 里,提交时再读
function PhoneFieldUncontrolled() {
  const ref = useRef(null);
  return <input ref={ref} defaultValue="" />;
}

受控适合需要即时反应的场景:输入时联动另一个字段、实时显示字数、边输边格式化、输入内容要参与其他计算。非受控适合字段多、彼此独立、只在提交或失焦时才需要值的场景。三十个字段的表单如果每个键都更新父级状态,渲染范围就是整张表单,卡顿是必然的,跟机器新旧关系不大。

Vue 3 的 v-model 本质上是受控写法的语法糖,值放在 reactive 对象里,输入时同步更新。Vue 的响应式更新粒度比 React 细,三十个字段不至于像 React 那样整棵树重渲染,但把校验写在每次输入里,仍然会让每次按键都跑一遍规则。

原生表单的提交、重置和禁用行为见HTML 表单;这篇重点讲状态和校验怎么组织。

不要在一个字段的生命周期里从非受控切换到受控。React 会对这种切换发出警告,输入框也可能被重置。要么一开始就传 value,要么一直用 defaultValue。

大表单为什么卡:不是 state 数量,是渲染范围

把三十个 useState 合并成一个对象,并不会让渲染变少。每次 setForm 仍然会让持有这个对象的组件重渲染,它下面的三十个字段也一起重渲染。真正有效的做法是把渲染范围切小:字段自己管理自己的值,或者用非受控加 ref,只在提交时汇总;父组件只保留错误、提交状态这些需要共享的信息。

全受控

字段值全在框架状态里,联动、格式化、即时预览都好写,调试时能看到完整数据。代价是每次输入都触发渲染和校验,大表单在低端设备上容易卡。

非受控为主

值留在 DOM 里,输入时不触发整表渲染,性能好。代价是取值要经过 ref,联动和即时预览要额外处理,字段值不参与框架状态,调试时看不见。

实际项目里经常是混合的:大多数普通字段用非受控,少数需要联动的字段用受控,错误和提交状态统一放在表单层。混合不是妥协,是按字段的交互需求分配成本。

表单状态怎么组织:四块信息,别混成一个

一个表单要记的东西比想象中多:值、错误、哪些字段被碰过、有没有改过、是否正在提交。全塞进一个对象也能跑,但每一块的生命周期不同,混在一起后很难判断「什么时候该显示错误」。

values:字段的当前值,提交时要用;嵌套结构按真实数据组织,不要为了扁平而扁平
errors:字段级和表单级错误,按字段路径索引,服务端返回的错误也放这里
touched:哪些字段被用户碰过,决定错误提示什么时候出现
dirty 和 submitting:有没有未保存修改、是否正在提交,决定离开提示和按钮状态

touched 是最容易被忽略的一块。没有它,页面一打开就满屏红色;有了它,用户没碰过的字段先不提示,碰过且校验失败才显示。提交时可以把所有字段标记为 touched,让错误一次性全出来。

扁平对象适合大多数字段,取值路径短,校验和错误映射都简单。只有地址、发票信息这种真的嵌套的数据,才用嵌套对象,并且配一个按路径读写的工具函数,不要在组件里手写 form.address.city 一路点下去。

动态字段数组要特别注意 key。用数组下标当 key,删除第二行之后,原来第三行的输入框会复用第二行的 DOM,光标和值都可能错位。每一行在创建时给一个稳定的 id,删除、排序、校验都按 id 走。

// 表单状态的四块信息,按职责分开
const formState = {
  values: {
    customer: "",
    phone: "",
    items: [{ id: "row-1", sku: "", qty: 1 }],
  },
  errors: {},
  touched: {},
  dirty: false,
  submitting: false,
};

Vue 3 里可以用一个 reactive 对象装 values,再用单独的 reactive 装 errors 和 touched。不要把所有东西塞进同一个 reactive,否则改一个错误也会触发依赖整个对象的组件更新。

校验放哪一层:字段、表单、服务端各管一段

校验不是「写在一个地方」就好,而是每一层只做自己擅长的事。字段级管格式:必填、长度、正则、数字范围。表单级管字段之间的关系:结束日期不能早于开始日期、明细金额之和要等于总额、至少填一种联系方式。服务端管客户端不可能知道的:用户名是否唯一、优惠券是否可用、库存够不够、当前用户有没有权限。

客户端的校验只是体验优化,不能当成安全边界。用户可以改前端代码、直接调接口,所以服务端必须再校验一次。反过来说,服务端校验也不能只返回一句「参数错误」,要把字段路径带上,前端才能把错误放回对应的输入框。

真正的浪费是把同一条规则写三遍。格式规则写进 onChange、onBlur 和提交函数,三份代码迟早会分叉。比较合理的做法是规则只定义一次,在需要的时机调用同一个校验函数,提示文案也从同一份映射里取。

异步校验的乱序问题

「用户名是否已被占用」「优惠券是否有效」这类校验必须问服务端,问题是请求会乱序。用户先输 abc,再改成 abcd,如果 abc 的响应后到,页面会提示 abcd 已被占用,用户怎么改都不对。处理方式和搜索请求一样:防抖,加序号,只接受最新一次的结果。

// 异步校验:防抖加序号,只接受最新一次结果
function createAsyncChecker(check, onResult) {
  let seq = 0;
  let timer = null;
  return function run(value) {
    const current = ++seq;
    clearTimeout(timer);
    timer = setTimeout(async () => {
      try {
        const result = await check(value);
        if (current === seq) onResult(result);
      } catch (error) {
        if (current === seq) onResult({ ok: false, message: "校验服务不可用" });
      }
    }, 400);
  };
}

异步校验不要放在每次按键上。输入过程中反复请求,既慢又浪费,用户还没输完就看到「不可用」也很烦。放在失焦或提交前更合理,最多在输入停顿之后做一次预检,并在界面上显示「正在检查」。

schema 校验:一条规则只写一次

字段一多,手写 if 判断会变成一堵墙,而且类型和校验规则各写一份,改字段名要改两处。Zod、Yup 这类 schema 库把结构和规则写在一起,校验、错误路径、类型推导都从同一份定义来。

// Zod 3:结构和规则写在一处,提交前统一校验
import { z } from "zod";

const orderSchema = z.object({
  customer: z.string().min(1, "请选择客户"),
  phone: z.string().regex(/^1[3-9]\d{9}$/, "手机号格式不对"),
  items: z.array(
    z.object({
      sku: z.string().min(1, "请选择商品"),
      qty: z.number().int().min(1, "数量至少为 1"),
    })
  ).min(1, "至少加一行商品"),
});

const result = orderSchema.safeParse(values);
if (!result.success) {
  const first = result.error.issues[0];
  console.log(first.path, first.message);
}

这段代码在 Node 或浏览器里都能跑,前提是项目里装了 Zod。错误对象里有路径和文案,正好可以直接映射到字段。schema 还能推导出 TypeScript 类型,避免 values 和类型定义两套。示例基于 Zod 3,Zod 4 的错误结构有调整,具体以安装版本为准,待确认。

如果后端也是 TypeScript,可以共享同一份 schema;如果后端是别的语言,就不要假设两边的校验完全一致,前端 schema 只做体验,服务端仍然要独立实现。

错误提示、焦点与无障碍

错误提示的位置要稳定。字段级错误放在输入框下面,紧挨着它;表单级错误放在表单顶部或提交按钮上方,汇总成一条可点击的列表。不要用 toast 承载字段错误,toast 会消失,用户改的时候已经看不到提示了。

提交失败时,把焦点移到第一个出错的字段,并把它滚动到可见区域。三十个字段的表单,如果错误在页面最上面,用户停在最下面点提交,只会看到按钮没反应。

function focusFirstError(container) {
  const first = container.querySelector('[aria-invalid="true"]');
  if (first) {
    first.scrollIntoView({ block: "center" });
    first.focus();
  }
}

无障碍方面有三件事必须做。第一,错误提示要和输入框关联,用 aria-describedby 指向错误文本的 id,屏幕阅读器才会在读输入框时把错误念出来。第二,校验失败的输入框要标 aria-invalid="true",不能只靠红色边框。第三,错误汇总如果要在提交后动态出现,给它 role="alert",让屏幕阅读器主动播报。

// 输入框与错误文本的关联,React 18
function Field({ id, label, error, ...inputProps }) {
  const errorId = id + "-error";
  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input
        id={id}
        aria-invalid={Boolean(error)}
        aria-describedby={error ? errorId : undefined}
        {...inputProps}
      />
      {error && <p id={errorId} className="field-error">{error}</p>}
    </div>
  );
}

还有两个细节。占位符不能当标签,用户输入后占位符消失,就不知道这个框是干什么的;标签要一直可见。必填标记要写进标签文本或 aria-required,不要只用星号。规则见HTML 无障碍,表单是最需要它的地方之一。

提交体验:防重复、留住输入、别乱跳走

提交按钮被连点两次,生成两张订单,是表单里最常见的线上事故。防止的办法有几层:点击后立刻把提交状态设为 true,按钮进入禁用和 loading;提交函数入口再判断一次,已经在提交就直接返回;服务端最好还能用幂等键兜底,同一个请求重复到达只处理一次。

一次提交要经过四步
先校验,全部通过才发请求
锁定按钮并显示提交中
成功就清理或跳转,失败保留输入
把服务端错误映射回字段并给一次总结

失败时不要清空表单。用户填了三十个字段,提交失败后全部清掉,是最让人恼火的体验之一。成功时也不要在请求发出前就清空,必须等后端确认落库再清理或跳转。

离开页面的提醒要克制。只有 dirty 为 true、确实有未保存修改时才拦截,并且只在浏览器后退、关闭标签页、站内路由跳转时提示。用户点了保存、请求成功之后要立即解除拦截,否则他正常离开还会被问「确定要离开吗」。

草稿自动保存看起来很美,代价要提前想清楚。存 localStorage 的话,备注里可能有手机号、地址这些个人信息,明文留在用户设备上不合适;多标签页同时编辑同一个草稿,后保存的会覆盖先保存的;草稿结构一变,旧版本的草稿反序列化可能直接报错。比较稳的是存到服务端,带上版本号和更新时间,冲突时提示用户选择保留哪一份。

「离开时自动保存草稿」和「有未保存修改就拦截」不能同时无脑打开。用户被拦截后选择离开,草稿又悄悄存了下来,下次打开看到旧内容,会以为系统在跟他开玩笑。两者只能选一个,或者把草稿做成显式的「保存草稿」按钮。

完整场景:三十个字段的工单表单从三处校验到一层

需求是售后工单录入:客户、联系电话、订单号、退款金额、商品明细、问题描述,加起来三十多个字段;要求移动端输入不卡;校验提示统一;提交不能重复;失败保留输入;客服中途离开能恢复。第一版每个字段一个 state,校验散在三处,代码大致是这样。

// 第一版:字段各自受控,校验散在三个时机
function TicketForm() {
  const [phone, setPhone] = useState("");
  const [amount, setAmount] = useState("");
  const [error, setError] = useState({});

  function checkPhone(value) {
    if (!/^1[3-9]\d{9}$/.test(value)) return "手机号格式不对";
    return "";
  }

  return (
    <form>
      <input
        value={phone}
        onChange={(event) => {
          setPhone(event.target.value);
          const message = checkPhone(event.target.value);
          if (message) setError((prev) => ({ ...prev, phone: message }));
        }}
        onBlur={() => {
          const message = checkPhone(phone);
          if (message) setError((prev) => ({ ...prev, phone: message }));
        }}
      />
      <input value={amount} onChange={(event) => setAmount(event.target.value)} />
    </form>
  );
}

这段代码有三个问题。第一,每输入一个字符就跑正则,还触发整张表单重渲染,低端设备上肉眼可见地慢。第二,校验只在失败时写错误,通过时不清除,用户改对了红字还挂着。第三,提交时又单独写了一套校验,和这里的规则不一致,同一字段会出现两种提示。

第二版把校验收进 schema,字段改成非受控,错误和 touched 单独管理,提交状态放在表单层。下面是核心部分,基于 React 18、react-hook-form 7 和 Zod 3,具体选项名以安装版本为准,待确认。

// 第二版:schema 定义规则,字段非受控,提交状态统一
const { register, handleSubmit, formState } =
  useForm({ resolver: zodResolver(orderSchema), mode: "onBlur" });

const onSubmit = handleSubmit(async (values) => {
  await createTicket(values);
});

return (
  <form onSubmit={onSubmit} noValidate>
    <input
      {...register("phone")}
      aria-invalid={Boolean(formState.errors.phone)}
    />
    {formState.errors.phone && <p>{formState.errors.phone.message}</p>}
    <button type="submit" disabled={formState.isSubmitting}>
      {formState.isSubmitting ? "提交中…" : "提交工单"}
    </button>
  </form>
);

Vue 3 不走这套,直接用 v-model 加一个校验函数,重点是 touched 和错误分开存,规则只出现在一个地方。

// Vue 3:v-model 加独立错误状态
const form = reactive({ phone: "", amount: "" });
const touched = reactive({ phone: false });
const errors = computed(() => ({
  phone: touched.phone && !/^1[3-9]\d{9}$/.test(form.phone) ? "手机号格式不对" : "",
}));

上线后还是有一批反馈。下面这些现象,一半来自校验时机,一半来自提交状态。

现象真实原因第一步查什么
旧平板上输入备注明显卡顿每次按键都更新整表状态并重跑全部正则用渲染高亮看一次输入触发了哪些组件
手机号改对了,红字还不消失校验失败才写错误,通过时没有清掉旧错误看校验函数成功分支有没有返回空并写回状态
同一字段在三个位置提示三种文案onChange、onBlur、提交各写了一套规则全局搜同一条正则或同一个提示文案
连点提交生成两张工单按钮没有进入提交中状态,请求入口也没拦住看 submitting 是否同步设置,按钮是否 disabled
服务端说订单号重复,但页面没标红服务端错误没有按字段路径映射回表单看失败分支有没有把 errors 写回对应字段
填了半小时,刷新后内容全没了只存在组件状态,没有草稿或本地缓存看是否有草稿保存,以及保存时机

表格里第二条和第三条都指向同一个原则:校验规则和错误清理必须在同一处。规则可以复用,但「什么时候显示、什么时候清除」要和 touched 与提交状态一起设计,否则规则越统一,提示反而越乱。

边界与代价:不是所有表单都要上框架

表单方案的选择,跟字段数量和交互复杂度直接相关。三五个字段的登录框,受控加一个手写校验函数就够了,引入 schema 和表单库只是多一层要学的东西。

  • 字段少于十个、没有动态增删、没有跨字段联动时,手写受控表单更快,代码也更直白。不要为了统一而统一。
  • 表单库的优势在大表单和复杂校验,代价是抽象层变厚。出错时要判断是库的行为、schema 的写法,还是自己的状态接错了,排查链路更长。
  • 非受控提升性能,但也让「输入时实时预览」「边输边算」变难。需要即时反馈的字段,仍然要单独做成受控。
  • schema 和类型推导很方便,但前后端共享 schema 只在同一门语言里成立。跨语言时两边各写一份,靠接口契约和测试保证一致,别假设自动同步。
  • 草稿自动保存会带来隐私和冲突问题。涉及个人信息、金额、证件的表单,优先存服务端,并设过期时间;本地存储要明确告知用户,并提供清除入口。
  • 离开拦截是把双刃剑。加得太频繁,用户会习惯性点「离开」,真正需要拦截的时候也不看了。
  • 多步骤表单不要每一步都校验全部字段。只校验当前步骤,允许用户回退修改,最后提交前再统一跑一次全量校验。

判断标准其实很简单:如果表单的复杂度主要来自字段数量,非受控和表单库能帮上忙;如果复杂度来自业务规则和字段联动,重点应该放在状态建模和校验分层,工具只是辅助。

今天就能验证的练习,和小结

  1. 做一个十个字段的受控表单,在 React DevTools 里打开渲染高亮,输入一个字段,数一数一次按键重渲染了几个组件。
  2. 把其中一个字段改成非受控,用 ref 在提交时取值,确认输入时不再触发整表渲染,同时记录取值方式的变化。
  3. 故意在校验通过时不清除旧错误,复现「改对了红字还在」;再补上清除逻辑,观察提示消失的时机。
  4. 给提交按钮加 submitting 状态,连点五次,确认只发出一次请求;再打开 Network 面板核对请求数。
  5. 用键盘 Tab 走一遍带错误的表单,检查焦点是否能落到第一个错误字段,屏幕阅读器是否能念出 aria-describedby 关联的错误文本。
值归谁管要先定:需要联动和即时反馈的字段受控,大表单的普通字段可以非受控。
状态分四块:values、errors、touched、dirty 与 submitting,各有各的时机。
校验分层:字段管格式,表单管关系,服务端管唯一性和权限,客户端校验不是安全边界。
错误要能定位:贴着字段显示,提交失败聚焦第一个错误,aria 关联不能少。
提交要防重、失败留输入、成功再清理;草稿和离开提示都有隐私与体验代价。

表单的难点从来不是把值取出来,而是让「用户输入、规则校验、服务端结果」这三件事在同一套状态里对上。值、错误、时机分清楚了,三十个字段和三个字段只是规模差别,不会变成两种写法。

到这里,表单里的错误文案、日期、金额都还是写死的中文格式。一旦要支持英文、德文,问题就从「校验对不对」变成「文案放哪、日期怎么显示、按钮会不会被长单词撑破」。下一篇讲国际化与多语言,从这些具体的排版事故开始。