React Suite 集成 React Hook Form 实战指南：Controller 桥接、校验与 Yup Resolver 完整方案

• 前端
• UI组件

React Suite（rsuite）的表单组件可以无缝接入 React Hook Form —— 一个轻量、灵活且功能强大的表单状态与校验管理库。本文以仓库中docs/pages/components/form-react-hook-form/的官方示例文档为骨架，系统讲解如何在 rsuite 项目中通过Controller桥接非受控表单库与 rsuite 组件、如何配置字段级校验与Form.ErrorMessage错误展示，以及如何通过@hookform/resolvers接入 Yup、Zod 等 Schema 校验体系，并扩展到DatePicker、Rate等更多数据录入组件。读完本文，你将掌握一套可直接复制运行的「rsuite + React Hook Form」表单方案。

为什么需要 Controller：React Hook Form 与 rsuite 的桥接模式

React Hook Form 的核心设计是"非受控"（uncontrolled）表单：它通过ref直接读取 DOM 输入值，避免每次击键都触发组件重渲染。但 rsuite 的组件（如Input、DatePicker、Rate）并不暴露可供注册的底层原生ref值，而是通过受控的value+onChange接口管理数据。此时就需要 React Hook Form 官方提供的Controller包装组件来充当桥梁：

• Controller负责把 React Hook Form 内部状态中的value注入到 rsuite 组件的value属性；
• rsuite 组件通过onChange回调把新值上报给Controller，从而写回 React Hook Form 的control；
• 通过render函数，你可以完全掌控 rsuite 组件如何渲染、如何挂载错误信息。

官方示例（basic.md）展示了最基础的接入方式：

import { useForm, Controller } from 'react-hook-form'; import { Input, Button, Form } from 'rsuite'; const App = () => { const defaultValues = { name: '', email: '' }; const { control, handleSubmit } = useForm({ defaultValues }); const onSubmit = data => alert(JSON.stringify(data, null, 2)); return ( <Form onSubmit={handleSubmit(onSubmit)}> <Form.Stack fluid> <Controller name="name" control={control} render={({ field, fieldState }) => ( <Form.Group> <Input id={field.name} value={field.value} onChange={value => field.onChange(value)} placeholder="Name" /> </Form.Group> )} /> <Controller name="email" control={control} render={({ field, fieldState }) => ( <Form.Group> <Input id={field.name} value={field.value} onChange={value => field.onChange(value)} placeholder="Email" /> </Form.Group> )} /> <Button appearance="primary" type="submit"> Submit </Button> </Form.Stack> </Form> ); }; ReactDOM.render(<App />, document.getElementById('root'));

这段代码中值得注意的对接细节：

1. useForm({ defaultValues })：在调用useForm时通过defaultValues声明字段初始值，React Hook Form 会据此初始化内部状态；如果省略，字段首次渲染时值为undefined，可能导致 rsuite 组件非受控告警，因此强烈建议为每个字段显式声明初始值。
2. field.value与field.onChange：Controller的render回调把field（即{ value, onChange, onBlur, ref, ... }）暴露给你。rsuite 的Input的onChange签名是(value: string, event) => void（见 Input.tsx 的类型定义），与field.onChange(value)天然匹配，所以这里直接写成onChange={value => field.onChange(value)}即可。
3. Form+handleSubmit：rsuite 的Form最终渲染为原生<form>元素并接管onSubmit（见 Form.tsx 中onSubmit={handleSubmit}），因此只需把 React Hook Form 的handleSubmit(onSubmit)交给Form，提交时 React Hook Form 会先完成校验，通过后才调用你的onSubmit回调。

关于Form.Stack fluid：Form.Stack是基于 Flexbox 的快速布局组件（见 FormStack.tsx），fluid让表单元素撑满容器宽度（仅在 vertical 布局下生效），layout 默认'vertical'，可选'horizontal' | 'vertical' | 'inline'。

可复用 Field 组件：封装 Controller 的渲染逻辑

观察上面的例子，每个字段都要写一遍<Form.Group>、<Component>和错误展示代码，字段一多就非常啰嗦。官方文档的后续示例（validation.md、yup-schema-validation.md、other-input-components.md）统一提炼了一个可复用的Field组件：

const Field = ({ as: Component = Input, field, error, ...rest }) => { return ( <Form.Group> <Component id={field.name} value={field.value} onChange={value => field.onChange(value)} {...rest} /> <Form.ErrorMessage show={!!error} placement="bottomStart"> {error} </Form.ErrorMessage> </Form.Group> ); };

这个封装解决了三个实际问题：

• as属性：允许把任意 rsuite 数据录入组件作为字段渲染（默认Input）。因为 rsuite 的数据录入组件大多遵守value+onChange的统一接口约定，只要onChange首个参数是"新值"，就能与field.onChange对接——这正是后续用同一个Field渲染DatePicker、Rate的通用性来源。
• Form.Group：提供字段的分组容器，用于承载输入控件与错误信息，保证布局结构清晰。
• Form.ErrorMessage：rsuite 的错误提示组件，show控制是否显示，placement控制提示气泡位置（示例中为bottomStart）。从 FormErrorMessage.tsx 源码看，当show为真时渲染带箭头的气泡式提示，否则返回null，因此show={!!error}确保只有存在错误消息时才展示。

字段级校验：rules 规则与错误信息渲染

React Hook Form 内置了轻量的字段级校验能力，通过Controller的rules属性声明即可，无需引入任何 Schema 库。官方 validation.md 示例：

const App = () => { const defaultValues = { name: '', email: '' }; const { control, handleSubmit, formState: { errors } } = useForm({ defaultValues }); const onSubmit = data => alert(JSON.stringify(data, null, 2)); return ( <Form onSubmit={handleSubmit(onSubmit)}> <Form.Stack fluid> <Controller name="name" control={control} rules={{ required: 'Name is required' }} render={({ field, fieldState }) => ( <Field field={field} error={errors[field.name]?.message} placeholder="Name" /> )} /> <Controller name="email" control={control} rules={{ required: 'Email is required', pattern: { value: /\S+@\S+\.\S+/, message: 'Invalid email' } }} render={({ field, fieldState }) => ( <Field field={field} error={errors[field.name]?.message} placeholder="Email" /> )} /> <Button appearance="primary" type="submit"> Submit </Button> </Form.Stack> </Form> ); };

核心要点：

1. rules与 React Hook Form 内置校验：rules支持required、pattern、min、max、minLength、maxLength、validate等标准规则。required的值既可以是布尔值，也可以直接是字符串——字符串将作为校验失败时的错误消息，示例中required: 'Name is required'即此用法。
2. 从formState.errors读取错误：useForm解构出的formState.errors是一个以字段名为 key、以{ type, message }为 value 的对象。示例通过errors[field.name]?.message取到错误文案，传给Field组件的error属性。
3. 注意??.可选链：字段未出错时errors[field.name]为undefined，可选链保证不会抛错，error为undefined时show={!!error}为false，错误提示自然隐藏。
4. 与 rsuite 的错误展示协作：rsuite 的Form.ErrorMessage只负责"展示"传入的错误文本，真正的"校验职责"完全由 React Hook Form 承担，二者各司其职、互不冲突。

提示：如果你熟悉 rsuite 自带的schema-typed校验体系（<Form model={...}>），可以发现两者思路类似但实现不同：rsuite 的Form也支持resolver属性接入第三方校验库（见 Form.tsx 的类型注释），不过本文聚焦 React Hook Form 方案，model/resolver二选一即可，无需混用。

与 Yup 集成：resolver 模式下的 Schema 校验

对于复杂表单，字段级rules会越写越散。React Hook Form 官方提供了 validation resolver）。

官方 yup-schema-validation.md 示例：

import { useForm, Controller } from 'react-hook-form'; import { Input, Button, Form } from 'rsuite'; import { yupResolver } from '@hookform/resolvers/yup'; import * as yup from 'yup'; const Field = ({ as: Component = Input, field, error, ...rest }) => { return ( <Form.Group> <Component id={field.name} value={field.value} onChange={value => field.onChange(value)} {...rest} /> <Form.ErrorMessage show={!!error} placement="bottomStart"> {error} </Form.ErrorMessage> </Form.Group> ); }; const validationSchema = yup.object().shape({ name: yup.string().required('Required'), email: yup.string().email('Invalid email address').required('Required') }); const App = () => { const defaultValues = { name: '', email: '' }; const { control, handleSubmit, formState: { errors } } = useForm({ defaultValues, resolver: yupResolver(validationSchema) }); const onSubmit = data => alert(JSON.stringify(data, null, 2)); return ( <Form onSubmit={handleSubmit(onSubmit)}> <Form.Stack fluid> <Controller name="name" control={control} render={({ field, fieldState }) => ( <Field field={field} error={errors[field.name]?.message} placeholder="Name" /> )} /> <Controller name="email" control={control} render={({ field, fieldState }) => ( <Field field={field} error={errors[field.name]?.message} placeholder="Email" /> )} /> <Button appearance="primary" type="submit"> Submit </Button> </Form.Stack> </Form> ); };

与上一节对照，接入 Yup 只需要两处变化：

1. 定义 Yup Schema：用yup.object().shape({...})声明字段规则与自定义错误消息（'Required'、'Invalid email address'）。required()与.email()等方法链式组合出校验逻辑。
2. 传入resolver：在useForm({ defaultValues, resolver: yupResolver(validationSchema) })中把 schema 包装进yupResolver，React Hook Form 会通过 resolver 统一执行校验并把错误映射回formState.errors，错误消息同样通过errors[field.name]?.message读取，因此视图层代码与rules方案完全一致，迁移成本极低。

可以推断的配套事实：yupResolver底层会把 Yup 校验结果转换为 React Hook Form 的FieldError结构（{ type, message, ref }），并合并到errors对象中；对于yup.object().shape中的每个字段，resolver 以字段路径为 key 返回错误，这正是示例中errors[field.name]能够取到对应消息的原因。

依赖安装参考（与文档站依赖版本一致）：npm install react-hook-form @hookform/resolvers yup，其中react-hook-form@^7.50.1、@hookform/resolvers@^3.3.4、yup@^1.3.3。若你使用其他校验库（Zod 等），只需把yupResolver换成对应的 resolver 实现。

扩展到更多数据录入组件：DatePicker 与 Rate

前面反复强调"rsuite 所有数据录入组件都能接入 React Hook Form"，官方 other-input-components.md 示例以DatePicker和Rate为例做了验证：

import { useForm, Controller } from 'react-hook-form'; import { DatePicker, Rate, Button, Form } from 'rsuite'; import { yupResolver } from '@hookform/resolvers/yup'; import * as yup from 'yup'; const Field = ({ as: Component = Input, field, error, ...rest }) => { return ( <Form.Group> <Component id={field.name} value={field.value} onChange={value => field.onChange(value)} {...rest} /> <Form.ErrorMessage show={!!error} placement="bottomStart"> {error} </Form.ErrorMessage> </Form.Group> ); }; const validationSchema = yup.object().shape({ date: yup.date().required('Date is required'), rating: yup.number() .required('Rating is required') .min(2, 'Rating must be at least 2') .max(5, 'Rating must be at most 5') }); const App = () => { const defaultValues = { date: new Date(), rating: 2 }; const { control, handleSubmit, formState: { errors } } = useForm({ defaultValues, resolver: yupResolver(validationSchema) }); const onSubmit = data => alert(JSON.stringify(data, null, 2)); return ( <Form onSubmit={handleSubmit(onSubmit)}> <Form.Stack fluid> <Controller name="date" control={control} render={({ field, fieldState }) => ( <Field as={DatePicker} field={field} error={errors[field.name]?.message} /> )} /> <Controller name="rating" control={control} render={({ field, fieldState }) => ( <Field as={Rate} field={field} error={errors[field.name]?.message} color="yellow" /> )} /> <Button appearance="primary" type="submit"> Submit </Button> </Form.Stack> </Form> ); };

这个示例的实战价值体现在三点：

1. Field的as泛化能力兑现：把Input换成DatePicker、Rate后，字段代码几乎不用改。rsuite 中这类组件（包括InputPicker、SelectPicker、Checkbox、Radio、Slider、Toggle等数据录入组件）均遵循value+onChange(新值)的受控接口，因此value={field.value}与onChange={value => field.onChange(value)}的桥接逻辑是通用的。
2. Yup 对非文本字段的校验：yup.date()校验日期对象、yup.number().min(2).max(5)校验评分范围，说明 Yup 能按字段类型进行类型化校验，并自定义各条规则的错误文案（'Date is required'、'Rating must be at least 2'等）。
3. defaultValues与受控初始值：date: new Date()、rating: 2直接为受控组件提供初始值，避免字段首次渲染时值为undefined的问题；Rate上还透传了color="yellow"这样的 rsuite 自有属性（经...rest传递），说明Field封装不影响 rsuite 组件自身的定制能力。

总结：rsuite + React Hook Form 的集成清单

最佳实践小结：

• 始终为每个字段声明defaultValues，避免受控组件拿到undefined；
• 用Controller（而非register）对接 rsuite 组件，因为 rsuite 组件不暴露原生 ref 读取路径；
• 简单校验用rules，复杂或需复用的校验逻辑用 resolver + Schema 库，两者错误消息都从formState.errors读取，视图层代码可保持一致；
• 通过可复用的Field组件统一Form.Group、控件渲染与Form.ErrorMessage展示，让表单代码保持整洁。

相关文档与源码索引：

• 官方集成文档总览：index.md
• 基础示例：basic.md / usage.md
• 校验示例：validation.md
• Yup 校验示例：yup-schema-validation.md
• 其他录入组件示例：other-input-components.md
• rsuite 表单容器实现：Form.tsx
• 输入组件接口：Input.tsx
• 布局与错误组件：FormStack.tsx / FormErrorMessage.tsx

• 前端
• UI组件