瀑布流
将不同高度的内容排列成瀑布流布局。
瀑布流布局组件，用于展示不同高度的内容。
何时使用
- 展示不规则高度的图片或卡片时
- 需要按照列数均匀分布内容时
- 需要响应式调整列数时
代码演示
- 基础用法 ·
basic - 响应式 ·
responsive - 图片 ·
image - 动态更新 ·
dynamic - 自定义语义结构的样式和类 ·
style-class
API
通用属性参考：通用属性
Masonry
| 参数 | 说明 | 类型 | 默认值 | 版本 | 全局配置 |
|---|---|---|---|---|---|
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string> | - | 6.0.0 | 6.0.0 |
| columns | 列数，可以是固定值或响应式配置 | number | { xs?: number; sm?: number; md?: number } | 3 | × | |
| fresh | 是否持续监听子项尺寸变化 | boolean | false | × | |
| gutter | 间距，可以是固定值、响应式配置或水平垂直间距配置 | Gap | [Gap, Gap] | 0 | × | |
| items | 瀑布流项 | MasonryItem[] | - | × | |
| itemRender | 自定义项渲染 | (item: MasonryItem) => React.ReactNode | - | × | |
| styles | 语义化结构 style，支持对象和函数形式 | Record<SemanticDOM, CSSProperties> | ((info: { props }) => Record<SemanticDOM, CSSProperties>) | - | 6.0.0 | 6.0.0 |
| onLayoutChange | 列排序回调 | ({ key: React.Key; column: number }[]) => void | - | × |
MasonryItem
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| children | 自定义展示内容，相对 itemRender 具有更高优先级 | React.ReactNode | - |
| column | 自定义所在列 | number | - |
| data | 自定义存储数据 | T | - |
| height | 高度 | number | - |
| key | 唯一标识 | string | number | - |
Gap
Gap 是项之间的间距，可以是固定值，也可以是响应式配置。
type Gap = undefined | number | Partial<Record<'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl', number>>;
Semantic DOM
| 语义节点 | 原生说明 | 版本 |
|---|---|---|
root | 根元素，设置相对定位、flex布局和瀑布流容器样式 | — |
item | 条目元素，设置绝对定位、宽度计算、过渡动画和瀑布流项目样式 | — |
语义说明来源: vendor/components/masonry/demo/_semantic.tsx
Design Token
类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。
原生 ComponentToken 未声明可直接提取的自有字段；共享令牌或继承关系以以下声明为准。
声明来源: vendor/components/masonry/style/index.ts
import type { CSSObject } from '@ant-design/cssinjs';
import type { FullToken, GenerateStyle } from '../../theme/internal';
import { genStyleHooks } from '../../theme/internal';
// biome-ignore lint/suspicious/noEmptyInterface: ComponentToken need to be empty by default
export interface ComponentToken {}
export interface MasonryToken extends FullToken<'Masonry'> {}
原生通用属性
Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |
安装并复现示例
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。
原生类型参考
源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。
vendor/components/masonry/Masonry.tsxvendor/components/masonry/MasonryItem.tsxvendor/components/masonry/hooks/usePositions.tsvendor/components/masonry/style/index.ts
来源与许可
https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd
保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。