Formily 重置按钮 Reset 全面指南：@formily/antd 普通重置、强制清空与重置校验实战

前端UI组件【免费下载链接】formily Cross Device High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址https://gitcode.com/gh_mirrors/fo/formily点击查看免费下载本文聚焦 Formily 生态中formily/antd提供的Reset重置按钮组件。通过完整示例与源码级剖析你将掌握普通重置与强制清空forceClear的本质区别、重置后自动触发校验validate的用法、onClick阻塞重置的机制以及Reset底层如何通过form.reset()与 Formily 核心的batchReset/resetSelf联动。阅读完成后你可以在 JSON Schema 表单与纯 JSX 表单中自如地编排各种重置交互。为什么需要专门的 Reset 组件在 Formily 的架构里表单状态字段值、校验反馈、visited/modified 标记由formily/core的Form模型统一管理formily/antd则提供与 Ant Design 对齐的 UI 层组件。表单重置Reset并不是简单的把 DOM 里 input 的值清空而是一套涉及字段初始值回填、状态标记复位、生命周期事件派发、甚至校验重新执行的完整流程。因此formily/antd在 reset/index.tsx 中基于 Ant Design 的Button封装了Reset组件把点击按钮 → 调用form.reset()→ 处理校验结果这条链路直接暴露成声明式 JSX开发者无需手动useForm再写事件回调。Reset的组件签名如下源码见 packages/antd/src/reset/index.tsx#L7-L11export interface IResetProps extends IFieldResetOptions, ButtonProps { onClick?: (e: React.MouseEventElement, MouseEvent) any onResetValidateSuccess?: (payload: any) void onResetValidateFailed?: (feedbacks: IFormFeedback[]) void }它同时继承了IFieldResetOptions重置行为选项与 Ant Design 的ButtonProps其余属性全部透传给Button因此Reset在外观、禁用态、尺寸等方面与普通Button完全一致只额外增加了重置相关的能力。四个典型场景从普通重置到重置并校验原文档给出了四个递进的实战场景本文完整保留并逐一解析。四个示例都基于同一段表单两个输入框其中一个input2带有default123默认值。核心区别只在Reset上的forceClear与validate属性组合。场景一普通重置import React from react import { Input, FormItem, FormButtonGroup, Reset } from formily/antd import { createForm } from formily/core import { FormProvider, createSchemaField } from formily/react const SchemaField createSchemaField({ components: { Input, FormItem, }, }) const form createForm() export default () ( FormProvider form{form} SchemaField SchemaField.String nameinput title输入框 required x-decoratorFormItem x-componentInput / SchemaField.String nameinput2 title输入框 default123 required x-decoratorFormItem x-componentInput / /SchemaField FormButtonGroup Reset重置/Reset /FormButtonGroup /FormProvider )行为特征点击重置后用户输入的内容会被清空但带有默认值的控件无法被清空——input2会恢复到default123声明的值。这正是 Formily 重置语义的关键重置不是清空而是回到默认值。底层原因见 packages/core/src/shared/internals.ts#L988-L1006 中的resetSelf当字段存在值时默认分支取initialValue未显式设置则退回typedDefaultValue作为回填值forceClear未开启时不会把值强制写成默认值之外的空。也就是说只要字段声明了默认值普通重置就必然把它还原回去。场景二强制清空重置forceClear// 其余代码与场景一相同仅按钮部分改为 FormButtonGroup Reset forceClear重置/Reset /FormButtonGroup行为特征加上forceClear后无论字段是否有默认值都会被强制重置为类型化默认值typed default value实现真正意义上的清空。注意forceClear清空的对象是字段当前的 value而default作为 schema 声明仍保留在字段上。若再次触发普通重置或重新校验默认值依旧会生效。场景三重置并校验validate// 其余代码与场景一相同仅按钮部分改为 FormButtonGroup Reset validate重置/Reset /FormButtonGroup行为特征重置完成后立即对重置过的字段重新执行校验。结合上文表单中required约束重置后input空值会立刻触发必填错误反馈展示让用户第一时间看到当前状态是否合法。适用于重置后需要重新评估表单有效性的业务例如重置后立即判断提交按钮是否可点。场景四强制清空重置并校验forceClear validate// 其余代码与场景一相同仅按钮部分改为 FormButtonGroup Reset forceClear validate重置/Reset /FormButtonGroup行为特征两个能力叠加——先强制清空所有字段值再对重置结果执行校验。这是一键清空 实时反馈的完整形态常用于搜索表单的清空筛选条件按钮清空后立即校验空的必填项会马上给出提示避免用户带着过期错误继续操作。API 详解ResetReset除了继承 Ant Design Button 的全部 API其余属性参考 Ant Design Button 文档之外额外提供以下属性属性名类型描述默认值onClick(event: MouseEvent) void \| boolean点击事件如果返回false可以阻塞重置-onResetValidateSuccess(payload: any) void重置校验成功事件-onResetValidateFailed(feedbacks: IFormFeedback[]) void重置校验失败事件返回校验反馈数组-onClick 的阻塞机制这是Reset组件内部实现的第一道闸门。源码 packages/antd/src/reset/index.tsx#L24-L35 中点击时先执行用户传入的props.onClick当返回值严格等于false时直接return既不会调用form.reset也不会触发后续的校验回调。利用这一点可以实现二次确认重置弹窗确认后再重置或特定状态下禁止重置等拦截逻辑。onResetValidateSuccess / onResetValidateFailed仅当validate开启时才有意义。它们对应form.reset()返回的 Promise 的then与catch分支分别承接校验通过携带 payload与校验失败携带IFormFeedback[]反馈数组的结果。IFormFeedback是 Formily 核心定义的校验反馈结构包含type、code、messages等字段可用于自定义错误提示的二次加工。源码级原理Reset 的完整调用链理解Reset的行为关键在它点击后实际调用的 API 与核心实现。1. 获取表单实例useParentFormReset并不接收form属性而是通过formily/react的useParentForm()钩子从FormProvider上下文就近获取表单实例见 packages/react/src/hooks/useParentForm.ts。因此Reset必须渲染在FormProvider内部否则拿不到表单。2. 发起重置form.reset组件内部执行的核心调用是form .reset(*, { forceClear, validate, }) .then(onResetValidateSuccess) .catch(onResetValidateFailed)Form.reset的签名见 packages/core/src/models/Form.ts#L615-L617reset (pattern: FormPathPattern *, options?: IFieldResetOptions) { return batchReset(this, pattern, options) }pattern默认是*即重置表单下所有字段你也可以传字段路径如input只重置特定字段。options即IFieldResetOptions定义于 packages/core/src/types.ts#L388-L391export interface IFieldResetOptions { forceClear?: boolean validate?: boolean }3. 批量重置batchResetbatchResetpackages/core/src/shared/internals.ts#L926-L942会按pattern查询所有匹配字段跳过VoidField对每个数据字段执行resetSelf并做两件额外的事将form.modified复位为false让表单重新回到未修改状态派发ON_FORM_RESET/ON_FIELD_RESET生命周期事件供 effects 或字段联动reactions监听。4. 单字段复位resetSelf每个字段的复位逻辑集中在resetSelfpackages/core/src/shared/internals.ts#L988-L1015它依次完成计算typedDefaultValue按字段类型处理后的默认值复位状态标记modified、selfModified、visited全部置false清空feedbacks、inputValues、caches将inputValue回填为typedDefaultValue若字段当前已有value则根据forceClear分支处理forceClear为truevalue typedDefaultValue强制清空否则优先取initialValue未定义时退回typedDefaultValue这就是有默认值的控件无法被清空的实现根源若options.validate为true最后对字段执行validateSelf完成重置后的自动校验校验结果通过ON_FIELD_VALIDATE_SUCCESS/ON_FIELD_VALIDATE_FAILED反馈给上层 Promise。另外Field实例自身也暴露了reset(options)方法packages/core/src/models/Field.ts#L513-L515底层同样走batchReset只是 pattern 自动限定为该字段子树${this.address}.**适用于在自定义组件内部对单个字段做精细化重置。在纯 JSX 表单中的使用Reset不依赖 Schema 渲染同样适用于非 JSON Schema 的普通 JSX 表单使用createFormFormProviderField组合。只要Reset渲染在FormProvider内它就能通过useParentForm拿到表单并完成重置例如import React from react import { createForm } from formily/core import { FormProvider, Field } from formily/react import { Input, FormItem, FormButtonGroup, Reset } from formily/antd const form createForm() export default () ( FormProvider form{form} Field namekeyword decorator{[FormItem]} component{[Input]} required / FormButtonGroup Reset validate onClick{(e) { // 返回 false 可阻塞重置例如做二次确认 if (!window.confirm(确认重置搜索条件)) return false }} 重置 /Reset /FormButtonGroup /FormProvider )小结与最佳实践明确重置语义Formily 的重置是回到默认值/初始值forceClear才表示强制清空。表单字段声明了default时普通重置不会将其清空这在需求评审时就应向产品确认预期行为。按需开启 validatevalidate会引入重置后的异步校验与反馈仅在需要即时校验反馈时使用需要处理校验失败场景时配合onResetValidateFailed接收IFormFeedback[]。善用 onClick 阻塞利用onClick返回false的拦截能力可优雅实现二次确认、条件阻止重置等交互无需额外状态。路径化重置若只需重置局部字段可在form.reset(某字段路径)层面精细控制避免整表单重置带来的不必要状态抖动。Reset组件相关的完整实现与示例可继续查阅 packages/antd/src/reset/index.tsx组件源码、packages/core/src/shared/internals.tsbatchReset/resetSelf核心实现以及 packages/antd/docs/components/Reset.zh-CN.md原始文档结合源码阅读可获得对重置链路最完整的理解。赞分享前端UI组件【免费下载链接】formily Cross Device High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址https://gitcode.com/gh_mirrors/fo/formily点击查看免费下载相关推荐formily/element 重置按钮 Reset 组件实战指南普通重置、强制清空与重置校验formily/element 重置按钮 Reset 组件实战指南普通重置、强制清空与重置校验 本文以 Formily 表单体系中的 Element 版组件前端UI组件Formily Reset 重置按钮完全指南普通重置、强制清空、重置校验与底层实现解析Formily Reset 重置按钮完全指南普通重置、强制清空、重置校验与底层实现解析 导读 Reset 是 Formily 表单体系中用于一键恢复字段初始状前端UI组件Formily Next Reset 按钮组件完整指南重置、强制清空与校验联动实战Formily Next Reset 按钮组件完整指南重置、强制清空与校验联动实战 本指南以 formily/next 中 Reset 组件为核心系统讲解前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考