Ant Design Form 高级搜索表单实战三列栅格布局 展开收起完整实现【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读在数据表格类管理页面中高级搜索Advanced Search是最常见的交互形态表单以三列栅格平铺多组查询条件配合展开/收起按钮在简洁与完整之间切换。本篇文章以 Ant Design 官方 Form 组件的 advanced-search 示例 为核心逐步拆解其布局原理、表单实例用法、主题 Token 样式定制并深入仓库源码讲解Row/Col栅格、Form.Item布局合并等底层机制帮助你直接复用这套方案到自己的项目中。一、示例整体结构一行代码看清三件事先看官方 demo 的说明advanced-search.md三列栅格式的表单排列方式常用于数据表格的高级搜索。有部分定制的样式代码由于输入标签长度不确定需要根据具体情况自行调整。这段描述点出了该示例的三个核心设计点也是本文将要展开的三条主线三列栅格通过RowCol span{8}实现一行三个查询项面向数据表格表单与下方Search Result List结果列表配合构成搜索页的完整闭环自定义样式因为表单项标签宽度不固定示例中的背景、圆角、间距等样式需要按实际情况微调。完整示例代码位于 components/form/demo/advanced-search.tsx官方文档页通过 index.zh-CN.md 中的code src./demo/advanced-search.tsx高级搜索/code引用展示。二、三列栅格布局Row Col 的尺寸控制2.1 布局核心代码示例的表单主体是一段循环生成的字段每个字段用一个Col span{8}包裹Form form{form} nameadvanced_search style{formStyle} onFinish{onFinish} Row gutter{24}{getFields()}/Row div style{{ textAlign: right }} {/* 按钮区 */} /div /FormgetFields()内部每次循环生成Col span{8} key{i} Form.Item name{field-${i}} label{Field ${i}} rules{[...]} Input placeholderplaceholder / /Form.Item /Col2.2 span 与栅格换算原理Ant Design 的栅格系统基于 24 等分span{8}表示每列占 8/24 1/3 宽度三个Col恰好排满一行从而实现三列栅格式布局。栅格组件源码位于 components/grid/col.tsx对外导出见 components/grid/index.tsx。需要调整列数时只需按 24 的约数修改span每行列数span 取值说明1 列24整行一个字段2 列12常用编辑表单3 列8高级搜索最常见4 列6紧凑型搜索2.3 gutter控制列间距Row gutter{24}为每一列之间提供 24px 的水平间距。查看 components/grid/row.tsx 源码可知gutter的类型为Gutter | [Gutter, Gutter]第 34 行传单个数字时内部会归一化为[gutter, undefined]第 136 行即只产生水平间距传数组[16, 24]时可同时指定水平与垂直间距rowGap会被设置为垂直间距值第 182-184 行。在搜索表单这类多行字段场景下建议使用gutter{[16, 24]}同时控制行间距避免字段行与行之间贴得太紧。三、展开/收起用一行 state 控制字段数量3.1 实现思路示例通过useState维护expand状态动态决定渲染 6 个还是 10 个字段const [expand, setExpand] useState(false); const getFields () { const count expand ? 10 : 6; // ...循环生成 count 个 Col span{8} };默认收起时显示 6 个字段两行三列展开后显示 10 个字段。这是高级搜索表单收起简洁、展开完整的标准做法比用display: none隐藏更干净——它直接控制渲染数量未挂载的字段不会参与表单值收集。3.2 展开按钮的细节处理a style{{ fontSize: 12 }} onClick{() { setExpand(!expand); }} DownOutlined rotate{expand ? 180 : 0} / Collapse /a这里有两个值得学习的细节使用a标签 onClick实现文字链接式按钮视觉上弱化操作入口符合搜索区操作不抢眼的设计惯例DownOutlined图标通过rotate属性在展开/收起时旋转 180°图标来自ant-design/icons包与 Ant Design 视觉语言保持一致。3.3 按钮区的排版div style{{ textAlign: right }} Space sizesmall Button typeprimary htmlTypesubmitSearch/Button Button onClick{() form.resetFields()}Clear/Button {/* 展开/收起链接 */} /Space /div按钮统一靠右对齐使用Space sizesmall控制按钮间距。htmlTypesubmit让 Search 按钮直接触发表单的onFinishClear 按钮调用form.resetFields()一键恢复所有字段的初始值。四、表单实例与校验useForm 的正确姿势4.1 创建表单实例const [form] Form.useForm(); Form form{form} nameadvanced_search onFinish{onFinish} /Form.useForm()返回表单实例form通过form属性注入Form。此后便可以在任意事件处理中命令式操作表单例如示例中的form.resetFields()。onFinish是表单提交成功的回调所有通过校验的字段值会作为一个对象传入const onFinish (values: any) { console.log(Received values of form: , values); };实际项目中这里通常把values作为查询参数请求后端接口再刷新下方的结果列表——这正是高级搜索与数据表格的衔接点。FormProps的完整定义见 components/form/Form.tsx。4.2 字段校验规则示例为每个字段配置了必填校验Form.Item name{field-${i}} label{Field ${i}} rules{[{ required: true, message: Input something! }]} Input placeholderplaceholder / /Form.Item搜索场景下如果允许空条件查全部通常不需要required校验示例加上它主要用于演示rules的用法。对于下拉框示例还展示了initialValue的用法Form.Item name{field-${i}} label{Field ${i}} rules{[{ required: true, message: Select something! }]} initialValue1 Select Option value1longlonglong.../Option Option value2222/Option /Select /Form.IteminitialValue1让 Select 在首次渲染时就选中value1的选项。4.3 示例中刻意埋下的陷阱超长标签细心的读者会发现Select 的第一个 Option 文本被刻意写成了超长字符串Option value1 longlonglonglonglonglonglonglong...longlong /Option这正是原文档所提示的由于输入标签长度不确定需要根据具体情况自行调整。当选项文本过长时Select 的宽度可能超出栅格列宽导致布局溢出或错位。官方用这个极端例子提醒使用者高级搜索表单中字段标签宽度并不固定上线前务必根据真实业务数据的文本长度调整样式。五、定制样式基于主题 Token 而非硬编码颜色5.1 背景、圆角与间距示例没有写任何 CSS 文件而是通过theme.useToken()拿到设计 Token 后以内联样式设置外观const { token } theme.useToken(); const formStyle: React.CSSProperties { maxWidth: none, background: token.colorFillAlter, borderRadius: token.borderRadiusLG, padding: 24, };token.colorFillAlter浅灰色填充色常用于表格斑马纹、搜索区背景等次级容器token.borderRadiusLG大圆角与卡片、抽屉等组件的圆角保持一致maxWidth: none覆盖 Form 默认的最大宽度限制让搜索区横向铺满容器padding: 24内边距与栅格gutter{24}呼应形成统一的 24px 视觉间距体系。下方结果列表占位区也采用了同样的 Token 组合const listStyle: React.CSSProperties { lineHeight: 200px, textAlign: center, background: token.colorFillAlter, borderRadius: token.borderRadiusLG, marginTop: 16, };优势使用 Token 而非硬编码色值意味着当项目通过ConfigProvider切换主题如暗色模式时搜索区会自动跟随主题变化无需额外适配。5.2 标签宽度与对齐的源码级处理关于标签长度不确定从源码看 Ant Design 也提供了系统性应对方案。在 components/form/FormItemLabel.tsx 中标签列的样式由labelCol、labelAlign、labelWrap共同决定const mergedLabelCol: ColProps labelCol || contextLabelCol || {}; const mergedLabelAlign labelAlign || contextLabelAlign; const labelColClassName classNames( labelClsBasic, mergedLabelAlign left ${labelClsBasic}-left, mergedLabelCol.className, { [${labelClsBasic}-wrap]: !!labelWrap }, );labelCol/wrapperCol通过 ColProps 控制标签列与输入控件列的栅格宽度配比如labelCol{{ span: 6 }} wrapperCol{{ span: 18 }}同时支持在Form与Form.Item两级配置Form.Item的配置优先合并mergedLabelCol逻辑labelAlignleft让标签左对齐而非默认右对齐标签长度参差时观感更稳定labelWrap标签过长时允许换行避免文本截断。这些属性同样定义在 components/form/Form.tsx 的FormProps中并经由 components/form/context.tsx 向下传递。当你的搜索字段标签长短不一时组合使用labelCol固定标签列宽度 labelAlignleft往往比逐个微调样式更省心。六、测试保障demo 同样被自动化覆盖该示例并不是孤立的展示代码它同样纳入了仓库的自动化测试体系。在 components/form/tests/snapshots/demo.test.tsx.snap 中存在renders components/form/demo/advanced-search.tsx correctly的快照components/form/tests/snapshots/demo-extend.test.ts.snap 中也有renders components/form/demo/advanced-search.tsx extend context correctly的快照用例。这说明官方对每个 demo 都做了两层验证基础渲染快照确保示例在不同依赖版本下渲染结果稳定扩展上下文extend context验证示例在 ConfigProvider 等扩展上下文中依然正确渲染。你在复用本示例时同样建议为自己的搜索表单补充展开/收起切换校验失败提示重置后字段值清空等关键交互的测试用例防止后续改动破坏行为。七、快速落地清单与 ProForm 延伸7.1 复用本示例的步骤引入依赖antd含Form、Row、Col、Input、Select、Button、Space、theme与ant-design/iconsDownOutlined复制 advanced-search.tsx 的组件骨架将getFields()中的循环字段替换为真实查询条件关键词、状态、日期范围等并删掉演示用的required校验除非业务确实需要在onFinish中调用数据请求接口并把返回结果渲染到下方的结果列表区域按业务标签的实际长度通过labelCol/labelWrap/ 自定义样式调整布局。7.2 面向复杂场景的 ProForm 查询表单原文档还提示若想3 分钟实现查询表单可考虑 ProForm 的查询表单QueryFilter。ProForm 是 Ant Design 生态中基于 Form 封装的进阶方案内置了查询表单的展开/收起、栅格分列等能力适合查询条件复杂、需要快速交付的中后台项目。普通项目直接基于本示例的Row Col useForm方案即可满足大部分高级搜索需求。八、小结本篇文章围绕 Ant Design 官方的 advanced-search 示例梳理出一条完整可落地的实现路径布局Row gutterCol span{8}实现三列栅格按 24 等分规则自由调整列数交互useState控制字段渲染数量配合DownOutlined旋转实现展开/收起表单Form.useForm()实例 rules校验 onFinish提交 resetFields重置样式theme.useToken()读取设计 Token让搜索区随主题自适应并用labelCol/labelAlign应对标签长度不固定的问题质量参考仓库快照测试思路为自己的搜索表单补充关键交互测试。以此为基础你可以把任何一个数据表格页面的搜索区升级为标准的三列高级搜索表单。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ant Design Form 高级搜索表单实战：三列栅格布局 + 展开收起完整实现
Ant Design Form 高级搜索表单实战三列栅格布局 展开收起完整实现【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读在数据表格类管理页面中高级搜索Advanced Search是最常见的交互形态表单以三列栅格平铺多组查询条件配合展开/收起按钮在简洁与完整之间切换。本篇文章以 Ant Design 官方 Form 组件的 advanced-search 示例 为核心逐步拆解其布局原理、表单实例用法、主题 Token 样式定制并深入仓库源码讲解Row/Col栅格、Form.Item布局合并等底层机制帮助你直接复用这套方案到自己的项目中。一、示例整体结构一行代码看清三件事先看官方 demo 的说明advanced-search.md三列栅格式的表单排列方式常用于数据表格的高级搜索。有部分定制的样式代码由于输入标签长度不确定需要根据具体情况自行调整。这段描述点出了该示例的三个核心设计点也是本文将要展开的三条主线三列栅格通过RowCol span{8}实现一行三个查询项面向数据表格表单与下方Search Result List结果列表配合构成搜索页的完整闭环自定义样式因为表单项标签宽度不固定示例中的背景、圆角、间距等样式需要按实际情况微调。完整示例代码位于 components/form/demo/advanced-search.tsx官方文档页通过 index.zh-CN.md 中的code src./demo/advanced-search.tsx高级搜索/code引用展示。二、三列栅格布局Row Col 的尺寸控制2.1 布局核心代码示例的表单主体是一段循环生成的字段每个字段用一个Col span{8}包裹Form form{form} nameadvanced_search style{formStyle} onFinish{onFinish} Row gutter{24}{getFields()}/Row div style{{ textAlign: right }} {/* 按钮区 */} /div /FormgetFields()内部每次循环生成Col span{8} key{i} Form.Item name{field-${i}} label{Field ${i}} rules{[...]} Input placeholderplaceholder / /Form.Item /Col2.2 span 与栅格换算原理Ant Design 的栅格系统基于 24 等分span{8}表示每列占 8/24 1/3 宽度三个Col恰好排满一行从而实现三列栅格式布局。栅格组件源码位于 components/grid/col.tsx对外导出见 components/grid/index.tsx。需要调整列数时只需按 24 的约数修改span每行列数span 取值说明1 列24整行一个字段2 列12常用编辑表单3 列8高级搜索最常见4 列6紧凑型搜索2.3 gutter控制列间距Row gutter{24}为每一列之间提供 24px 的水平间距。查看 components/grid/row.tsx 源码可知gutter的类型为Gutter | [Gutter, Gutter]第 34 行传单个数字时内部会归一化为[gutter, undefined]第 136 行即只产生水平间距传数组[16, 24]时可同时指定水平与垂直间距rowGap会被设置为垂直间距值第 182-184 行。在搜索表单这类多行字段场景下建议使用gutter{[16, 24]}同时控制行间距避免字段行与行之间贴得太紧。三、展开/收起用一行 state 控制字段数量3.1 实现思路示例通过useState维护expand状态动态决定渲染 6 个还是 10 个字段const [expand, setExpand] useState(false); const getFields () { const count expand ? 10 : 6; // ...循环生成 count 个 Col span{8} };默认收起时显示 6 个字段两行三列展开后显示 10 个字段。这是高级搜索表单收起简洁、展开完整的标准做法比用display: none隐藏更干净——它直接控制渲染数量未挂载的字段不会参与表单值收集。3.2 展开按钮的细节处理a style{{ fontSize: 12 }} onClick{() { setExpand(!expand); }} DownOutlined rotate{expand ? 180 : 0} / Collapse /a这里有两个值得学习的细节使用a标签 onClick实现文字链接式按钮视觉上弱化操作入口符合搜索区操作不抢眼的设计惯例DownOutlined图标通过rotate属性在展开/收起时旋转 180°图标来自ant-design/icons包与 Ant Design 视觉语言保持一致。3.3 按钮区的排版div style{{ textAlign: right }} Space sizesmall Button typeprimary htmlTypesubmitSearch/Button Button onClick{() form.resetFields()}Clear/Button {/* 展开/收起链接 */} /Space /div按钮统一靠右对齐使用Space sizesmall控制按钮间距。htmlTypesubmit让 Search 按钮直接触发表单的onFinishClear 按钮调用form.resetFields()一键恢复所有字段的初始值。四、表单实例与校验useForm 的正确姿势4.1 创建表单实例const [form] Form.useForm(); Form form{form} nameadvanced_search onFinish{onFinish} /Form.useForm()返回表单实例form通过form属性注入Form。此后便可以在任意事件处理中命令式操作表单例如示例中的form.resetFields()。onFinish是表单提交成功的回调所有通过校验的字段值会作为一个对象传入const onFinish (values: any) { console.log(Received values of form: , values); };实际项目中这里通常把values作为查询参数请求后端接口再刷新下方的结果列表——这正是高级搜索与数据表格的衔接点。FormProps的完整定义见 components/form/Form.tsx。4.2 字段校验规则示例为每个字段配置了必填校验Form.Item name{field-${i}} label{Field ${i}} rules{[{ required: true, message: Input something! }]} Input placeholderplaceholder / /Form.Item搜索场景下如果允许空条件查全部通常不需要required校验示例加上它主要用于演示rules的用法。对于下拉框示例还展示了initialValue的用法Form.Item name{field-${i}} label{Field ${i}} rules{[{ required: true, message: Select something! }]} initialValue1 Select Option value1longlonglong.../Option Option value2222/Option /Select /Form.IteminitialValue1让 Select 在首次渲染时就选中value1的选项。4.3 示例中刻意埋下的陷阱超长标签细心的读者会发现Select 的第一个 Option 文本被刻意写成了超长字符串Option value1 longlonglonglonglonglonglonglong...longlong /Option这正是原文档所提示的由于输入标签长度不确定需要根据具体情况自行调整。当选项文本过长时Select 的宽度可能超出栅格列宽导致布局溢出或错位。官方用这个极端例子提醒使用者高级搜索表单中字段标签宽度并不固定上线前务必根据真实业务数据的文本长度调整样式。五、定制样式基于主题 Token 而非硬编码颜色5.1 背景、圆角与间距示例没有写任何 CSS 文件而是通过theme.useToken()拿到设计 Token 后以内联样式设置外观const { token } theme.useToken(); const formStyle: React.CSSProperties { maxWidth: none, background: token.colorFillAlter, borderRadius: token.borderRadiusLG, padding: 24, };token.colorFillAlter浅灰色填充色常用于表格斑马纹、搜索区背景等次级容器token.borderRadiusLG大圆角与卡片、抽屉等组件的圆角保持一致maxWidth: none覆盖 Form 默认的最大宽度限制让搜索区横向铺满容器padding: 24内边距与栅格gutter{24}呼应形成统一的 24px 视觉间距体系。下方结果列表占位区也采用了同样的 Token 组合const listStyle: React.CSSProperties { lineHeight: 200px, textAlign: center, background: token.colorFillAlter, borderRadius: token.borderRadiusLG, marginTop: 16, };优势使用 Token 而非硬编码色值意味着当项目通过ConfigProvider切换主题如暗色模式时搜索区会自动跟随主题变化无需额外适配。5.2 标签宽度与对齐的源码级处理关于标签长度不确定从源码看 Ant Design 也提供了系统性应对方案。在 components/form/FormItemLabel.tsx 中标签列的样式由labelCol、labelAlign、labelWrap共同决定const mergedLabelCol: ColProps labelCol || contextLabelCol || {}; const mergedLabelAlign labelAlign || contextLabelAlign; const labelColClassName classNames( labelClsBasic, mergedLabelAlign left ${labelClsBasic}-left, mergedLabelCol.className, { [${labelClsBasic}-wrap]: !!labelWrap }, );labelCol/wrapperCol通过 ColProps 控制标签列与输入控件列的栅格宽度配比如labelCol{{ span: 6 }} wrapperCol{{ span: 18 }}同时支持在Form与Form.Item两级配置Form.Item的配置优先合并mergedLabelCol逻辑labelAlignleft让标签左对齐而非默认右对齐标签长度参差时观感更稳定labelWrap标签过长时允许换行避免文本截断。这些属性同样定义在 components/form/Form.tsx 的FormProps中并经由 components/form/context.tsx 向下传递。当你的搜索字段标签长短不一时组合使用labelCol固定标签列宽度 labelAlignleft往往比逐个微调样式更省心。六、测试保障demo 同样被自动化覆盖该示例并不是孤立的展示代码它同样纳入了仓库的自动化测试体系。在 components/form/tests/snapshots/demo.test.tsx.snap 中存在renders components/form/demo/advanced-search.tsx correctly的快照components/form/tests/snapshots/demo-extend.test.ts.snap 中也有renders components/form/demo/advanced-search.tsx extend context correctly的快照用例。这说明官方对每个 demo 都做了两层验证基础渲染快照确保示例在不同依赖版本下渲染结果稳定扩展上下文extend context验证示例在 ConfigProvider 等扩展上下文中依然正确渲染。你在复用本示例时同样建议为自己的搜索表单补充展开/收起切换校验失败提示重置后字段值清空等关键交互的测试用例防止后续改动破坏行为。七、快速落地清单与 ProForm 延伸7.1 复用本示例的步骤引入依赖antd含Form、Row、Col、Input、Select、Button、Space、theme与ant-design/iconsDownOutlined复制 advanced-search.tsx 的组件骨架将getFields()中的循环字段替换为真实查询条件关键词、状态、日期范围等并删掉演示用的required校验除非业务确实需要在onFinish中调用数据请求接口并把返回结果渲染到下方的结果列表区域按业务标签的实际长度通过labelCol/labelWrap/ 自定义样式调整布局。7.2 面向复杂场景的 ProForm 查询表单原文档还提示若想3 分钟实现查询表单可考虑 ProForm 的查询表单QueryFilter。ProForm 是 Ant Design 生态中基于 Form 封装的进阶方案内置了查询表单的展开/收起、栅格分列等能力适合查询条件复杂、需要快速交付的中后台项目。普通项目直接基于本示例的Row Col useForm方案即可满足大部分高级搜索需求。八、小结本篇文章围绕 Ant Design 官方的 advanced-search 示例梳理出一条完整可落地的实现路径布局Row gutterCol span{8}实现三列栅格按 24 等分规则自由调整列数交互useState控制字段渲染数量配合DownOutlined旋转实现展开/收起表单Form.useForm()实例 rules校验 onFinish提交 resetFields重置样式theme.useToken()读取设计 Token让搜索区随主题自适应并用labelCol/labelAlign应对标签长度不固定的问题质量参考仓库快照测试思路为自己的搜索表单补充关键交互测试。以此为基础你可以把任何一个数据表格页面的搜索区升级为标准的三列高级搜索表单。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考