Redwood 表单指南：基于 React Hook Form 的 `@redwoodjs/forms` 完整实战

后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载Redwood 在redwoodjs/forms包中提供了一系列表单辅助组件它们是对 React Hook FormRHF的轻量封装让你用声明式的 JSX 就能完成校验、错误样式、服务端错误展示与类型转换。本文以 Redwood 官方文档docs/versioned_docs/version-5.x/forms.md为骨架结合packages/forms/src下的真实源码实现系统讲解每个组件的用法、validation/emptyAs等核心 Props 的行为细节以及如何通过useRegister、useErrorStyles和 RHF 的Controller打造自定义字段读完即可在 Redwood 项目中写出既符合 GraphQL 类型要求又具备完整校验与错误反馈的表单。核心思路Redwood 表单 React Hook Form GraphQL 友好的增强Redwood 的表单辅助组件绝大多数都是 React Hook Form 的简单封装目标是让常用场景更简单。如果内置辅助组件不够灵活你可以直接使用 React Hook Form——redwoodjs/forms重新导出了它的全部导出见 index.tsx 中的export * from react-hook-formimport { useForm, useFormContext, // 或者 React Hook Form 导出的任何其他内容 } from redwoodjs/forms与此同时Redwood 在 RHF 之上做了针对 GraphQL 的扩展。源码注释coercion.ts明确指出RHF 原生提供valueAsDate、valueAsNumber但 Redwood 因后端使用 GraphQL额外增加了valueAsBoolean和valueAsJSON两个类型转换辅助项加上emptyAs空值处理 Props构成了redwoodjs/forms独有的三个能力见 index.tsx 的模块注释。组件全景概览redwoodjs/forms导出的核心组件如下来源于文档的组件表并可在 index.tsx 的导出列表中一一对应验证组件说明Form包裹所有表单组件提供表单上下文与错误上下文FormError展示服务端返回的错误信息通常放在表单顶部Label替代 HTMLlabel接受错误样式相关 PropsInputField替代 HTMLinput接受校验与错误样式 PropsSelectField替代 HTMLselect接受校验与错误样式 PropsTextAreaField替代 HTMLtextarea接受校验与错误样式 PropsFieldError当同name的字段存在校验错误时展示错误消息否则不渲染Submit替代button typesubmit触发校验与提交执行传给Form的onSubmit所有 HTMLinput类型都有对应的命名组件命名规则为TypeField其中Type为 HTML input 类型之一。文档列出的完整列表为ButtonField、CheckboxField、ColorField、DateField、DatetimeLocalField、EmailField、FileField、HiddenField、ImageField、MonthField、NumberField、PasswordField、RadioField、RangeField、ResetField、SearchField、SubmitField、TelField、TextField、TimeField、UrlField、WeekField。从源码看这些命名组件并非逐个手写而是在 InputComponents.tsx 中维护了一个INPUT_TYPES常量数组其中不含checkbox因为复选框有单独的 CheckboxField.tsx 实现再用pascalcase元编程批量生成INPUT_TYPES.forEach(...)见 InputComponents.tsx每个组件本质上都是InputField type{...} /的预置版本。校验与错误样式 Props所有以Field结尾的组件即全部输入字段以及SelectField、TextAreaField都接受三类 Propsvalidation接受 React Hook Formregister的全部选项外加 Redwood 独有的类型转换辅助项valueAsBoolean、valueAsJSON。对应源码类型为RedwoodRegisterOptionscoercion.tserrorClassName/errorStyle字段出错时替换className/style使用的类名与内联样式。除name外传给这些组件的其他 Props 都会透传给其渲染的原生标签。参考表Prop说明name字段名称React Hook Form 以它作为 key 把所有逻辑串联起来validation所有校验逻辑接受 RHF 的register选项与 Redwood 扩展项errorClassName出错时应用的类名errorStyle出错时应用的样式典型示例一个带校验的联系表单import { Form, Label, TextField, TextAreaField, FieldError, Submit, } from redwoodjs/forms const ContactPage () { const onSubmit (data) { console.log(data) } return ( Form onSubmit{onSubmit} Label namename classNamelabel errorClassNamelabel error / TextField namename classNameinput errorClassNameinput error validation{{ required: true }} / FieldError namename classNameerror-message / Label nameemail classNamelabel errorClassNamelabel error / TextField nameemail classNameinput errorClassNameinput error validation{{ required: true, pattern: { value: /[^][^\.]\../, }, }} / FieldError nameemail classNameerror-message / Label namemessage classNamelabel errorClassNamelabel error / TextAreaField namemessage classNameinput errorClassNameinput error validation{{ required: true }} / FieldError namemessage classNameerror-message / Submit classNamebuttonSave/Submit /Form ) }注意validation{{ required: true }}时 RHF 默认的错误消息会由FieldError按错误类型补全详见下文FieldError小节而带pattern等自定义校验时建议通过validation中的message字段或直接借助默认文案。Form表单上下文的总入口凡是要让 Redwood 在校验失败时改变样式、在提交时执行回调的表单都应该被Form包裹。Prop说明config接受一个对象内容为 React Hook FormuseForm钩子的选项formMethodsuseForm返回的函数集合。仅当你需要访问useForm返回的某个函数如下例的reset时才需要onSubmit校验成功后调用的函数入参为包含表单所有字段 name-value 对的对象其他所有 Props 都会透传给其渲染的form标签。Form的内部机制从 Form.tsx 的实现可以看到Form实际封装了三层内部调用useForm(config)创建表单实例若传入了formMethods则优先使用外部实例将errorProps 中 GraphQL 错误扩展里的字段消息errorProps?.graphQLErrors?.[0]?.extensions?.properties?.messages注入ServerErrorsContext供useErrorStyles消费通过FormProvider把表单实例下发给任意深度的子组件使所有辅助组件能用useFormContext拿到register等函数。理解这一点很重要RHF 走的是非受控组件路线register是它的核心钩子函数作用是把字段注册进表单以便校验。Redwood 的辅助组件无法直接从Form逐层拿到register组件可能嵌套任意深度所以借助FormProvider上下文传递这正是 useRegister.ts 中const { register } useFormContext()的由来。使用formMethods访问useForm返回函数useForm返回的一些函数比如重置表单的reset在组件内部很有用。要访问它们需要自己调用useForm但同时仍要把返回值传给FormProvider让 Redwood 的辅助组件能够注册自身import { useForm } from react-hook-form const ContactPage () { const formMethods useForm() const onSubmit (data) { console.log(data) formMethods.reset() } return ( Form formMethods{formMethods} onSubmit{onSubmit} {/* 依旧正常工作 */} TextField namename validation{{ required: true }} / /Form ) }config与formMethods的区别在于config是传给内部useForm的选项对象如{ mode: onBlur }而formMethods是你自己调用useForm拿到的完整返回对象直接接管表单实例。FormError展示服务端错误FormError会渲染一个div内含一个标题消息和一个ul逐条列出服务端在保存表单时报告的错误。如果你提交了一个侥幸通过客户端校验的表单在 scaffold 生成的页面中就能看到它的表现。例如下面的表单里TextField没有配置任何校验import { useMutation } from redwoodjs/web const CREATE_CONTACT gql mutation CreateContactMutation($input: ContactInput!) { createContact(input: $input) { id } } const ContactPage () { const [create, { loading, error }] useMutation(CREATE_CONTACT) const onSubmit (data) { create({ variables: { input: data }}) } return ( Form onSubmit{onSubmit} FormError error{error} / {/* 没有校验——什么邮箱都能提交 */} TextField nameemail / /Form ) }客户端没有校验什么都能提交但 GraphQL 是强类型系统不会放行非法数据。它会抛出错误通过useMutation返回的error对象冒泡到顶部由FormError渲染出类似内容div p Cant create new contact: /p ul li email is not formatted like an email address /li /ul /div从源码FormError.tsx看FormError的解析逻辑很有层次若没有error直接返回null若存在 GraphQL 错误顶部消息取graphQLErrors[0].message并且当extensions.code BAD_USER_INPUTService Validation 错误时标题会被覆盖为Errors prevented this form from being saved字段级消息则从extensions.properties.messages中展开若无 GraphQL 错误但有网络错误networkError会尝试解析bodyTextServer Parse Error或result.errorsServer Error中的消息。它还支持wrapperClassName、titleClassName、listClassName、listItemClassName及对应 Style Props用于整体控制错误块的样式。Label可感知错误的标签Label渲染 HTMLlabel标签并根据关联字段是否存在校验错误切换className和style。它既可以自闭合此时name即标签文本Label namename classNameinput errorClassNameinput error / !-- 渲染为label forname classinputname/label --也可以写成成对标签并放入自定义文本此时该文本即为渲染出的标签文字Label namename classNameinput errorClassNameinput errorYour Name/Label !-- 渲染为label forname classinputYour Name/label --除下表列出的 Props 外其余 Props 全部透传给底层labelProp说明name关联字段名应与对应输入字段的name一致errorClassName同name字段存在校验错误时使用的类名errorStyle同name字段存在校验错误时使用的样式实现上Label.tsx 会渲染label htmlFor{name}htmlFor与输入字段的id默认等于name见 InputComponents.tsx配对保证点击标签可聚焦输入框错误样式的切换则复用useErrorStyles。输入字段Input Fields输入框是绝大多数表单的骨干。虽然你可以用InputField加typeProps 做出各种输入框但通常直接使用命名输入字段更省事——它们针对特定类型预置了合适的默认行为尤其是类型转换。默认类型转换Coercion以下字段会自动做类型转换你也可以随时用validation里的setValueAs覆盖或手动实现字段默认转换CheckboxFieldvalueAsBooleanNumberFieldvalueAsNumberDateFieldvalueAsDateDatetimeLocalFieldvalueAsDatevalueAsDate和valueAsNumber是 React Hook Form 内置的、基于 HTML 标准的转换。但因为 Redwood 后端使用 GraphQL表单提交的类型必须与 GraphQL 服务端期望一致。为避免用户大量手写setValueAsRedwood 在 RHF 的valueAs系列之上额外提供了两个便捷项valueAsBooleanvalueAsJSON源码层面setCoercioncoercion.ts负责整个转换流程的编排当设置了valueAsJSON时会把校验函数替换为JSONValidation解析失败返回NaN时判为无效并删掉valueAsJSON标记当类型为date/datetime-local或显式设置valueAsNumber时也分别走对应分支最终统一把转换逻辑包装成 RHF 的setValueAs函数。空输入值的默认处理Redwood 对空输入值提供了灵活的处理机制合理的空值语义能让数据库关联字段的处理变得更简单。空字段行为由以下优先级规则决定若用户指定了setValueAs由该函数决定空字段行为若设置了emptyAsProp则emptyAs决定空字段的值取值见下文若设置了validation { required: true }空字段返回null——同时 RHF 的required校验会生效阻止空值表单提交若字段是 Id 字段name以Id结尾空字段返回null这对大多数数据库关联字段是最合适的值需要其他值时可使用emptyAs覆盖若以上均不适用空字段按字段类型采用默认值DateFields →nullNumberFields →NaNTextFields withvalueAsNumber→NaNSelectFields withvalueAsNumber→NaNSelectFields withoutvalueAsNumber→空字符串TextFields withvalueAsJSON→nullTextFields 及同类 →空字符串这套决策链在源码中有完整对应实现coercion.ts 的注释详细记录了上述 5 条规则getSetValueAsFncoercion.ts则按emptyAs、required、isId即name.endsWith(Id)组合出具体的转换函数SET_VALUE_AS_FUNCTIONS表中为valueAsDate、valueAsJSON、valueAsNumber、valueAsString四种类型各自实现了emptyAsNull、emptyAsUndefined、emptyAsZero、emptyAsString、emptyAsNaN等变体。emptyAs PropemptyAs允许用户在未指定setValueAs的情况下覆盖字段为空时的默认返回值。可选值有nullundefined0空字符串例如NumberField namequantity emptyAsundefined / NumberField namescore emptyAs{null} /第一个字段为空时返回undefined第二个字段为空时返回null。需要注意的是源码 coercion.ts 有明确说明RHF 的setValueAs对复选框不生效因此 Redwood 目前不为CheckboxField提供emptyAs功能同时若valueAsNumber与emptyAs同时使用Redwood 会删除valueAsNumber改由内部的setValueAs完成等价转换coercion.ts以保证emptyAs的优先级。自定义输入字段useRegister 与 useErrorStyles你可以通过 Redwood 提供的useRegister和useErrorStyles两个 Hook 创建与 Redwood 体系无缝集成的自定义字段useRegister把字段注册进 React Hook Form是 RHFregister的包装useRegister.ts。它会调用setCoercion注入默认转换合并onBlur/onChange回调并返回可直接展开到原生元素上的{ ref, onBlur, onChange, ... }若缺失name会抛出错误name prop must be provided。useErrorStyles为自定义字段建立错误样式。其实现useErrorStyles.ts会读取useFormContext的formState.errors和ServerErrorsContext中的服务端错误若存在服务端错误还会通过setError(name, { type: server, message })把它写入表单状态当字段存在校验错误时用errorClassName/errorStyle替换className/style。两者结合即可创建既复刻 Redwood 字段行为、又包含自定义领域逻辑的字段。下面是一个集标签、输入框、错误展示于一体的必填自定义字段import { FieldError, useErrorStyles, useRegister } from redwoodjs/forms const RequiredField ({ label, name, validation }) { const register useRegister({ name, validation: {...validation, required: true} }) const { className: labelClassName, style: labelStyle } useErrorStyles({ className: my-label-class, errorClassName: my-label-error-class, name, }) const { className: inputClassName, style: inputStyle } useErrorStyles({ className: my-input-class, errorClassName: my-input-error-class, name, }) return ( label className{labelClassName} style{labelStyle}{label}/label input className{inputClassName} style{inputStyle} typetext {...register} / FieldError name{name} / / ) }受控组件字段结合 RHF 的 Controller如果你在使用功能完整的组件库或拥有自研的生产级组件可以通过 Redwood 的useErrorStyles配合 React Hook Form 的Controller组件将它们无缝集成进 Redwood 表单。下面是用primereact的ToggleButton封装成 Redwood 风格命名字段的示例web/src/components/ToggleButtonField/ToggleButtonField.tsximport { ToggleButton } from primereact/togglebutton import type { ToggleButtonProps } from primereact/togglebutton import { Controller, RegisterOptions, useErrorStyles } from redwoodjs/forms interface Props extends ToggleButtonProps { validation?: RegisterOptions errorClassName?: string } const ToggleButtonField (props: Props) { const { name, className, errorClassName, defaultValue, validation, style, ...propsRest } props const { className: componentClassName, style: componentStyle } useErrorStyles({ className: className, errorClassName: errorClassName, name: name, }) return ( Controller name{name} defaultValue{defaultValue} rules{validation} render{({ field: { onChange, onBlur, value, name, ref } }) ( ToggleButton {...propsRest} checked{value} onChange{onChange} onBlur{onBlur} ref{ref} name{name} className{componentClassName} style{{ ...componentStyle, ...style }} / )} / ) } export default ToggleButtonField核心要点Controller负责把受控组件的值、变更回调与表单状态绑定useErrorStyles负责错误时切换样式rules{validation}把校验规则交给 RHF 执行。这样封装出来的组件在使用上与redwoodjs/forms的命名输入字段完全一致。SelectField下拉选择框SelectField渲染 HTMLselect标签支持用multipleProps 多选。当multiple为true时字段返回的值数组按选项在列表中的顺序排列而不是用户选择的顺序SelectField nametoppings multiple{true} optionlettuce/option optiontomato/option optionpickle/option optioncheese/option /SelectField // 如果用户选择了 lettuce、tomato 和 cheese // onSubmit 处理器收到 // // { toppings: [lettuce, tomato, cheese] }校验下面的两个例子分别演示了单选与多选场景下必须选择且不能选第一个占位选项的校验SelectField nameselectSingle validation{{ required: true, validate: { matchesInitialValue: (value) { return ( value ! Please select an option || Select an Option ) }, }, }} optionPlease select an option/option optionOption 1/option optionOption 2/option /SelectField FieldError nameselectSingle style{{ color: red }} /SelectField multiple{true} nameselectMultiple validation{{ required: true, validate: { matchesInitialValue: (value) { let returnValue [true] returnValue value.map((element) { if (element Please select an option) return Select an Option }) return returnValue[0] }, }, }} optionPlease select an option/option optionOption 1/option optionOption 2/option /SelectField FieldError nameselectMultiple style{{ color: red }} /注意validate的返回值语义返回true表示通过返回字符串则视为该字符串为错误消息。上面的写法正是利用这一特性把Select an Option作为校验失败时的提示文案。类型转换通常情况下SelectField返回字符串但你可以用valueAs系列属性让返回值变成其他类型。典型场景是用下拉框选择数字型 ID不使用valueAsNumber时返回字符串开启后则返回数字对应 GraphQL 的IntSelectField nameselect validation{{ valueAsNumber: true }} option value{1}Option 1/option option value{2}Option 2/option option value{3}Option 3/option /SelectField如果用户选择了Option 3Form的onSubmit收到的数据为{ select: 3, }注意此场景下 Redwood 的emptyAs与valueAsNumber的交互当二者同时出现时Redwood 会在内部用setValueAs承担转换职责见 coercion.ts空值行为仍由emptyAs决定未设emptyAs时空选返回NaN。FieldError字段级错误消息FieldError在具有相同name属性的字段存在校验错误时渲染一个包含错误消息的span否则什么都不渲染。FieldError namename classNameerror-message / !-- 渲染为span classerror-messagename is required/span --从 FieldError.tsx 可以看到当校验错误未提供自定义message时Redwood 会按错误类型给出默认文案错误类型默认消息requiredis requiredpatternis not formatted correctlyminLengthis too shortmaxLengthis too longminis too lowmaxis too highvalidateis not valid最终渲染的文本为${name} ${DEFAULT_MESSAGES[type]}如name is required若validation中提供了message则优先使用。FieldError在错误不存在时返回null因此可以放心地在每个字段下方放置不会产生多余 DOM。测试与验证redwoodjs/forms的测试集中在 packages/forms/src/tests/form.test.tsx覆盖了字段注册、校验、emptyAs空值行为、服务端错误注入等关键路径。如果你要验证自定义字段的行为是否符合预期可以参考该测试文件中的写法用testing-library/react渲染表单并断言提交数据与错误样式。小结与最佳实践优先使用命名输入字段TextField、NumberField、DateField等已针对类型预置了默认转换InputComponents.tsx 批量生成比手动设置InputField type更省心重视空值语义数据库关联字段name以Id结尾为空时自动返回null需要其他空值语义时用emptyAs自定义转换时用setValueAs优先级最高善用 GraphQL 友好的转换valueAsBoolean、valueAsJSON让前端提交的数据类型与 GraphQL 服务端期望对齐避免大量手写setValueAs服务端错误展示在表单顶部放置FormError error{error} /配合useMutation返回的error对象BAD_USER_INPUT类型错误会自动展示字段级消息同时useErrorStyles会把服务端字段错误同步到对应输入框的错误样式见 useErrorStyles.ts需要 RHF 高级能力时直接使用useForm并通过formMethods传入Form或使用Controller集成受控组件库封装自定义字段非受控场景用useRegisteruseErrorStyles受控组件库场景用ControlleruseErrorStyles。更多相关上下文可继续阅读 docs/docs/forms.md当前版本以及 Redwood 教程中关于表单的章节docs/docs/tutorial理解表单在真实 CRUD 页面中的完整用法。赞分享后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载相关推荐Redwood Forms 完全指南基于 React Hook Form 的声明式表单开发Redwood Forms 完全指南基于 React Hook Form 的声明式表单开发 Redwood 框架在 redwoodjs/forms 中提供了后端前端Web框架开发工具Redwood 表单体系完全指南基于 redwoodjs/forms 与 React Hook Form 的验证、错误处理与类型转换实战Redwood 表单体系完全指南基于 redwoodjs/forms 与 React Hook Form 的验证、错误处理与类型转换实战 导读 redwo后端前端Web框架开发工具Redwood Forms 完全指南基于 React Hook Form 的表单构建与校验体系Redwood Forms 完全指南基于 React Hook Form 的表单构建与校验体系 Redwood 框架通过 redwoodjs/forms 包后端前端Web框架开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考