React / 系统课时
显示字段错误
显示字段错误
表单校验失败时,最有用的反馈不是一句“提交失败”,而是把服务端返回的错误重新映射到具体字段。这里用 Server Action、Zod 和 useActionState 建立完整闭环,让错误既能就地显示,也能被辅助技术正确关联。
学习目标
- 用 Server Action 返回按字段分组的校验错误
- 用
useActionState把服务端结果绑定到对应输入框 - 用
aria-describedby和aria-live提升错误提示的可访问性
先约定错误状态的形状
字段错误适合用“字段名 → 字符串数组”的结构返回。数组允许一个字段同时出现多条规则错误;顶层 message 则保留给整次提交的通用提示。校验不通过属于预期业务结果,应直接 return,不要把它当异常抛出。
以下片段示例依赖 App Router 项目已安装 zod,并把两个文件分别放到对应路径。
// 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 问题整理为与表单字段对应的数组。
// 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 或内部异常文本返回给浏览器。字段错误只负责“用户能修正什么”,系统错误负责“应用为什么没有完成操作”。