Ant Design List 组件完全指南：从基础列表到虚拟滚动与网格布局
发布时间：2026/9/19 22:22:35 作者：尧图编辑部 阅读量：1,286
Ant Design List 组件完全指南从基础列表到虚拟滚动与网格布局【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design本指南围绕 antd 仓库 List 组件文档 展开系统讲解 Ant Design 中用于展示同一主题下多元素内容的 List 组件。你将掌握 List 的完整 API 参数、List.Item / List.Item.Meta 的组合用法、分页与「加载更多」两种翻页方案、网格与响应式栅格、滚动加载与虚拟列表等高阶实战技巧并通过源码实现理解其底层原理能够直接落地到企业级中后台业务中。何时使用 ListList 用于展示与同一主题single subject相关的内容。与 Table 的强结构化数据表格不同List 的内容可以由不同类型、不同尺寸的多个元素组成——例如一条新闻列表可以同时包含文字、缩略图、段落摘要和操作按钮。典型场景包括消息通知、动态 Feed 流商品 / 文章 / 数据卡片列表结合grid栅格模式带头像、标题、描述的通讯录或成员列表需要加载更多或分页浏览的长数据列表。List 采用dataSourcerenderItem的数据驱动渲染模型同时支持直接传入children自定义内容兼顾声明式与命令式两种使用方式。快速上手三种基础形态1. 简单列表Simple List最简单的用法是传入字符串数组配合header/footer/bordered等展示性属性。参考 simple.tsximport { Divider, List, Typography } from antd; const data [ Racing car sprays burning fuel into crowd., Japanese princess to wed commoner., Australian walks 100km after outback crash., Man charged over missing wedding girl., Los Angeles battles huge wildfires., ]; const App: React.FC () ( List header{divHeader/div} footer{divFooter/div} bordered dataSource{data} renderItem{(item) ( List.Item Typography.Text mark[ITEM]/Typography.Text {item} /List.Item )} / / ); export default App;要点header/footer接收任意ReactNode渲染在列表顶部与底部bordered为列表添加边框边框样式由 Design Token 中的lineWidth、lineType、colorBorder生成见 style/index.ts默认尺寸为default可通过size切换为small/large不同尺寸对应不同内边距 tokenitemPaddingSM/itemPadding/itemPaddingLG。2. 基础列表 数据驱动Basic List数据驱动的标准写法是dataSourcerenderItemList.Item.Meta组合参考 basic.tsximport { Avatar, List } from antd; const data [ { title: Ant Design Title 1 }, { title: Ant Design Title 2 }, { title: Ant Design Title 3 }, { title: Ant Design Title 4 }, ]; const App: React.FC () ( List itemLayouthorizontal dataSource{data} renderItem{(item, index) ( List.Item List.Item.Meta avatar{Avatar src{https://api.dicebear.com/7.x/miniavs/svg?seed${index}} /} title{a hrefhttps://ant.design{item.title}/a} descriptionAnt Design, a design language for background applications, is refined by Ant UED Team / /List.Item )} / ); export default App;List.Item.Meta提供avatar头像、title标题、description描述三个槽位是头像 标题 摘要布局的标准组合件。从源码 Item.tsx 可以看到Meta 内部渲染为-item-meta-avatar、-item-meta-title、-item-meta-description三层结构其间距、字号均由独立 Design Token 控制详见后文主题定制一节。3. 垂直布局 操作项Vertical当itemLayoutvertical时List.Item的actions操作区会从右侧移动到内容底部而extra额外内容则显示在右侧非常适合图文混排的资讯流参考 vertical.tsximport { LikeOutlined, MessageOutlined, StarOutlined } from ant-design/icons; import { Avatar, List, Space } from antd; const IconText ({ icon, text }: { icon: React.FC; text: string }) ( Space {React.createElement(icon)} {text} /Space ); const App: React.FC () ( List itemLayoutvertical sizelarge pagination{{ onChange: (page) console.log(page), pageSize: 3 }} dataSource{data} footer{divbant design/b footer part/div} renderItem{(item) ( List.Item key{item.title} actions{[ IconText icon{StarOutlined} text156 keylist-vertical-star-o /, IconText icon{LikeOutlined} text156 keylist-vertical-like-o /, IconText icon{MessageOutlined} text2 keylist-vertical-message /, ]} extra{img width{272} altlogo src... /} List.Item.Meta avatar{Avatar src{item.avatar} /} title{a href{item.href}{item.title}/a} description{item.description} / {item.content} /List.Item )} / );actions 与 extra 的位置规则关键行为差异水平布局horizontalactions与extra均显示在最右侧垂直布局verticalactions移到内容底部extra移到右侧源码中该逻辑通过ListContext下发itemLayout见 Item.tsx 的三元分支垂直布局且存在extra时渲染-item-main内容 actions与-item-extra两栏否则按水平模式平铺渲染。此外Item.tsx还实现了一个细节当List.Item直接包含多个文本节点时isItemContainsTextNodeAndNotSingular判断会加上-item-no-flex类回退为块级布局避免 flex 布局破坏纯文本内容。List 完整 API 参数详解以下参数表完整来自 index.en-US.md并结合 index.tsx 的类型定义与默认值展开说明。通用属性如className、style、id等可参考 Common props。List 主属性属性说明类型默认值bordered是否渲染列表边框booleanfalsedataSource列表数据源数组any[]-footer列表底部渲染器ReactNode-grid列表网格模式配置如{gutter: 16, column: 4}object-header列表顶部渲染器ReactNode-itemLayout列表布局方向horizontal|verticalhorizontalloading数据加载中是否显示 loading 指示器boolean | SpinPropsfalseloadMore显示加载更多内容ReactNode-localei18n 文案包括空数据文案object{emptyText: No Data}pagination分页配置设为false可隐藏boolean | objectfalserenderItem使用dataSource时自定义列表项渲染(item, index) ReactNode-rowKey列表项唯一 key可以是React.Key类型的字段名或接收 item 返回React.Key的函数keyof T| (item: T) React.Keykeysize列表尺寸default|large|smalldefaultsplit是否渲染列表项之间的分隔线booleantrue源码级行为补充rowKey 的三级兜底策略index.tsx优先使用函数rowKey(item)→ 其次取item[rowKey]→ 再退化为item.key→ 最终兜底为list-item-${index}。其中按 index 兜底的模式在数据变化时可能引起 key 不稳定生产环境建议始终为数据提供稳定唯一 key。loading 的双形态支持index.tsx传boolean时内部自动包装为{ spinning: loading }后交给 Spin 组件传对象时可直接透传 Spin 的tip、delay等属性。加载期间列表渲染一个minHeight: 53的占位层源码中isLoading div style{{ minHeight: 53 }} /。size 的全局联动size通过useSizehook 与 ConfigProvider 的全局size上下文合并组件级配置优先最终映射为lg/smCSS 类。空数据文案优先级index.tsxlocale.emptyText ConfigProvider 的renderEmpty(List) 内置DefaultRenderEmpty。pagination默认false不分页split默认truebordered默认false——这些默认值在组件函数签名中直接可见index.tsx。List.Item属性说明类型默认值版本actions列表项操作区内容。itemLayout为vertical时显示在底部否则显示在最右侧ArrayReactNode-classNames语义化结构 classNameRecordactions \| extra, string-5.18.0extra列表项额外内容。itemLayout为vertical时显示在右侧否则显示在最右侧ReactNode-styles语义化 DOM 样式Recordactions \| extra, CSSProperties-5.18.0classNames/styles5.18.0 新增允许对actions与extra两个语义模块做精确的类名与内联样式定制。源码 Item.tsx 显示二者会与 ConfigProvider 中list.item.classNames / list.item.styles的全局配置深度合并实现全局主题 局部覆盖的两层定制体系。List.Item.Meta属性说明类型默认值avatar列表项头像ReactNode-description列表项描述ReactNode-title列表项标题ReactNode-Meta 内部仅渲染有值的槽位title或description都不存在时整个 content 区不渲染避免产生空 DOM见 Item.tsx。分页方案一内置 Pagination 配置List 内置了对 Pagination 组件的集成传入pagination对象即自动分页dataSource会在渲染前按当前页切片。List pagination{{ position: bottom, align: center, pageSize: 3, onChange: (page) console.log(page) }} dataSource{data} renderItem{(item) List.Item{item}/List.Item} /交互式示例可切换位置与对齐方式见 pagination.tsx。pagination 专属参数属性说明类型默认值position指定Pagination的位置top|bottom|bothbottomalign指定Pagination的对齐方式start|center|endend其余参数pageSize、current、total、hideOnSinglePage、showSizeChanger等全部透传给 Pagination 组件详见 Pagination 文档。源码级实现原理index.tsx分页状态由组件内部useState管理paginationCurrent默认取pagination.defaultCurrent || 1paginationSize默认取pagination.defaultPageSize || 10通过extendsObject合并三层配置默认值{ current: 1, total: 0 }→ 基于dataSource.length计算出的total与当前状态 → 用户传入的pagination对象用户配置优先级最高存在越界保护当current Math.ceil(total / pageSize)时自动收敛到最大有效页数据切片逻辑仅当dataSource.length (current - 1) * pageSize时执行splice否则保持原数据避免空页渲染onChange/onShowSizeChange会被包装triggerPaginationEvent在更新内部状态的同时回调用户传入的事件处理函数分页器渲染位置由paginationPosition决定top渲染在头部之前bottom渲染在尾部之后both则两处都渲染index.tsx。对应的测试用例位于 pagination.test.tsx覆盖了hideOnSinglePage单页隐藏分页器、pageSize切片、快照渲染等行为。分页方案二加载更多Load More与内置分页不同加载更多由loadMore属性接管列表尾部区域配合loading属性与手动数据追加实现参考 loadmore.tsxconst [initLoading, setInitLoading] useState(true); const [loading, setLoading] useState(false); const [list, setList] useStateDataType[]([]); const onLoadMore () { setLoading(true); setList(data.concat([...new Array(count)].map(() ({ loading: true, name: {}, picture: {} })))); fetch(fakeDataUrl) .then((res) res.json()) .then((res) { setData(data.concat(res.results)); setList(data.concat(res.results)); setLoading(false); }); }; const loadMore !initLoading !loading ? ( div style{{ textAlign: center, marginTop: 12, height: 32, lineHeight: 32px }} Button onClick{onLoadMore}loading more/Button /div ) : null; return ( List classNamedemo-loadmore-list loading{initLoading} itemLayouthorizontal loadMore{loadMore} dataSource{list} renderItem{(item) ( List.Item actions{[a keylist-loadmore-editedit/a, a keylist-loadmore-moremore/a]} Skeleton avatar title{false} loading{item.loading} active List.Item.Meta avatar{Avatar src{item.picture.large} /} title{a hrefhttps://ant.design{item.name?.last}/a} descriptionAnt Design, a design language for background applications, is refined by Ant UED Team / divcontent/div /Skeleton /List.Item )} / );实现要点loadMore是一个受控的ReactNode是否渲染加载更多按钮完全由业务状态如initLoading、loading决定用Skeleton的loading属性为新增但尚未返回数据的占位项展示骨架屏形成平滑的加载体验源码中loadMore与pagination、footer共同参与isSomethingAfterLastItem()判断index.tsx用于决定最后一个列表项是否需要保留分隔线。网格与响应式布局Grid固定网格 Grid通过grid{{ gutter: 16, column: 4 }}即可让 List 变为多列栅格通常与 Card 搭配构成卡片墙参考 grid.tsxList grid{{ gutter: 16, column: 4 }} dataSource{data} renderItem{(item) ( List.Item Card title{item.title}Card content/Card /List.Item )} /List grid props属性说明类型默认值column网格列数number-gutter网格间距number0xs576px时的列数number-sm≥576px时的列数number-md≥768px时的列数number-lg≥992px时的列数number-xl≥1200px时的列数number-xxl≥1600px时的列数number-响应式网格 Responsive Grid通过同时配置xs~xxl各断点列数实现断点自适应参考 responsive.tsxList 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 )} /响应式实现原理index.tsx组件先检测grid配置中是否含xs~xxl任一响应式字段needResponsive仅在需要时才调用useBreakpointhook 订阅窗口变化避免无谓的监听开销useBreakpoint基于 responsiveObserver 的媒体查询机制返回各断点是否命中的映射断点匹配按xs sm md lg xl xxl顺序取当前命中的最大断点responsiveArray遍历命中该断点的列数即作为columnCount列宽通过colStyle计算为${100 / columnCount}%含maxWidth配合 Grid 的RowCol实现等宽分列——未配置任何响应式字段时useBreakpoint不启用直接用grid.column网格模式下List.Item外层由Item.tsx渲染为Colflex{1}内部才渲染实际的 item 元素Item.tsx。滚动加载与虚拟列表高阶当数据量持续增长继续使用加载更多按钮会带来大量 DOM 渲染开销此时有两种进阶方案。滚动加载Infinite Scroll配合第三方库react-infinite-scroll-component实现触底自动加载参考 infinite-load.tsxdiv idscrollableDiv style{{ height: 400, overflow: auto, padding: 0 16px }} InfiniteScroll dataLength{data.length} next{loadMoreData} hasMore{data.length 50} loader{Skeleton avatar paragraph{{ rows: 1 }} active /} endMessage{Divider plainIt is all, nothing more /Divider} scrollableTargetscrollableDiv List dataSource{data} renderItem{(item) ( List.Item key{item.email} List.Item.Meta avatar{Avatar src{item.picture.large} /} title{a hrefhttps://ant.design{item.name.last}/a} description{item.email} / divContent/div /List.Item )} / /InfiniteScroll /div注意scrollableTarget需要指向承载滚动容器的id数据量不大时该方案实现成本最低。虚拟列表Virtual List当列表项成百上千时应使用rc-virtual-list只渲染可视区域内的节点参考 virtual-list.tsximport VirtualList from rc-virtual-list; const ContainerHeight 400; VirtualList data{data} height{ContainerHeight} itemHeight{47} itemKeyemail onScroll{onScroll} {(item: UserItem) ( List.Item key{item.email} List.Item.Meta avatar{Avatar src{item.picture.large} /} title{a hrefhttps://ant.design{item.name.last}/a} description{item.email} / divContent/div /List.Item )} /VirtualListheight为虚拟滚动视口高度itemHeight为预估的单项高度用于计算滚动位置与渲染窗口itemKey指定唯一键字段滚动到底部前追加数据的判断基于scrollHeight - scrollTop - ContainerHeight 1的容差比较注意虚拟列表模式下通常不再依赖 List 自身的dataSource分页数据累积逻辑由外部状态控制。主题定制与 Design TokenList 的所有视觉细节均通过 cssinjs 的 Design Token 驱动令牌定义见 style/index.ts 的ComponentToken接口默认值由prepareComponentToken给出style/index.ts。完整 Token 清单Token说明默认值contentWidth内容宽度用于小屏垂直布局换行220itemPadding默认尺寸列表项内边距${paddingContentVertical} 0itemPaddingSM小尺寸列表项内边距${paddingContentVerticalSM} ${paddingContentHorizontal}itemPaddingLG大尺寸列表项内边距${paddingContentVerticalLG} ${paddingContentHorizontalLG}headerBg头部区域背景色transparentfooterBg底部区域背景色transparentemptyTextPadding空数据文案内边距paddingmetaMarginBottomMeta 下间距paddingavatarMarginRight头像右间距paddingtitleMarginBottom标题下间距paddingSMdescriptionFontSize描述文字字号fontSize通过 ConfigProvider 覆盖 Token参考 component-token.tsx使用ConfigProvider的theme.components.List即可全局或局部覆盖ConfigProvider theme{{ components: { List: { headerBg: pink, footerBg: pink, emptyTextPadding: 32, itemPadding: 26px, itemPaddingSM: 16px, itemPaddingLG: 36px, metaMarginBottom: 20, avatarMarginRight: 20, titleMarginBottom: 10, descriptionFontSize: 20, }, }, }} {/* 所有 List 将应用上述主题 */} /ConfigProvider从源码看样式生成的三个层次style/index.ts 中genStyleHooks(List, ...)依次生成三类样式genBaseStyle基础样式包括 flex 布局的-item、-item-meta三栏结构、-item-action操作区、加载态-spin最小高度、空数据-empty-text等genBorderedStylebordered模式的边框、圆角borderRadiusLG与不同尺寸下的内边距覆盖genResponsiveStyle基于screenMD/screenSM的媒体查询——中等屏以下操作区与 extra 调整外边距小屏以下max-width: screenSM列表项flexWrap: wrap、垂直布局wrap-reverse并让 extra 居中换行实现移动端友好降级style/index.ts。常见实践建议始终提供稳定 keyrowKey优先使用数据中的唯一 ID 字段或返回唯一值的函数避免依赖源码中的 index 兜底防止重排时出现渲染错位按数据规模选择方案几十条以内用内置pagination交互式追加用loadMore Skeleton持续滚动且数据量大用 Infinite Scroll上千条且需要流畅滚动用rc-virtual-list网格与响应式结合卡片场景优先配置xs~xxl断点列数让移动端自动降为单列空状态定制通过locale.emptyText或 ConfigProvider 的renderEmpty提供更友好的空数据提示主题统一治理headerBg、itemPadding等令牌既可在 ConfigProvider 全局配置也可与List.Item的classNames/styles5.18.0局部覆盖配合形成全局 局部的分层样式治理。测试保障List 组件在仓库中拥有完整的测试覆盖components/list/testsindex.test.tsx覆盖基础渲染与空状态、pagination.test.tsx覆盖分页切片与分页器显隐、loading.test.tsx覆盖加载态、Item.test.tsx覆盖列表项与 Meta 结构、image.test.ts与demo.test.ts验证示例代码的可运行性。这些测试用例是理解组件行为契约的最佳参考。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 