React Router 表单校验实战：基于 action 与 useFetcher 的注册表单实现指南-育师

React Router 表单校验实战：基于 action 与 useFetcher 的注册表单实现指南

【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router

表单校验是几乎所有 Web 应用绕不开的核心交互。在 React Router（本文基于GitHub_Trending/re/react-router仓库当前的 framework 与 data 两种路由模式）中，服务端action可以像 Web 标准表单那样解析提交数据、校验并将错误回传给 UI，而useFetcher能让我们在不触发页面导航的前提下完成这一整套流程。本文以“注册（Sign Up）表单”为例，带你完整走通从路由配置、action 校验、以 400 状态码回传错误，到前端渲染校验信息的整条链路，并结合仓库源码解释其中每个机制为何如此工作。

该指南适用于 React Router 的 framework（全栈框架）与 data（仅使用数据路由能力）两种模式。校验逻辑的薄厚取舍可以自行决定——你可以将它只作为动作管线的最小骨架，再叠加你偏爱的第三方校验库和错误组件。

1. 环境准备：注册一条 Signup 路由

假设项目已经初始化好了 React Router 的应用骨架（包含app/目录与基于 routes.ts 约定的路由配置文件）。首先在路由配置中声明一条signup路由，指向负责注册页面的模块文件：

import { type RouteConfig, route, } from "@react-router/dev/routes"; export default [ route("signup", "signup.tsx"), ] satisfies RouteConfig;

其中@react-router/dev/routes提供类型化的route()辅助函数与RouteConfig类型；route("signup", "signup.tsx")表示 URL 路径/signup由同目录下的signup.tsx模块（遵循文件路由约定，默认位于app/下）渲染。satisfies RouteConfig会让 TypeScript 在配置不符合路由定义规范时立即给出编译期错误，防止把错误的路由配置悄悄带入运行时。

接下来创建最小可提交的注册表单。这里使用useFetcher提供的fetcher.Form组件，而不是普通<form>或Form，因为后文我们会让表单与action交互时不发生路由跳转：

import type { Route } from "./+types/signup"; import { useFetcher } from "react-router"; export default function Signup(_: Route.ComponentProps) { let fetcher = useFetcher(); return ( <fetcher.Form method="post"> <p> <input type="email" name="email" /> </p> <p> <input type="password" name="password" /> </p> <button type="submit">Sign Up</button> </fetcher.Form> ); }

几点说明：

./+types/signup是 React Router 在 dev 模式或类型生成阶段自动产出的类型模块。Route.ComponentProps、Route.ActionArgs、Route.LoaderArgs等都从这里按需取用，具体机制参见 route-module 类型安全指南。
<fetcher.Form method="post">与传统表单的关键差异在于提交时navigate: false：数据只会发给当前路由的action，不会触发地址栏变更或页面级导航。想深入理解 navigational Form 与 fetcher.Form 的区别，可阅读 fetch 与 Form 的使用时机及 form-vs-fetcher 背景说明。
表单项通过name属性参与序列化，服务端将按这些name读取字段值。

2. 定义服务端 action：解析表单、校验并回传错误

在同一个signup.tsx模块中导出action函数。本指南侧重于讲清楚表单校验涉及的机制（提交数据如何流转、校验失败如何返回、状态码起什么作用），而不是深入某个具体校验规则库或错误对象结构，因此下面只对 email 与 password 做最基本的规则检查：

import type { Route } from "./+types/signup"; import { redirect, useFetcher, data } from "react-router"; export default function Signup(_: Route.ComponentProps) { // omitted for brevity } export async function action({ request, }: Route.ActionArgs) { const formData = await request.formData(); const email = String(formData.get("email")); const password = String(formData.get("password")); const errors = {}; if (!email.includes("@")) { errors.email = "Invalid email address"; } if (password.length < 12) { errors.password = "Password should be at least 12 characters"; } if (Object.keys(errors).length > 0) { return data({ errors }, { status: 400 }); } // Redirect to dashboard if validation is successful return redirect("/dashboard"); }

2.1 三个关键动作逐一拆解

读取表单数据。request来自Route.ActionArgs，是标准的 WebRequest对象；await request.formData()按multipart/form-data/application/x-www-form-urlencoded的标准解析请求体，返回一个FormData。接着用formData.get("email")/get("password")按表单控件的name取值，并统一包一层String()，把null（字段缺失）等情况收敛成可比较的字符串。整套动作与原生 Fetch 语义完全一致，无框架黑魔法。

校验并把错误组织成对象。示例把每个字段的错误文本存入errors对象（errors.email、errors.password）。实际项目里这里可以替换为 zod / valibot 等第三方校验库的返回值，本指南只关心 React Router 负责的“传输与状态”部分。

通过data()携带状态码返回。data({ errors }, { status: 400 })是失败路径的返回值——它把错误数据与一个 400（Bad Request）状态码捆绑返回给发起请求的 fetcher。从源码可以看到，data()在 router/utils.ts 中返回一个DataWithResponseInit包装：

export function data<D>(data: D, init?: number | ResponseInit) { return new DataWithResponseInit( data, typeof init === "number" ? { status: init } : init, ); }

也就是说它既允许传数字状态码（内部自动包装为{ status: init }），也允许传完整的ResponseInit（自定义 header、其他状态码等）。该工具同时从 server-runtime/single-fetch.ts 作为服务端响应工具导出，是 framework 模式下 action/loader 返回结构化数据（可包含Date、Map、Error、Promise等可序列化类型）的入口之一。官方 API 细节见 data() 工具文档。

校验成功则重定向。return redirect("/dashboard")让用户跳转到仪表盘页，属于标准的“PRG（Post-Redirect-Get）”收尾。

2.2 为什么校验失败要用 400 而不是 200

这段代码里，data({ errors }, { status: 400 })中的status: 400绝非可有可无：

语义上，400 是 Web 标准中表示“请求本身有误（Bad Request）”的通用状态码，用它向客户端传达“这不是服务器故障，而是你提交的数据需要修正”，也便于前端错误日志、监控与可观测性系统分类。
机制上，React Router 中 action 成功后默认会触发一次数据重新校验（revalidation），让loader的最新数据回流到 UI。而这条逻辑对 4xx/5xx 的响应是“关掉的”。

其实现位于 router/router.ts：

// Don't revalidate loaders by default after action 4xx/5xx responses // when the flag is enabled. They can still opt-into revalidation via // `shouldRevalidate` via `actionResult` let actionStatus = pendingActionResult ? pendingActionResult[1].statusCode : undefined; let shouldSkipRevalidation = actionStatus && actionStatus >= 400;

代码注释与该逻辑共同说明：当 action 返回 400 这类状态码时，路由会跳过默认的 loader 重新验证，因为数据没有发生任何合法变更，没有必要为了“展示错误”而重跑一遍 loader。反过来说，只有当返回 2xx（或发生 3xx 重定向）时，action 才会按正常流程触发数据重验证并继续导航/更新逻辑。这就是“用 400 隔离校验失败与正常提交”的底层原因。

2.3 这条链路的服务端执行概况

在 framework 模式下，action 请求由服务端处理管线接管。server-runtime/single-fetch.ts 中的singleFetchAction会在执行前做 CSRF 防护检查（throwIfPotentialCSRFAttack），随后把请求交给staticHandler.query完成 action 路由匹配与执行。这意味着你写的 action 并不是被“随手调用”的，而是与 loader、middleware 一样被纳入统一的数据策略与请求管线，相关机制参见 client-data 指南与>export default function Signup(_: Route.ComponentProps) { let fetcher = useFetcher(); let errors = fetcher.data?.errors; return ( <fetcher.Form method="post"> <p> <input type="email" name="email" /> {errors?.email ? <em>{errors.email}</em> : null} </p> <p> <input type="password" name="password" /> {errors?.password ? ( <em>{errors.password}</em> ) : null} </p> <button type="submit">Sign Up</button> </fetcher.Form> ); }

要点如下：

fetcher.data保存最近一次由该 fetcher 发起的 action/loader 成功返回的数据。当 action 返回data({ errors }, { status: 400 })时，虽然状态码是 400，但这属于“业务性错误响应”，会被正常交给 fetcher 而非抛给错误边界，因此fetcher.data?.errors能拿到错误对象。
用errors?.email、errors?.password做存在性判断，存在则就地渲染<em>错误文本；不存在则渲染null，UI 保持干净。
校验通过时 action 走redirect("/dashboard")，页面随之导航离开，这里的错误展示逻辑自然不再可见。

3.1 深入：fetcher.Form 的“不导航”承诺从何而来

回顾 dom/lib.tsx 中FetcherForm的实现：

let FetcherForm = React.forwardRef<HTMLFormElement, FetcherFormProps>( (props, ref) => { return ( <Form {...props} navigate={false} fetcherKey={fetcherKey} ref={ref} /> ); }, ); FetcherForm.displayName = "fetcher.Form";

fetcher.Form本质上是给普通Form强制注入了navigate={false}与本次调用唯一的fetcherKey。再结合useFetcher在 dom/lib.tsx 中的定义可以看到：

未显式传入key时，fetcher 使用React.useId()生成组件私有的默认 key；传入key则可以在应用任意位置共享同一个 fetcher 的状态。
组件挂载时在 router 中注册 fetcher，卸载时通过useEffect清理，避免内存泄漏。
fetcher 自带独立状态机：fetcher.state取值为"idle" | "loading" | "submitting"（submitting期间表单可显示 pending UI），fetcher.data存放返回数据。可通过 useFetcher 官方文档查看完整签名。

因此你可以在同一个页面放多个<fetcher.Form>，各自提交互不干扰、互不引发页面跳转——这正是复杂动态界面（搜索联想、行内编辑、批量操作）需要的交互模型。

3.2 错误展示位置的权衡：fetcher.data 与 action 数据再校验

本示例把错误直接渲染在触发提交的组件里，因为错误源与展示源在同一个 fetcher 作用域内。若你的错误需要渲染在“别的路由/别的组件”（例如表单挂在 layout 上、错误提示要在别处显示），React Router 还提供useActionData()等机制与 fetcher 体系配合；同时，错误展示组件也要考虑 Error Boundary 的兜底（非 4xx 校验类错误之外的渲染错误，交由 error-boundary 指南处理），这些都属于在基础链路上的进阶组合。

4. 完整链路回顾与可扩展方向

至此这条表单校验链路是自洽的：

用户提交<fetcher.Form method="post">，请求以navigate: false的方式进入signup路由的action，不发生页面导航；
action 用request.formData()读取字段、执行校验；
有错误时data({ errors }, { status: 400 })返回——4xx 状态既符合 Web 语义，又让 React Router 跳过无意义的 loader 重新验证，fetcher.data承接错误数据；
组件读取fetcher.data?.errors就地渲染错误；
校验通过则redirect("/dashboard")，完成注册跳转并触发正常的数据重新验证。

在此基础上，你还可以自然地扩展（均不影响本文所述的骨架机制）：

引入第三方校验库：把手工if检查替换为 zod/valibot 的 schema 校验，错误结构归一后仍用data({ errors }, { status: 400 })返回；
按字段保留用户输入：校验失败时让表单保留用户已填内容，仅标记错误字段，避免用户重填；
与路由 action 体系打通：若你更希望整页导航 + 通过useActionData读取错误，可参考 actions 入门；同一份 action 返回值对两种读取方式都成立；
类型安全：action 的返回值经data()后会被类型推断到 fetcher/useActionData侧，配合 route-module 类型安全指南可以让errors.email等访问在编译期即被检查，避免手写as断言带来的漂移风险。