rsuite Grid 栅格 Gutter 实战：Row 水平/垂直间距与响应式配置完全指南-平芜编程栈

前端
UI组件

【免费下载链接】rsuite

🧱 A suite of React components .

项目地址：https://gitcode.com/gh_mirrors/rs/rsuite

本篇技术指南聚焦 rsuite 栅格系统（Grid / Row / Col）中的Gutter（栅格间隔）功能，讲解如何通过Row组件的gutter属性同时控制水平与垂直方向的列间距、如何使用响应式对象在不同屏幕断点下精细化调整间距，并结合仓库源码剖析其底层 CSS 变量实现机制。读完你将掌握gutter的三种取值形态（单值、[水平, 垂直]数组、ResponsiveValue对象）、与Slider等控件联动的交互写法，以及 gutter 与align、justify、响应式span等属性的组合使用技巧。

栅格间隔：让 24 列布局呼吸起来

rsuite 的 Grid 组件基于 24 列栅格体系，灵感源自 Bootstrap 的栅格系统，提供Grid（容器）、Row（行）、Col（列）三层结构（详见栅格文档）。当页面中并排多个列时，如果列与列之间没有任何间隔，内容会挤作一团，视觉可读性大打折扣。

rsuite 提供了gutter属性来解决这个问题。按照官方文档的描述：通过在Row上设置gutter属性来调整栅格间距，gutter属性可以设置水平和垂直方向的间距，并支持响应式值（对应文档的"栅格间隔"小节）。这意味着：

不需要在每一列上单独加padding或margin，只需在父级Row上声明一次；
一个属性同时覆盖两个方向：水平方向决定列与列之间的左右空隙，垂直方向决定行与行之间的上下空隙；
可以按屏幕断点（xs ~ xxl）分别定制间距，让移动端紧凑、桌面端宽松。

理解 GutterType：gutter 的三种合法取值

在Row 的类型定义中，gutter属性的类型为：

export type GutterType = number | string | [number | string, number | string];

结合 Row 组件的 Props 声明，gutter的完整类型是GutterType | ResponsiveValue<GutterType>。其中ResponsiveValue<T>定义在 src/internals/types/sizes.ts：

export type Breakpoints = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | '2xl'; export type ResponsiveValue<T> = { [key in Breakpoints]?: T };

因此gutter共有三种基础写法：

写法	示例	含义
单个数字	`gutter={16}`	水平和垂直方向均使用 16px 间距
单个字符串	`gutter={'1rem'}`	水平和垂直方向均使用 1rem 间距（支持任意 CSS 长度单位）
二元数组	`gutter={[16, 24]}`	水平间距 16px，垂直间距 24px；元素可混合使用数字与字符串，如`[16, '2rem']`
响应式对象	`gutter={{ xs: 8, md: 16, lg: 32 }}`	按断点分别指定间距，每个值可以是上述任意一种（含数组）

数组的第一项始终作用于水平方向（列间距），第二项作用于垂直方向（行间距）；数组与单值混用时，第二个元素可以省略单位或混用单位。

交互式示例：用 Slider 实时调节 Gutter

gutter 演示片段是栅格文档中"栅格间隔"一节的完整示例：它用两个Slider分别控制水平（Column Gutter）与垂直（Row Gutter）间距，再以数组形式传给Row，直观展示两类间距的变化效果。完整代码与官方演示一致：

import { Grid, Row, Col, VStack, HStack, Slider, Center, Text } from 'rsuite'; const DecorativeBox = ({ children, ...rest }) => ( <Center bg="var(--rs-placeholder)" p={20} rounded="lg" {...rest}> {children} </Center> ); const App = () => { const [columnGutter, setColumnGutter] = React.useState(16); const [rowGutter, setRowGutter] = React.useState(16); return ( <> <VStack spacing={20}> <HStack spacing={20} w="100%"> <Text muted w={120}>Column Gutter</Text> <Slider value={columnGutter} w="100%" onChange={setColumnGutter} /> </HStack> <HStack spacing={20} w="100%"> <Text muted w={120}>Row Gutter</Text> <Slider value={rowGutter} w="100%" onChange={setRowGutter} /> </HStack> </VStack> <hr /> <Grid fluid> <Row gutter={[columnGutter, rowGutter]}> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> <Col span={4}> <DecorativeBox>4</DecorativeBox> </Col> </Row> </Grid> </> ); }; ReactDOM.render(<App />, document.getElementById('root'));

这段代码有四个值得注意的实战要点：

gutter={[columnGutter, rowGutter]}是状态驱动的：拖动任一Slider触发setColumnGutter/setRowGutter，Row立即以新的数组值重渲染，间距随之实时变化——这正是"属性一次声明、状态驱动重算"的典型用法，无需操作 DOM 或重挂载组件。
12 个span={4}列恰好铺满一行：24 列栅格体系下4 × 12 = 24，当span与offset之和超过默认columns（24）时，列才会自动换行（参见多行示例），本例不换行，因此垂直 gutter 的实际效果需要在多行场景（如缩小窗口宽度触发换行）中才能看到。
Grid fluid表示 100% 宽度容器：Grid的fluid属性提供流体布局，不设固定容器宽度，适合演示间距对内容布局的影响（Grid Props 说明）。
装饰盒用Center组件：DecorativeBox借助 rsuite 的Center与bg/p/rounded快捷样式属性渲染占位块，视觉上凸显列之间的间隔区域。

源码原理：gutter 如何变成 CSS 变量

gutter之所以能同时驱动水平、垂直两个方向的间距，核心在于 rsuite 将其编译为一组 CSS 自定义属性（CSS 变量），再由 SCSS 消费这些变量计算实际间距。整个链路分三步。

第一步：Row 将 gutter 转为 CSS 变量

Row 的实现通过getResponsiveGutterStyles(gutter)计算行内样式并合并进style。该函数位于 src/Grid/utils/styles.ts，逻辑如下：

传入undefined时不产生任何样式；
数组[h, v]被拆分为水平值h与垂直值v；单值value则被复制为[value, value]，即两个方向相同；
生成两个 CSS 变量：水平间距写入--rs-grid-gutter，垂直间距写入--rs-grid-row-gutter；
若传入的是响应式对象，则遍历BREAKPOINTS（['xs', 'sm', 'md', 'lg', 'xl', 'xxl']，定义于 src/internals/constants/index.ts），为每个断点生成带后缀的变量，如--rs-grid-gutter-md、--rs-grid-row-gutter-lg；xs作为基础值不加后缀；
所有值统一经过getCssValue处理（位于src/internals/utils），将纯数字补上px单位，字符串原样保留。

第二步：SCSS 消费变量计算列内边距与行外边距

栅格间距的经典实现是"负外边距 + 内边距"组合：列内边距制造列间空隙，行的负外边距抵消首尾列的额外边距，保证整行与容器对齐。栅格 mixin 中：

.rs-col { --rs-col-gutter: calc(var(--rs-grid-gutter-#{$size}, var(--rs-grid-gutter)) / 2); } .rs-row { --rs-row-gutter: calc(var(--rs-grid-gutter-#{$size}, var(--rs-grid-gutter)) / -2); --rs-row-gap: var(--rs-grid-row-gutter-#{$size}, var(--rs-grid-row-gutter)); }

其中var(--rs-grid-gutter-#{$size}, var(--rs-grid-gutter))是带回退值的变量引用语法：若当前断点设置了专门的 gutter 变量则使用之，否则回退到xs基础值。

第三步：实际应用于行列盒模型

行样式 _row.scss：.rs-row声明display: flex; flex-flow: row wrap，并使用margin-inline: var(--rs-row-gutter)（负值抵消列内边距）和row-gap: var(--rs-row-gap)（CSSrow-gap直接驱动垂直方向行间距）；
列样式 _columns.scss：.rs-col使用padding-inline: var(--rs-col-gutter)（即水平 gutter 的一半）产生列间空隙。

默认情况下，栅格变量 _variables.scss 定义了--rs-grid-gutter: calc(var(--rs-spacing) * 3)，即默认间距与全局 spacing 令牌联动；一旦你在Row上设置了gutter，内联样式中的变量会覆盖默认值。

响应式 Gutter：为每个断点定制间距

gutter的响应式能力源于ResponsiveValue<GutterType>。下面是在 Row 测试用例中实际验证过的完整写法：

<Row gutter={{ xs: 8, sm: 16, md: 24, lg: 32, xl: 40, xxl: 48 }} > Row </Row>

测试断言（Row.spec.tsx）确认了以下行为：

xs: 8生成无后缀变量--rs-grid-gutter: 8px（基础值，对所有屏幕生效直至被覆盖）；
sm~xxl分别生成--rs-grid-gutter-sm、--rs-grid-gutter-md等带断点后缀的变量；
支持部分断点：例如只写{ xs: 8, md: 24 }时，sm、lg、xl、xxl的变量不会被设置（测试中这些属性值为空字符串），它们将自动回退到xs的 8px——这意味着你只需声明"变化点"，其余断点自然继承基础值；
每个断点的值同样支持数组形式：gutter={{ xs: [8, 16], sm: [16, 24] }}会同时生成对应的水平变量（--rs-grid-gutter-sm）与垂直变量（--rs-grid-row-gutter-sm），测试在 Row.spec.tsx#L115-L151 中逐一断言。

响应式的生效依赖 SCSS 中按断点生成的媒体查询。栅格样式 src/Grid/styles/index.scss 使用@media (min-width: ...)逐级套用make-gridmixin，因此md断点的变量只在min-width: md及以上生效，天然形成"从 xs 基础值向上覆盖"的移动优先策略。

固定值、字符串与混合单位

gutter不限于纯数字。测试 Row.spec.tsx#L16-L48 验证了三类写法：

// 单值：水平垂直相同 <Row gutter={10}> {/* --rs-grid-gutter: 10px; --rs-grid-row-gutter: 10px */} <Row gutter={'2rem'}> {/* 两个方向均为 2rem */} // 数组：方向分离 <Row gutter={[10, 20]}> {/* 水平 10px，垂直 20px */} <Row gutter={['1rem', '2rem']} /> <Row gutter={[10, '2rem']} /> {/* 混合：水平数字、垂直字符串 */}

字符串值允许使用任意 CSS 长度单位（rem、em、%、vw等），适合与设计令牌（design token）或全局--rs-spacing体系对齐；混合数组则让水平与垂直方向各自选择合适的单位。需要留意的是，数字值在getCssValue中会被补上px，因此在需要跟随根字号缩放的场景（如响应式字号布局）优先使用rem字符串。

Gutter 与 Row / Col 其他响应式属性的联动

gutter只是 Row 的三个核心属性之一，它常与以下属性组合使用，且都支持相同的ResponsiveValue对象语法：

align（'top' | 'middle' | 'bottom'）：行内列的垂直对齐方式；
justify（'start' | 'end' | 'center' | 'space-around' | 'space-between'）：列的水平分布方式；
Col上的响应式span/offset/push/pull/order/hidden：例如span={{ xs: 24, md: 8 }}让列在移动端占满整行、桌面端三等分。

上述属性在 Row 与 Col 的 Props 表格中均有详细说明。值得注意的是，rsuite 6.0 起废弃了旧的xs/sm/md/xsOffset/xsPush等扁平写法，统一收口为对象语法（DeprecatedColProps 类型中明确标注了迁移指引，例如xs对应改为span={{ xs: number }}）；而 Col 的实现仍会兼容解析新旧两种格式，以便平滑升级。

组合示例（响应式间距 + 响应式列宽 + 对齐）：

<Row gutter={{ xs: 8, md: [24, 16], lg: [32, 24] }} align="middle" justify="space-between" > <Col span={{ xs: 24, md: 8 }}>A</Col> <Col span={{ xs: 24, md: 8 }}>B</Col> <Col span={{ xs: 24, md: 8 }}>C</Col> </Row>

常见问题与最佳实践

为什么 gutter 要放在Row上而不是Col上？因为 gutter 属于"行级布局策略"，且数组/响应式语法需要统一入口；放在Col上只能单列声明，无法表达两列之间的共享间隔。
垂直 gutter 看不到效果？单行 24 列恰好排满时不存在换行，自然没有行间距；请结合多行场景（span + offset超出行宽自动换行）或嵌套栅格使用。
间距不对称导致首尾列偏移？这是正常的：行的负外边距与列的内边距互相抵消，保证首尾列与容器边缘对齐，这正是栅格系统的标准行为，不必手动修正。
与嵌套栅格配合：栅格支持无限嵌套（嵌套示例），每层可独立设置gutter，各层间距互不干扰。
性能与主题化：gutter以 CSS 变量实现，运行时修改gutter（如 Slider 联动）只更新内联样式中的变量，浏览器仅触发样式重算，无需重建 DOM，可放心用于高频交互场景。

小结

rsuite 的gutter属性用一个声明同时解决水平与垂直两个方向的栅格间距问题，并借助ResponsiveValue对象语法实现了移动优先的断点定制。其底层通过 getResponsiveGutterStyles 将GutterType（单值 / 数组 / 响应式对象）编译为--rs-grid-gutter、--rs-grid-row-gutter及其断点后缀变量，再由栅格 mixin 与行列 SCSS 换算成负外边距、内边距与row-gap，最终形成"一处配置、全局生效"的间距体系。配合文档中的 gutter 交互示例与 Row 测试用例，你可以快速在真实项目中落地这套响应式栅格间距方案。