React / 系统课时

显示字段错误

显示字段错误

表单校验失败时,最有用的反馈不是一句“提交失败”,而是把服务端返回的错误重新映射到具体字段。这里用 Server Action、Zod 和 useActionState 建立完整闭环,让错误既能就地显示,也能被辅助技术正确关联。

学习目标

  • 用 Server Action 返回按字段分组的校验错误
  • 用 useActionState 把服务端结果绑定到对应输入框
  • 用 aria-describedby 和 aria-live 提升错误提示的可访问性

先约定错误状态的形状

字段错误适合用“字段名 → 字符串数组”的结构返回。数组允许一个字段同时出现多条规则错误;顶层 message 则保留给整次提交的通用提示。校验不通过属于预期业务结果,应直接 return,不要把它当异常抛出。

以下片段示例依赖 App Router 项目已安装 zod,并把两个文件分别放到对应路径。

ts
// app/actions/profile.ts
'use server';

import { z } from 'zod';

const ProfileSchema = z.object({
  name: z.string().trim().min(2, '姓名至少 2 个字符'),
  email: z.string().trim().email('请输入有效邮箱地址'),
});

export type FormState = {
  errors?: {
    name?: string[];
    email?: string[];
  };
  message?: string;
};

export async function saveProfile(
  _prevState: FormState,
  formData: FormData,
): Promise<FormState> {
  const result = ProfileSchema.safeParse({
    name: formData.get('name'),
    email: formData.get('email'),
  });

  // 校验失败时提前返回,让客户端保留在当前表单。
  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors,
      message: '请修正标记的字段',
    };
  }

  // 本课只演示错误反馈;真实项目可在这里执行数据库写入。
  return { errors: {}, message: '校验通过' };
}

预期结果:safeParse() 不会因普通校验失败抛异常,而是返回结构化错误;flatten().fieldErrors 会把 Zod 问题整理为与表单字段对应的数组。

tsx
// app/profile-form.tsx
'use client';

import { useActionState } from 'react';
import { saveProfile, type FormState } from '@/app/actions/profile';

const initialState: FormState = { errors: {}, message: '' };

export default function ProfileForm() {
  const [state, formAction, pending] = useActionState(
    saveProfile,
    initialState,
  );

  return (
    // noValidate 仅用于本示例,确保错误由服务端规则返回。
    <form action={formAction} noValidate>
      <label htmlFor="name">姓名</label>
      <input
        id="name"
        name="name"
        aria-invalid={Boolean(state.errors?.name)}
        aria-describedby="name-error"
      />
      {/* 错误容器的 id 与 aria-describedby 一一对应。 */}
      <div id="name-error" aria-live="polite">
        {state.errors?.name?.map((error) => (
          <p key={error}>{error}</p>
        ))}
      </div>

      <label htmlFor="email">邮箱</label>
      <input
        id="email"
        name="email"
        type="email"
        aria-invalid={Boolean(state.errors?.email)}
        aria-describedby="email-error"
      />
      <div id="email-error" aria-live="polite">
        {state.errors?.email?.map((error) => (
          <p key={error}>{error}</p>
        ))}
      </div>

      {/* pending 状态避免用户在同一次提交期间重复操作。 */}
      <button disabled={pending}>
        {pending ? '提交中…' : '保存'}
      </button>
      <p aria-live="polite">{state.message}</p>
    </form>
  );
}

预期结果:提交姓名 J 和邮箱 bad 时,页面会分别在姓名与邮箱输入框附近显示“姓名至少 2 个字符”和“请输入有效邮箱地址”;修正后再次提交,字段错误消失并显示“校验通过”。

错误为什么要贴近字段

useActionState 会把 Server Action 的返回值保存为 state,所以关键不是“显示一段错误文本”,而是保持字段名一致:服务端返回 errors.email,客户端就在邮箱控件旁读取 state.errors?.email。这样新增字段时也能按同一模式扩展。

aria-describedby 把输入控件和错误容器建立语义关联,aria-live="polite" 则允许错误内容变化时被读屏软件提示。仅靠红色边框不能完整表达错误状态,最好同时保留可读文本。

不要把服务器异常直接当字段错误

数据库断开、权限失败等异常通常不属于某个输入字段。它们应转换为通用、安全的消息,或交给错误边界处理;不要把原始堆栈、SQL 或内部异常文本返回给浏览器。字段错误只负责“用户能修正什么”,系统错误负责“应用为什么没有完成操作”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

显示字段错误

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通