Ant Design 紧凑模式完整指南：3 步搞定高密度布局

Ant Design 紧凑模式完整指南：3 步搞定高密度布局

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design

Ant Design 紧凑模式分两级：Space.Compact把相邻控件拼成一个无间隙的组件组，theme.compactAlgorithm则从主题层把控件高度、字号和间距整体收小。用对这两层，一屏多放两三行数据、表单少滚一次屏，都是可以直接量出来的收益。

先看效果：按钮从 40px 降到 36px，控件整体收窄

紧凑不是把样式压糊，而是三件事同时发生：控件高度降低、字号降一档、间距 token 整体收缩。以默认主题（基础字号 14px、间距基数 sizeStep=4）为例：

表中数字基于默认主题推算，实际值以你项目里theme.getToken()的返回值为准。

紧凑算法的实现只有 20 来行，核心逻辑在 components/theme/themes/compact/index.ts：字号降到fontSizeSM、controlHeight减 4、再用genCompactSizeMapToken把所有尺寸 token 收一档。理解了这一点，你就能解释界面上任何一处紧凑表现。

三步进阶用法

第一步 · Space.Compact 局部紧凑写法

适用场景：搜索栏、工具条这类"输入框 + 按钮"横向拼接的组合。

import { Button, Input, Select, Space } from 'antd'; export default function SearchBar() { return ( <Space.Compact style={{ width: '100%' }}> <Input placeholder="输入订单号" style={{ width: '40%' }} /> <Select placeholder="状态" options={[{ value: 'all', label: '全部' }]} /> <Button type="primary">查询</Button> </Space.Compact> ); }

组件会依次给子项挂上-compact-item、-compact-first-item、-compact-last-item三个类，中间元素的左右边框只保留一条，首尾保留圆角。实现见 components/space/Compact.tsx 里的useCompactItemContext。

第二步 · 表单紧凑：Form.Item 内嵌 Space.Compact

适用场景：字段多的录入表单，一屏想塞下更多行。

说明一点：当前版本的Form没有独立的compact属性。表单紧凑是"缩小行距 + 控件组内嵌Space.Compact"的组合：

import { Form, Input, Row, Col, Space, Button } from 'antd'; export default function LoginForm() { return ( <Form layout="vertical" style={{ rowGap: 12 }}> <Row gutter={12}> <Col span={12}> <Form.Item name="account" label="账号"> <Input /> </Form.Item> </Col> <Col span={12}> <Form.Item name="password" label="密码"> <Input.Password /> </Form.Item> </Col> </Row> <Form.Item> <Space.Compact style={{ width: '100%' }}> <Input placeholder="邀请码（选填）" /> <Button type="primary">注册</Button> </Space.Compact> </Form.Item> </Form> ); }

行距由rowGap控制（12 到 16 是常用区间），控件组用Space.Compact收边。两层一起用，表单密度可以明显提升。

第三步 · 全局紧凑：ConfigProvider 配置紧凑算法

适用场景：整个后台系统都需要高密度风格，不想逐个页面调整。

import { ConfigProvider, theme } from 'antd'; export default function App() { return ( <ConfigProvider theme={{ algorithm: [theme.darkAlgorithm, theme.compactAlgorithm] }} > <YourApp /> </ConfigProvider> ); }

algorithm接收算法数组，按顺序叠加执行——先 dark 再 compact，得到暗色紧凑主题。注意是算法数组，不是compact: true这种开关属性。

自定义紧凑算法：改 token 不改组件

紧凑算法的配置边界是 Map Token：它能调高度、字号、间距，但不会动组件结构。想再激进一点，把紧凑算法当作推导函数参考，自己算一份 token 差量：

// themes/my-compact.ts import defaultAlgorithm from 'antd/es/theme/themes/default'; export default function myCompact(token, mapToken) { const merged = mapToken ?? defaultAlgorithm(token); return { ...merged, ...merged.genSizeMapToken({ ...token, sizeStep: token.sizeStep - 4 }), controlHeight: merged.controlHeight - 8, }; } // 使用：<ConfigProvider theme={{ algorithm: myCompact }}>

默认实现里sizeStep只减 2、controlHeight减 4；减到 8 时控件会压到 32px 以下，属于比较激进的配置，上线前建议走一轮走查。

避坑清单

1. 嵌套 Space.Compact 后首尾样式错位原因：外层Compact会把"嵌套组件本身"标记为 last-item，内层再按自己的子项独立标记，两套标记叠在一起容易出现重复边框或丢圆角。 解法：优先平铺；确实要嵌套时，内层Space.Compact自己会接管首尾判断（见 components/space/Compact.tsx 第 140-143 行），先确认子项 key 稳定，再看渲染出来的类名是否符合预期。

2. 全局紧凑下想恢复某一段默认尺寸原因：算法是主题级覆盖，单靠 className 盖不回去。 解法：局部断开上下文，用NoCompactStyle（同文件内导出，把SpaceCompactItemContext置空）包住该区域，配合size属性手动指定尺寸。

3. 自定义组件在紧凑组里边框、圆角不对原因：只有内置组件默认消费了紧凑上下文，你的组件不读它就不会自适应。 解法：调用useCompactItemContext(prefixCls, direction)，把返回的compactItemClassnames挂到根节点，用compactSize决定内部尺寸。

4. 紧凑后点击热区变小，移动端误触增多原因：紧凑算法把控件高度直接减 4px，触控面积随之缩小。 解法：触屏为主的产品慎用全局紧凑，或给关键按钮单独设size="middle"恢复 40px 高度。

5. 紧凑模式下列表文字显得更挤原因：基础字号从 14px 降到 12px，是算法的既定行为（改用fontSizeSM作为基准）。 解法：对信息密度高的正文区域单独覆盖fontSize，不要全局再压字号。

怎么选型：场景对照表

写在最后

紧凑模式的决策其实就两条：局部需求用Space.Compact，全局需求用紧凑算法；两者可以叠加，但先全局再局部地排查问题会快很多。上线前重点检查三样：首尾元素的边框类名、自定义组件是否接入了上下文、关键按钮的点击热区是否还在可接受范围。

• 官方主题文档（紧凑算法章节）：docs/react/customize-theme.zh-CN.md
• 版本演进记录：CHANGELOG.zh-CN.md

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design