零基础跑通金融风控系统：贷款违约预测实战指南
2026/9/8 20:44:38
Ant Design List 组件全解析：基础用法、分页栅格与迁移至 Listy 的完整指南
【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design
List 是 Ant Design（antd）中最基础的列表展示组件，用于承载文字、列表项、图片与段落等数据内容，常见于各类后台数据展示页面。本文以 components/list/index.zh-CN.md 官方文档为核心，结合components/list目录下的源码实现与官方示例，系统讲解 List 的 API、分页/栅格/响应式等进阶用法、语义化结构与主题变量，并给出组件进入废弃阶段后的替代方案与从 List 迁移到 Listy 的实操对照。
阅读提示：当前仓库中 List 组件已标记为 DEPRECATED（废弃），预计在下个 major 版本移除。新项目应直接使用自
antd@6.6.0提供的 Listy 组件；本文保留对 List 的完整用法讲解，同时重点提供迁移路径。
何时使用
当页面需要按行渲染一组同类数据，且对表现形式的定制要求不高时，可以使用 List 作为最基础的展示容器。它能够承载：
- 纯文字列表（如新闻标题、日志记录）；
- 带头像、标题与描述的结构化列表项；
- 图片与富文本段落；
- 栅格化的“卡片墙”布局（常与 Card 搭配）。
从 components/list/index.tsx 的入口实现可以看出，List 由List（列表容器）、Item（单项）、Item.Meta（元信息：头像/标题/描述）三个复合成员构成，容器内部依赖ConfigProvider的useComponentConfig('list')、Grid 的Row/Col、Pagination、Spin等基础组件完成渲染，属于典型的“数据展示层组合组件”。
废弃状态说明
从antd5.x/6.x 开始，List 进入废弃流程。组件在非生产环境下会通过devUseWarning('List')输出一条 deprecated 提示（源码见 components/list/index.tsx），并设置displayName = 'Deprecated.List'。提示内容为：
The
Listcomponent is deprecated and will be removed in the next major version. If you're using version 6.6.0 or later, please useListyinstead.
即：List 将于下个 major 版本移除，若你使用的版本 ≥ 6.6.0，请改用 Listy。迁移方式见文末「FAQ：如何从 List 迁移」一节。
List API 详解
通用属性参考官方「通用属性」说明。此外，antd 官方在 List 之上封装了 ProList（位于 ProComponents 体系），扩展了多选、展开等贴近 Table 的交互能力，可作为强化替代方案考虑。
List
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| bordered | 是否展示边框 | boolean | false |
| dataSource | 列表数据源 | any[] | - |
| footer | 列表底部 | ReactNode | - |
| grid | 列表栅格配置 | object | - |
| header | 列表头部 | ReactNode | - |
| itemLayout | 设置List.Item布局，设置为vertical则竖直样式显示，默认横排 | string | - |
| loading | 当卡片内容还在加载中时，可以用loading展示一个占位 | boolean | object（Spin 配置） | false |
| loadMore | 加载更多（自定义 ReactNode，通常放“加载更多”按钮） | ReactNode | - |
| locale | 默认文案设置，目前包括空数据文案 | object | {emptyText:暂无数据} |
| pagination | 对应的pagination配置，设置 false 不显示 | boolean | object | false |
| renderItem | 当使用 dataSource 时，可以用renderItem自定义渲染列表项 | (item: T, index: number) => ReactNode | - |
| rowKey | 当renderItem自定义渲染列表项有效时，自定义每一行的key的获取方式 | keyofT | (item: T) =>React.Key | "key" |
| size | list 的尺寸 | default|large|small | default |
| split | 是否展示分割线 | boolean | true |
从 components/list/index.tsx 的默认参数解构可以看到实现层面的关键默认值：pagination = false、bordered = false、split = true、dataSource = []、loading = false，与上表完全一致。
从源码理解几个关键行为
- rowKey 的取值回退链：在
renderInternalItem（components/list/index.tsx）中，key 的确定顺序为：rowKey为函数时取其返回值 →rowKey为字符串时取item[rowKey]→ 否则取item.key；若以上都取不到，则回退为list-item-${index}。因此即使数据没有key字段，列表也能正常渲染。 - loading 对象化：
loading传入 boolean 时会在内部被转换为{ spinning: loadingProp }后透传给<Spin>（components/list/index.tsx）。所以loading也可以直接传 Spin 支持的完整配置对象。 - size 到样式的映射：
size经useSize合并后映射为lg/sm类名（components/list/index.tsx），配合 style/index.ts 中的itemPaddingLG、itemPaddingSM等 token 控制内边距。 - 数据源切片：当开启分页后，组件会按当前页与
pageSize对dataSource执行splice，仅渲染当前页的数据（components/list/index.tsx）。因此传入分页时，total会默认取dataSource.length，你无需手动计算总数。 - grid 时的渲染结构：开启
grid后，列表项不再渲染为<li>而是<div>（见 components/list/Item.tsx），并统一放入Row容器、按列数计算width/maxWidth，这是栅格布局的底层来源。
pagination
分页的配置项（可直接透传 Pagination 组件的全部属性，仅position/align为 List 特有）：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| position | 指定分页显示的位置 | top|bottom|both | bottom |
| align | 指定分页对齐的位置 | start|center|end | end |
更多配置项，请查看 Pagination 组件文档。
从源码看，List 内部维护了分页的受控状态：paginationCurrent默认取pagination.defaultCurrent || 1，paginationSize默认取pagination.defaultPageSize || 10（components/list/index.tsx）。渲染分页时位置逻辑为：top/both时置于列表头部上方，bottom/both时置于列表尾部（footer、loadMore之后），详见 components/list/index.tsx。
List grid props
grid支持固定列数与响应式断点列数两种写法：
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| 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 | - | 6.3.0 |
响应式断点实现的依据：组件通过useBreakpoint订阅当前屏幕断点，其候选顺序来自responsiveArray = ['xxxl', 'xxl', 'xl', 'lg', 'md', 'sm', 'xs']（见 components/_util/responsiveObserver.ts）。当grid中带断点键时，组件会从大到小取当前命中的最大断点，再用grid[断点]覆盖grid.column得到实际列数，最终通过width = 100 / columnCount的百分比计算每项宽度（components/list/index.tsx）。
List.Item
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| actions | 列表操作组，根据itemLayout的不同，位置在卡片底部或者最右侧 | Array<ReactNode> | - | |
| classNames | 语义化结构 className | Record<actions \| extra, string> | - | 5.18.0 |
| extra | 额外内容，通常用在itemLayout为vertical的情况下，展示右侧内容；horizontal展示在列表元素最右侧 | ReactNode | - | |
| styles | 语义化结构 style | Record<actions \| extra, CSSProperties> | - | 5.18.0 |
从 components/list/Item.tsx 可以看到两处值得注意的布局细节：
actions操作组渲染为<ul>，各项之间会自动插入<em>分隔符，且 action 分割样式来自主题变量colorSplit；- 当
itemLayout="vertical"且提供了extra时，列表项采用“主内容区 + 右侧 extra 区”的两栏结构（item-main+item-extra）；而 horizontal 布局下extra直接排在最右侧。是否启用 flex 模式由isFlexMode()判断：vertical 有extra即 flex；horizontal 下若 children 是「单一文本节点以外的多节点」则关闭 flex，改走块级排版。
classNames/styles的具体生效结构以 _semantic 演示（components/list/demo/_semantic.tsx）为准，支持actions与extra两个语义槽位，与下方「Semantic DOM」一节对应。
List.Item.Meta
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| avatar | 列表元素的图标 | ReactNode | - |
| description | 列表元素的描述内容 | ReactNode | - |
| title | 列表元素的标题 | ReactNode | - |
Meta的实现位于 components/list/Item.tsx：渲染为list-item-meta，左侧为可选avatar，右侧为title（<h4>）与description组成的content区。同时Meta通过useImperativeHandle暴露nativeElement引用，可拿到其根 DOM 节点。
代码演示：从官方示例看典型场景
components/list/index.zh-CN.md通过<code src="./demo/*.tsx">挂载了 17 个官方演示，均可在 components/list/demo 目录下找到完整可运行的源码，覆盖了 List 的主流用法：
- 简单列表 / 基础列表（simple.tsx、basic.tsx）：最基础的
dataSource + renderItem，配合header、footer、bordered、size使用。simple 示例同时演示了default/small/large三种尺寸下的内边距差异。 - 加载更多（loadmore.tsx）：通过
loadMore传入自定义按钮，点击后请求下一页数据并concat追加；每页先插入loading: true的占位项并用Skeleton占位，数据返回后替换，是「加载更多」模式的标准写法。 - 竖排列表样式（vertical.tsx）：设置
itemLayout="vertical"，配合actions、extra展示右侧图片与底部操作组，最接近内容流/资讯类页面。 - 分页设置（pagination.tsx）：用 Radio 动态切换
pagination={{ position, align }}，直观演示top/bottom/both与start/center/end组合。 - 栅格列表 / 响应式栅格列表（grid.tsx、responsive.tsx、grid-test.tsx）：
grid固定列数与断点列数两种形态。responsive 示例中grid={{ gutter: 16, xs: 1, sm: 2, md: 4, xl: 6, xxl: 3 }}，同一份dataSource随视口宽度自动重排。 - 滚动加载（无限长列表）（infinite-load.tsx）：监听容器滚动到底后触发下一页请求。
- 拖拽排序（drag-sorting.tsx、drag-sorting-handler.tsx）与栅格拖拽排序（grid-drag-sorting.tsx、grid-drag-sorting-handler.tsx）：展示列表项顺序调整的交互。
- 滚动加载无限长列表（虚拟滚动）（virtual-list.tsx）：通过
@rc-component/virtual-list的VirtualList作为数据滚动层，并配合List.Item逐行渲染，容器固定高度 400px、每行 47px，是 List 时代实现超长列表性能优化的官方示例——该能力在 Listy 中已内置为virtual。 - 调试类演示（debug 标记，不进入正式文档站点）：component-token.tsx（自定义组件 token）、spin-debug.tsx（Spin 加载状态调试）。
Semantic DOM 语义化结构
List.Item 的语义化结构如下（源码与在线调试演示见 components/list/demo/_semantic.tsx）：
actions：操作组容器（ul.list-item-action）；extra：额外内容区（div.list-item-extra）。
二者自5.18.0起支持通过classNames与styles定向定制，并且优先级规则是「组件自身配置合并 ConfigProvider 中list.item.classNames / list.item.styles」——在 components/list/Item.tsx 中可以看到moduleClass/moduleStyle先将全局配置展开再覆盖本地配置。这一点与 ConfigProvider 组件配置 中的语义化配置体系保持一致。
主题变量（Design Token）
List 的组件级 Token 定义与默认值均可在 components/list/style/index.ts 的ComponentToken接口与prepareComponentToken中查到，包括：
| Token | 说明 | 默认值来源 |
|---|---|---|
| contentWidth | 内容宽度 | 220 |
| itemPadding / itemPaddingLG / itemPaddingSM | 默认/大/小尺寸列表项内边距 | 由paddingContentVertical(±LG/SM)计算 |
| headerBg / footerBg | 头部/底部区域背景色 | transparent |
| emptyTextPadding | 空文本内边距 | token.padding |
| metaMarginBottom | Meta 下间距 | token.padding |
| avatarMarginRight | 头像右间距 | token.padding |
| titleMarginBottom | 标题下间距 | token.paddingSM |
| descriptionFontSize | 描述文字大小 | token.fontSize |
样式侧还内建了响应式规则：≤768px时收紧 action 与 extra 的间距，≤576px时列表项启用flexWrap（vertical 为wrap-reverse）以适配窄屏（components/list/style/index.ts）。这些 Token 可通过ConfigProvider的theme.components.List覆盖。
FAQ：替代方案与迁移
List 组件废弃后，有替代方案吗？
有。请使用antd@6.6.0起提供的 Listy 组件。Listy 是 List 的继任者，内置了虚拟滚动（virtual+height）、分组吸顶（group+sticky）、程序化滚动（refscrollTo）等能力，并支持灵活的自定义渲染（itemRender），致力于满足不同场景下的列表需求。
如何从 List 迁移？
列表在不同场景下的表现形式各有不同，因此很难给出一份逐条对应的迁移指南。但得益于 Listy 提供的自定义渲染能力，List 中那些预设结构现在都可以在itemRender里用普通 JSX 重新组合。对应关系如下：
- 数据与渲染：
dataSource对应items，renderItem对应itemRender；rowKey含义不变，但在 Listy 中为必填且不再默认取key字段，原先依赖默认值的需显式传rowKey="key"。列表数据量较大时无需借助第三方依赖，配合height开启virtual即可实现虚拟滚动。 - 行内的预设结构：
List.Item、List.Item.Meta、actions、extra等均可在itemRender中自行组合（例如用普通 JSX 或你喜爱的布局实现头像、标题、描述、操作区）。 - 列表外的结构：
header与footer直接写在 Listy 外层；loading用 Spin 包裹；pagination自行切片后传入items并搭配 Pagination 使用；loadMore可参考 Listy 文档中的「无限加载」示例。 - 样式相关：
bordered、split、size通过语义化 DOM 的classNames、styles与主题变量调整（Listy 提供{ root?, item?, groupHeader? }语义结构）；grid场景不建议迁移到 Listy，请直接使用 Row / Col 搭配 Card 实现卡片墙布局。
小结
- 在 antd 中，List 以「容器 + 项 + 元信息」的复合结构提供了从纯文本到卡片墙、从静态分页到滚动加载的完整数据展示能力，其分页切片、断点列数、loading 透传等实现细节都可以在 components/list/index.tsx 与 components/list/Item.tsx 中找到直接依据。
- 由于 List 已进入废弃流程，若你从
antd@6.6.0开始使用或正在做技术升级，应优先选择 Listy；存量 List 代码可参考上文「迁移对照」逐场景替换，其中分页/无限加载由外层自行组合，长列表与虚拟滚动则是 Listy 的天然优势。
【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考