rsuite Grid 栅格 `hidden` 属性详解：基于断点控制列的显示与隐藏

• 前端
• UI组件

hidden是 rsuite 24 列响应式栅格系统（Grid/Row/Col）中用于控制列在不同屏幕尺寸下显示或隐藏的核心属性。本文围绕 docs/pages/components/grid/fragments/hidden.md 中的完整示例展开，结合 Col 组件源码 与 栅格样式源码，讲解hidden的布尔值与响应式对象两种写法、底层 CSS 断点机制、与span等属性的协同用法，以及新旧两套 API 的迁移方式。读完你可以直接在项目里实现"移动端隐藏侧栏、桌面端展示"这类典型响应式布局。

一、最小可用示例：按断点隐藏列

hidden.md提供了一个可直接运行的最小示例：在一个流体栅格（Grid fluid）内放置两列，其中一列在超小屏（xs）时隐藏，另一列则采用span={{ xs: 24, md: 12 }}的响应式宽度：

import { Grid, Row, Col, Center } from 'rsuite'; const DecorativeBox = ({ children, ...rest }) => ( <Center bg="var(--rs-placeholder)" p={20} my={6} rounded="lg" {...rest}> {children} </Center> ); const App = () => ( <Grid fluid> <Row> <Col span={{ md: 12 }} hidden={{ xs: true }}> <DecorativeBox>hidden={`{ xs: true }`}</DecorativeBox> </Col> <Col span={{ xs: 24, md: 12 }}> <DecorativeBox>span={`{ xs: 24, md: 12 }`}</DecorativeBox> </Col> </Row> </Grid> ); ReactDOM.render(<App />, document.getElementById('root'));

代码要点：

• hidden={{ xs: true }}：表示仅在xs（超小屏）断点隐藏该列。由于栅格默认每行 12 列（在Row不传columns时），第一列在md及以上占据 6 列，第二列也占据 6 列，两列并排；而在xs屏幕下第一列被隐藏，第二列独占整行（xs: 24）。
• DecorativeBox只是演示用的装饰盒，用于视觉化列宽，并非栅格 API 的一部分，实际使用时替换为你的业务内容即可。
• 该示例的完整上下文可参考栅格组件总文档 docs/pages/components/grid/en-US/index.md（中文版见 docs/pages/components/grid/zh-CN/index.md）。

二、hidden的两种取值形式

在 ColProps 类型定义 中，hidden的类型为：

hidden?: boolean | ResponsiveValue<boolean>;

ResponsiveValue的定义（见 docs/pages/_common/types/responsive-value.md）如下：

type ResponsiveValue<T> = { xs?: T; // Extra small devices (portrait phones, <576px) sm?: T; // Small devices (landscape phones, ≥576px) md?: T; // Medium devices (tablets, ≥768px) lg?: T; // Large devices (desktops, ≥992px) xl?: T; // Extra large devices (large desktops, ≥1200px) xxl?: T; // Extra extra large devices (larger desktops, ≥1400px) };

2.1 布尔值形式（作用于 xs）

直接传入boolean时，按 Col.tsx 的 resolve 逻辑，该值会被视为作用于xs断点：

<Col hidden>…</Col> {/* 等价于 hidden={{ xs: true }} */} <Col hidden={false}>…</Col> {/* 等价于 hidden={{ xs: false }} */}

2.2 响应式对象形式（作用于多个断点）

传入对象时，每个断点键的值独立生效，未声明的断点不受影响（不会被隐藏）：

<Col hidden={{ xs: true, md: true }}>…</Col> {/* xs 与 md 隐藏，sm/lg/xl/xxl 正常显示 */} <Col hidden={{ xs: true }}>…</Col> {/* 仅 xs 隐藏 */}

从源码实现看，Col.tsx 中的处理逻辑 会遍历BREAKPOINTS常量数组（['xs', 'sm', 'md', 'lg', 'xl', 'xxl']，定义见 src/internals/constants/index.ts），只为显式出现的键生成对应类名，未声明的断点不会生成任何隐藏样式，因此默认保持可见。

三、底层原理：hidden是如何变成 CSS 的

hidden不依赖 JavaScript 运行时判断，而是通过生成语义化 CSS 类名 + 媒体查询实现，这也是其零运行时开销的原因。

3.1 类名生成规则

在 Col.tsx 的 addResponsiveClasses 中，hidden走的是特殊分支——它不生成rs-col-*前缀，而是使用全局根前缀生成rs-hidden-{size}类：

const classKey = type === 'hidden' ? rootPrefix(`hidden-${size}`) // 例如 rs-hidden-xs : prefix(`${size}-${type === 'span' ? '' : type + '-'}${value}`);

对应的测试用例（src/Grid/test/Col.spec.tsx）验证了这一点：

render( <Col span={{ md: 6 }} hidden={{ xs: true, md: true }}> Col </Col> ); expect(screen.getByText('Col')).to.have.class('rs-hidden-xs'); expect(screen.getByText('Col')).to.have.class('rs-col-md-6'); expect(screen.getByText('Col')).to.have.class('rs-hidden-md');

即hidden={{ xs: true, md: true }}会同时挂上rs-hidden-xs和rs-hidden-md两个类。

3.2 样式定义：display: none

隐藏样式在 src/Grid/styles/_mixin.scss 中定义：

// Hidden styles @mixin hidden($size) { .rs-hidden-#{$size} { display: none; } }

3.3 断点媒体查询区间

每个rs-hidden-{size}类只在其对应断点区间内生效，完整的媒体查询定义在 src/Grid/styles/index.scss：

@media (max-width: (vars.$screen-sm - 1)) { @include mixin.hidden(xs); } @media (min-width: vars.$screen-sm) and (max-width: (vars.$screen-md - 1)) { @include mixin.hidden(sm); } @media (min-width: vars.$screen-md) and (max-width: (vars.$screen-lg - 1)) { @include mixin.hidden(md); } @media (min-width: vars.$screen-lg) and (max-width: (vars.$screen-xl - 1)) { @include mixin.hidden(lg); } @media (min-width: vars.$screen-xl) and (max-width: (vars.$screen-xxl - 1)) { @include mixin.hidden(xl); } @media (min-width: vars.$screen-xxl) { @include mixin.hidden(xxl); }

断点像素值定义在 src/styles/_variables.scss，整理如下：

注意到xs是唯一使用max-width的断点，其余断点均为min-width加max-width的双端区间（xxl只有min-width）。这意味着rs-hidden-xs只在小于 576px 时生效，而rs-hidden-md只在 768px 至 991px 区间生效——超过该区间，类名仍在但样式失效，列恢复显示。这一机制保证了"只隐藏指定断点、其余断点不受影响"的语义。

四、hidden与span、offset等属性的协同

hidden与span、offset、push、pull、order一样，都支持响应式对象语法，可以自由组合。参考 hidden 示例中hidden={{ xs: true }}与span={{ md: 12 }}的组合，以及响应式演示 docs/pages/components/grid/examples/responsive.tsx 中的用法，常见的组合模式有：

模式一：小屏隐藏、大屏显示（移动端精简侧栏/辅助信息）

<Row> <Col xs={24} md={16}> <DecorativeBox>主内容区</DecorativeBox> </Col> <Col xs={24} md={8} hidden={{ xs: true }}> <DecorativeBox>侧栏：仅 ≥md 显示</DecorativeBox> </Col> </Row>

模式二：窄屏隐藏装饰列，宽屏恢复 12 列均分

<Row> <Col span={{ md: 12 }} hidden={{ xs: true }}> <DecorativeBox>隐藏列</DecorativeBox> </Col> <Col span={{ xs: 24, md: 12 }}> <DecorativeBox>主列</DecorativeBox> </Col> </Row>

在xs下，主列占满 24 列；在md及以上，隐藏列恢复显示，两列各占 12 列。

模式三：多断点分段控制

<Col span={{ xs: 24, sm: 12, lg: 6 }} hidden={{ sm: true, lg: true }}> <DecorativeBox>仅在 xs 与 md 区间显示</DecorativeBox> </Col>

这里列在xs显示（占满整行）、sm隐藏、md显示、lg与xl/xxl隐藏——借助断点区间的双端媒体查询，可以精确控制"哪一段屏幕宽度下出现"。

注意与span的配合

隐藏一个列后，同行其余列的span总和会自动决定其换行行为。rsuite 栅格默认每行 12 列，当列span与offset之和超过 12（或通过columns调整后的总数）时，多余列会折行到下一行（见总文档中的 Multiple Rows 一节 docs/pages/components/grid/en-US/index.md）。因此设计隐藏逻辑时，要同步考虑隐藏后剩余列是否仍能按预期铺满整行。

五、新旧 API 对比：xsHidden等旧属性的迁移

在 DeprecatedColProps 类型定义 中，旧版按断点拆分的属性（xsHidden、smHidden、mdHidden、lgHidden、xlHidden、xxlHidden等）已被标记为@deprecated，官方注释明确建议迁移到新的响应式对象语法，例如：

/** @deprecated Use hidden={{ xs: true }} instead */ xsHidden?: boolean;

旧写法：

<Col xsHidden smHidden mdHidden lgHidden xlHidden xxlHidden>…</Col>

新写法（等价）：

<Col hidden={{ xs: true, sm: true, md: true, lg: true, xl: true, xxl: true }}>…</Col>

对应旧写法的测试见 src/Grid/test/Col.spec.tsx，它断言xsHidden到xxlHidden会依次生成rs-hidden-xs至rs-hidden-xxl六个类。需要说明的是，从源码看旧属性目前仍被兼容处理：在 Col.tsx 的 legacy 分支 中，${size}Hidden这类键仍会被读取并转换成hidden-{size}类，只是官方类型标注为弃用，新代码应优先使用对象语法。

六、实现要点与源码位置速查

七、实战建议

1. 优先使用响应式对象语法。hidden={{ md: true }}比旧式mdHidden更直观、易维护，也便于与span、offset等属性统一书写风格。
2. 默认隐藏用hidden兜底，布局宽度交给span。例如"移动端只显示主内容"时，不必同时写两套span分支，直接给辅助列加hidden={{ xs: true }}即可。
3. 牢记断点区间是互斥的双端区间。hidden={{ md: true }}只在 768px–991px 生效，不要在lg屏幕上期待它继续隐藏；如需覆盖更大范围，请显式声明多个断点。
4. 渲染与视觉分离。hidden仅改变视觉呈现（display: none），列仍保留在 DOM 中，利于表单校验、可访问性信息等场景；若需要真正从 DOM 移除，应自行做条件渲染。

本文所依据的完整示例位于 docs/pages/components/grid/fragments/hidden.md，栅格组件全部属性（Grid的as/fluid、Row的gutter/align/justify、Col的span/offset/push/pull/order/hidden）见 docs/pages/components/grid/en-US/index.md。

• 前端
• UI组件