Ant Design List 响应式栅格列表:基于 List grid 断点实现自适应列数布局
Ant Design List 响应式栅格列表:基于 List grid 断点实现自适应列数布局
响应式栅格列表(Responsive grid list)是 antd List 组件在栅格(grid)模式下的进阶用法:通过为 grid 配置传入 xs/sm/md 等响应式断点属性,让列表列数随视口宽度自动切换,同时保证栅格尺寸体系与 Layout Grid 的 Col 完全一致。本文以仓库内 responsive 示例 为主体,结合 List 组件源码讲解断点如何驱动列宽、栅格间距如何计算,帮助你写出"一套代码、多端自适应"的列表布局。
一、示例速览:一个最简响应式栅格列表
仓库中 responsive.md 对应的官方示例只有一个核心动作:给 <List grid={...}> 的 grid 对象同时声明固定断点列数与栅格间距,然后配合 Card 渲染数据项。
完整示例代码位于 components/list/demo/responsive.tsx,可直接复制运行:
import React from 'react';
import { Card, List } from 'antd';
const data = [
{ title: 'Title 1' },
{ title: 'Title 2' },
{ title: 'Title 3' },
{ title: 'Title 4' },
{ title: 'Title 5' },
{ title: 'Title 6' },
];
const App: React.FC = () => (
<List
grid={{
gutter: 16,
xs: 1,
sm: 2,
md: 4,
lg: 4,
xl: 6,
xxl: 3,
}}
dataSource={data}
renderItem={(item) => (
<List.Item>
<Card title={item.title}>Card content</Card>
</List.Item>
)}
/>
);
export default App;
这份数据的响应式策略一目了然:
| 视口宽度 | 列数 | 说明 |
|---|---|---|
< 576px(xs) |
1 | 手机单列堆叠 |
≥ 576px(sm) |
2 | 小平板两列 |
≥ 768px(md) |
4 | 平板/小桌面四列 |
≥ 992px(lg) |
4 | 常规桌面保持四列 |
≥ 1200px(xl) |
6 | 宽屏展开为六列 |
≥ 1600px(xxl) |
3 | 超宽屏反而收敛为三列 |
值得注意的细节是 gutter: 16——它表示每一项卡片之间的栅格间距,与 Layout Grid 中 Row 的 gutter 语义一致。此外示例特意让 xxl(1600px 以上)列数回落为 3,说明断点列数完全由产品形态决定,不必单调递增。
二、断点对齐:与 Layout Grid 的 Col 完全同源
原文档特别强调"尺寸与 Layout Grid 保持一致"(原文:The size property is as same as Layout Grid)。这意味着 List 响应式栅格不是另起炉灶,而是复用了 antd 栅格系统的断点定义。在 List 官方 API 文档 的 List grid props 一节中,每个断点属性都有明确的像素范围:
| 属性 | 生效视口 | 类型 | 默认值 |
|---|---|---|---|
column |
无断点匹配时的固定列数 | number | - |
gutter |
栅格间距(任意宽度均生效) | number | 0 |
xs |
< 576px |
number | - |
sm |
≥ 576px |
number | - |
md |
≥ 768px |
number | - |
lg |
≥ 992px |
number | - |
xl |
≥ 1200px |
number | - |
xxl |
≥ 1600px |
number | - |
xxxl |
≥ 1920px |
number | -(antd 6.3.0 起新增) |
类型层面,ListGridType 在 components/list/index.tsx#L38-L48 中声明:
export interface ListGridType {
gutter?: RowProps['gutter'];
column?: ColumnCount;
xs?: ColumnCount;
sm?: ColumnCount;
md?: ColumnCount;
lg?: ColumnCount;
xl?: ColumnCount;
xxl?: ColumnCount;
xxxl?: ColumnCount;
}
其中 gutter 直接引用了 grid 模块的 RowProps['gutter'] 类型,这是"与 Layout Grid 保持一致"在源码层面的直接证据:两者共享同一套栅格间距类型定义。因此若你已掌握 Grid/Col 的断点用法,即可零成本迁移到 List 栅格列表中。
三、源码剖析:断点如何驱动列宽计算
响应式并非 CSS 类名切换,而是由 List 在运行时监听视口并动态计算每列宽度。关键逻辑位于 components/list/index.tsx#L248-L274:
const needResponsive = Object.keys(grid || {}).some((key) =>
responsiveArray.includes(key as Breakpoint),
);
const screens = useBreakpoint(needResponsive);
const currentBreakpoint = React.useMemo(() => {
for (let i = 0; i < responsiveArray.length; i += 1) {
const breakpoint = responsiveArray[i];
if (screens[breakpoint]) {
return breakpoint;
}
}
return undefined;
}, [screens]);
const colStyle = React.useMemo(() => {
if (!grid) {
return undefined;
}
const columnCount =
currentBreakpoint && grid[currentBreakpoint] ? grid[currentBreakpoint] : grid.column;
if (columnCount) {
return {
width: `${100 / columnCount}%`,
maxWidth: `${100 / columnCount}%`,
};
}
}, [JSON.stringify(grid), currentBreakpoint]);
整个计算链分四步:
- 判断是否需要响应式:检测
grid的 key 中是否包含responsiveArray里的断点名(xxxl/xxl/xl/lg/md/sm/xs,定义于 components/_util/responsiveObserver.ts#L7)。若没有任何断点属性(如固定column: 4),组件不会启动视口监听。 - 订阅视口状态:通过 components/grid/hooks/useBreakpoint.tsx 提供的
useBreakpointHook 订阅屏幕尺寸变化,返回当前激活的ScreenMap(各断点是否命中的布尔集合)。 - 确定当前断点:按
xxxl → xs的优先级顺序遍历responsiveArray,取第一个命中的断点作为currentBreakpoint。这正是"宽屏向下兼容"的实现:例如在 1366px 宽(命中xl)时,如果grid.xl未配置而grid.lg配置了,那么……实际上源码取的是命中断点对应的精确值。 - 计算列宽:若当前断点配置了列数则使用它,否则回退到
grid.column;最终以100 / columnCount百分比宽度写入每个列表项的style,保证任意窗口下列数总和恰为 100% 不溢出。
在渲染层,列表项被放入 grid 模块的 Row(带 gutter)中(components/list/index.tsx#L279-L286),每个子项外面包一层设置了 colStyle 的 div,从而把"Row 的 gutter 间距 + 动态列宽"组合成完整的栅格排版。
四、断点映射底层:matchMedia 与主题 Token
useBreakpoint 之所以知道"≥ 1200px 命中 xl",是因为底层响应式观察器 useResponsiveObserver 会依据主题 Token 生成媒体查询字符串,并通过 window.matchMedia 注册监听。见 components/_util/responsiveObserver.ts#L17-L25:
const getResponsiveMap = (token: GlobalToken): BreakpointMap => ({
xs: `(max-width: ${token.screenXSMax}px)`,
sm: `(min-width: ${token.screenSM}px)`,
md: `(min-width: ${token.screenMD}px)`,
lg: `(min-width: ${token.screenLG}px)`,
xl: `(min-width: ${token.screenXL}px)`,
xxl: `(min-width: ${token.screenXXL}px)`,
xxxl: `(min-width: ${token.screenXXXL}px)`,
});
两个工程细节值得注意:
- xs 使用
max-width,其余断点使用min-width,保证断点区间首尾相接、无重叠缝隙;同时validateBreakpoints会校验各screenXXXMin ≤ screenXXX ≤ screenXXXMax且与下一断点有序衔接(components/_util/responsiveObserver.ts#L31-L66),从源头杜绝非法媒体查询。 - 断点像素值全部来自主题 Token(如
screenXL: 1200),意味着如果你通过 ConfigProvider 定制了这些 Token,List 的响应式断点也会同步改变,与 Layout Grid 保持一致的说法由此进一步坐实。
订阅注册 / 注销的完整生命周期(addEventListener('change')、首个订阅者触发 register、最后一个订阅者触发 unregister)也封装在 useResponsiveObserver 中,多组件共用同一实例、不重复创建监听,可参考 components/_util/responsiveObserver.ts#L95-L153。
五、实操要点与注意事项
1. 兜底列数 column 不能省略场景
若 grid 同时给出断点列数与 column,那么在尚未命中任何断点的极端窗口下会回退到 column。因此建议把 column 当作"最小公共列数"兜底。对比固定列数示例 grid.tsx 中仅 { gutter: 16, column: 4 } 的写法,响应式版本只是用断点字段替换/扩展了 column。
2. 与 Loading、Pagination 的组合
响应式判断只发生在 grid 渲染路径内;加载中的 Spin 占位与底部分页逻辑不受影响(分页切片与栅格列数是两条独立的渲染管线,见 components/list/index.tsx#L227-L296),你可以放心叠加使用。
3. 设计注意列数 × 内容密度
从示例可见 xxl: 3 反而比 xl: 6 少——超宽屏下每行卡片过多会造成内容过窄、阅读困难。响应式列数应结合卡片内文案长度整体权衡,而不是单纯"屏越宽列越多"。
4. 迁移提示:List 已进入废弃阶段
当前仓库对 List 组件标注了 DEPRECATED 警告(见 components/list/index.tsx#L304-L311),运行时会提示"List 组件已废弃,将在下一个大版本移除,antd 6.6.0 及以上请改用 Listy"。Listy 是官方指定的后继组件(位于 components/listy),若你在新项目中做响应式列表,建议优先评估 Listy 的栅格与虚拟滚动能力;本文涉及的响应式设计思路与断点体系仍可平滑迁移。
六、总结
响应式栅格列表 = Layout Grid 的断点体系 + List 的动态列宽计算:
- 断点定义:
xs~xxxl与 Col 断点 完全同源,像素值由主题 Token 决定; - 生效机制:
useBreakpoint+window.matchMedia实时订阅视口,命中最高优先级断点后以100 / 列数 %动态设置每项宽度; - 列宽兜底:未配置断点列数时回退
grid.column,gutter则由 Row 统一承载。
阅读顺序建议:先跑一遍 responsive.tsx 体验效果,再对照 List 文档 grid props 表 调整各断点列数,最后回到 List 源码 印证列宽计算逻辑,即可完整掌握 antd 响应式列表的实现原理。