Masonry 瀑布流
将等宽、不等高的内容排列为瀑布流。
用法
按最短列排列卡片
组件结构
加粗的是必需部件。
data-scope="masonry"：root · column · item
示例
响应式列
根据容器宽度调整列数
间距
设置列与项目之间的间距
sm
lg
顺序排列
按文档顺序逐列填充
设计指引
何时使用
- 展示图片墙、卡片流或长短不一的摘要。
- 希望内容按最短列排列并减少空白。
何时不用
特性
- 默认按最短列排列，也支持按顺序逐列填充。
- 支持固定列数和响应式列数。
- 支持五档行列间距。
组合
最佳实践
- 图片应提供宽高或宽高比，减少加载后的重排。
- 避免在会重排的项目中放置不可恢复的交互状态。
- Web Components 需按最大列数提供空的
column节点。
反模式
- 不要用 CSS 多栏替代瀑布流布局。
- 不要对有严格顺序的内容使用最短列策略。
- 不要用项目外边距代替
gap。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-masonry> |
| Vue 组件 | XhMasonry |
| 状态机 | 无，connect 直接由 props 算属性 |
| 皮肤 | @xihan-ui/styles/masonry.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
columns | MasonryColumns | 列数，未提供时按三列。也接受断点对象 { base, sm, md, lg, xl }，逐档写各自的列数， 未写的档沿用更窄的一档。换档依据容器自身的宽度，不是视口宽度。 | |
gap | MasonryGap | 列与列、项与项之间的间距档位：xs / sm / md / lg / xl，未提供时不留间距。档位对应的数值由皮肤决定。 | |
sequential | boolean | 按文档序逐列填充：项分段落入各列，阅读顺序仍是先走完左列，再走下一列。 未提供时最短列优先，视觉上更齐平，但相邻的两项未必相邻。 |
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
getRootProps | () => T['element'] | |
getColumnProps | (props: MasonryColumnProps) => T['element'] | |
getItemProps | (props: MasonryItemProps) => T['element'] |
无障碍
键盘
规格出处：W3C APG
无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。
- 最短列策略会改变 DOM 顺序。
- 顺序有意义的内容使用
sequential。 - 需要稳定焦点顺序时使用栅格。
样式参考
皮肤
@xihan-ui/styles/masonry.css 使用 [data-scope="masonry"][data-part="root"] 部件选择器，位于 xihan.components 层。覆盖样式使用 xihan.overrides。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-gap | props.gap |
root | data-sequential | ''（条件成立时才出现） |
column | data-index | String(column.index) |
item | data-column | String(item.column) |
item | data-index | String(item.index) |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-masonry-gap | columnroot | gap | defaultgap=lggap=mdgap=smgap=xlgap=xs | --xh-layout-gap-lg--xh-layout-gap-md--xh-layout-gap-sm--xh-layout-gap-xl--xh-layout-gap-xs--xh-space-0 | masonry 的 column、root 部件 gap 覆盖槽。 |
动效
本组件皮肤不含过渡与关键帧，也没有脚本驱动的动效：状态一变，外观立即到位。
响应式
- 响应式列数根据容器宽度计算。
- 内容或容器尺寸变化后自动重新排列。
RTL
- 列顺序和间距自动适配 RTL。