Ant Design List 响应式栅格列表:基于 List grid 断点实现自适应列数布局

原创2026-09-07 20:44:541,752 阅读
文章标签:前端UI组件设计系统

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]);

整个计算链分四步:

  1. 判断是否需要响应式:检测 grid 的 key 中是否包含 responsiveArray 里的断点名(xxxl/xxl/xl/lg/md/sm/xs,定义于 components/_util/responsiveObserver.ts#L7)。若没有任何断点属性(如固定 column: 4),组件不会启动视口监听。
  2. 订阅视口状态:通过 components/grid/hooks/useBreakpoint.tsx 提供的 useBreakpoint Hook 订阅屏幕尺寸变化,返回当前激活的 ScreenMap(各断点是否命中的布尔集合)。
  3. 确定当前断点:按 xxxl → xs 的优先级顺序遍历 responsiveArray,取第一个命中的断点作为 currentBreakpoint。这正是"宽屏向下兼容"的实现:例如在 1366px 宽(命中 xl)时,如果 grid.xl 未配置而 grid.lg 配置了,那么……实际上源码取的是命中断点对应的精确值。
  4. 计算列宽:若当前断点配置了列数则使用它,否则回退到 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 响应式列表的实现原理。

登录后查看全文
ant-design