虚拟列表

高性能列表，支持分组，并可为长列表开启虚拟滚动。

何时使用

需要渲染长列表，又不想为每一行都付出挂载成本时 —— 开启 virtual 后只渲染视口内的行。
列表需要分组，并让分组标题吸顶时。
需要以命令式方式控制滚动位置（跳到某一项、某个分组或某个像素位置）时。

代码演示

API

自 antd@6.6.0 版本开始提供该组件。

通用属性参考：通用属性

参数	说明	类型	默认值	版本	全局配置
classNames	语义化结构 class	`{ root?, item?, groupHeader? }`	-	6.6.0	6.6.0
group	分组配置，见下方 Group	`Group<T, K>`	-	6.6.0	×
height	滚动容器高度，内容超出后滚动	number	-	6.6.0	×
itemRender	渲染单行	`(item: T, index: number) => ReactNode`	-	6.6.0	×
items	列表数据源	`T[]`	`[]`	6.6.0	×
rowKey	每一项的唯一键，字段名或取值函数	`keyof T \| (item: T) => Key`	-	6.6.0	×
sticky	分组标题是否吸顶	boolean	false	6.6.0	×
styles	语义化结构 style	`{ root?, item?, groupHeader? }`	-	6.6.0	6.6.0
virtual	是否开启虚拟滚动，仅渲染视口内的行，需配合 `height` 使用	boolean	false	6.6.0	×
onScroll	原生滚动事件回调	`React.UIEventHandler<HTMLElement>`	-	6.6.0	×

Group

参数	说明	类型
key	计算每条数据所属的分组键，返回值相同的数据归为一组	`(item: T) => K`
title	渲染分组标题，入参为分组键与该组数据	`(groupKey: K, items: T[]) => ReactNode`

Ref

名称	说明	类型
scrollTo	滚动到某个位置、某一项或某个分组	`(config?: ListyScrollToConfig) => void`

ListyScrollToConfig 为以下之一：

形态	说明
number	滚动到某个像素位置（scrollTop）
`{ top?, left? }`	滚动到绝对像素坐标
`{ key, align?, offset? }`	滚动到 `rowKey` 等于 `key` 的数据项
`{ groupKey, align?, offset? }`	滚动到某个分组标题

align 可选 'top' | 'bottom' | 'auto'；offset 为对齐后额外的像素偏移。

Semantic DOM

语义节点	原生说明	版本
`root`	根元素，即滚动容器，设置字体与相对定位	—
`item`	条目元素，设置内间距、分割线与悬浮背景	—
`groupHeader`	分组标题元素，设置吸顶定位与背景色	—

语义说明来源: vendor/components/listy/demo/_semantic.tsx

主题变量（Design Token）

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

令牌	类型	原生说明
`itemPaddingBlock`	`number`	列表项的纵向内间距。
`itemPaddingInline`	`number`	列表项的横向内间距。

声明来源: vendor/components/listy/style/index.ts

import { unit } from '@ant-design/cssinjs';

import type { CSSObject } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks } from '../../theme/internal';

export interface ComponentToken {
  /**
   * @nameZH 列表项纵向内间距
   * @nameEN Item Vertical Padding
   * @desc 列表项的纵向内间距。
   * @descEN Vertical padding of a list item.
   */
  itemPaddingBlock: number;
  /**
   * @nameZH 列表项横向内间距
   * @nameEN Item Horizontal Padding
   * @desc 列表项的横向内间距。
   * @descEN Horizontal padding of a list item.
   */
  itemPaddingInline: number;
}

type ListyToken = FullToken<'Listy'>;

原生通用属性

Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

参数	说明	类型	默认值
style	自定义样式	CSSProperties	-
className	自定义类名	string	-
rootClassName	添加在组件最外层的 className	string	-
autoFocus	自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效	boolean	false

安装并复现示例

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

vendor/components/listy/index.tsx
vendor/components/listy/style/index.ts

来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。