# 列表

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/list
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

最基础的列表展示，可承载文字、列表、图片、段落。


## 何时使用 {#when-to-use}

最基础的列表展示，可承载文字、列表、图片、段落，常用于后台数据展示页面。


:::warning{title=废弃提示}
List 组件已经进入废弃阶段，将于下个 major 版本移除，请改用 [Listy](/components/listy)，迁移方式参见 [如何从 List 迁移？](#faq-migrate-from-list)。
:::

## 代码演示 {#examples}


- 简单列表 · `simple`
- 基础列表 · `basic`
- 加载更多 · `loadmore`
- 竖排列表样式 · `vertical`
- 分页设置 · `pagination`
- 栅格列表 · `grid`

- 响应式的栅格列表 · `responsive`
- 滚动加载 · `infinite-load`
- 拖拽排序 · `drag-sorting`
- 拖拽排序（拖拽手柄） · `drag-sorting-handler`
- 栅格拖拽排序 · `grid-drag-sorting`
- 栅格拖拽排序（拖拽手柄） · `grid-drag-sorting-handler`
- 滚动加载无限长列表 · `virtual-list`



## API

通用属性参考：[通用属性](#jguang-common-props)

另外我们封装了 [ProList](https://procomponents.ant.design/components/list)，在 `antd` List 之上扩展了更多便捷易用的功能，比如多选，展开等功能，使用体验贴近 Table，欢迎尝试使用。

### List

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| bordered | 是否展示边框 | boolean | false |  | × |
| dataSource | 列表数据源 | any\[] | - |  | × |
| footer | 列表底部 | ReactNode | - |  | × |
| grid | 列表栅格配置 | [object](#list-grid-props) | - |  | × |
| header | 列表头部 | ReactNode | - |  | × |
| itemLayout | 设置 `List.Item` 布局，设置成 `vertical` 则竖直样式显示，默认横排 | `horizontal` \| `vertical` | `horizontal` |  | × |
| loading | 当卡片内容还在加载中时，可以用 `loading` 展示一个占位 | boolean \| [object](/components/spin#api) ([更多](https://github.com/ant-design/ant-design/issues/8659)) | false |  | × |
| loadMore | 加载更多 | ReactNode | - |  | × |
| locale | 默认文案设置，目前包括空数据文案 | object | {emptyText: `暂无数据`} |  | × |
| pagination | 对应的 `pagination` 配置，设置 false 不显示 | boolean \| object | false |  | × |
| renderItem | 当使用 dataSource 时，可以用 `renderItem` 自定义渲染列表项 | (item: T, index: number) => ReactNode | - |  | × |
| rowKey | 当 `renderItem` 自定义渲染列表项有效时，自定义每一行的 `key` 的获取方式 | `keyof` T \| (item: T) => `React.Key` | `"key"` |  | × |
| size | list 的尺寸 | `default` \| `large` \| `small` | `default` |  | × |
| split | 是否展示分割线 | boolean | true |  | × |

### pagination

分页的配置项。

| 参数     | 说明               | 类型                         | 默认值   |
| -------- | ------------------ | ---------------------------- | -------- |
| position | 指定分页显示的位置 | `top` \| `bottom` \| `both`  | `bottom` |
| align    | 指定分页对齐的位置 | `start` \| `center` \| `end` | `end`    |

更多配置项，请查看 [`Pagination`](/components/pagination)。

### 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 | -      | 6.3.0 |

### List.Item

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| actions | 列表操作组，根据 `itemLayout` 的不同，位置在卡片底部或者最右侧 | Array&lt;ReactNode> | - |  | × |
| classNames | 语义化结构 className | [`Record<actions \| extra, string>`](#semantic-dom) | - | 5.18.0 | 5.18.0 |
| extra | 额外内容，通常用在 `itemLayout` 为 `vertical` 的情况下，展示右侧内容; `horizontal` 展示在列表元素最右侧 | ReactNode | - |  | × |
| styles | 语义化结构 style | [`Record<actions \| extra, CSSProperties>`](#semantic-dom) | - | 5.18.0 | 5.18.0 |

### List.Item.Meta

| 参数        | 说明               | 类型      | 默认值 | 版本 |
| ----------- | ------------------ | --------- | ------ | ---- |
| avatar      | 列表元素的图标     | ReactNode | -      |      |
| description | 列表元素的描述内容 | ReactNode | -      |      |
| title       | 列表元素的标题     | ReactNode | -      |      |

## Semantic DOM

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `extra` | 设置额外内容 | 5.18.0 |
| `actions` | 设置列表操作组 | 5.18.0 |

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

## 主题变量（Design Token）{#design-token}

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

| 令牌 | 类型 | 原生说明 |
| --- | --- | --- |
| `contentWidth` | `number \| string` | 内容宽度 |
| `itemPaddingLG` | `string` | 大号列表项内间距 |
| `itemPaddingSM` | `string` | 小号列表项内间距 |
| `itemPadding` | `string` | 列表项内间距 |
| `headerBg` | `string` | 头部区域背景色 |
| `footerBg` | `string` | 底部区域背景色 |
| `emptyTextPadding` | `CSSProperties['padding']` | 空文本内边距 |
| `metaMarginBottom` | `CSSProperties['marginBottom']` | Meta 下间距 |
| `avatarMarginRight` | `CSSProperties['marginRight']` | 头像右间距 |
| `titleMarginBottom` | `CSSProperties['marginBottom']` | 标题下间距 |
| `descriptionFontSize` | `number` | 描述文字大小 |

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

```ts
import type { CSSProperties } from 'react';

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, mergeToken } from '../../theme/internal';

export interface ComponentToken {
  /**
   * @desc 内容宽度
   * @descEN Width of content
   */
  contentWidth: number | string;
  /**
   * @desc 大号列表项内间距
   * @descEN Padding of large item
   */
  itemPaddingLG: string;
  /**
   * @desc 小号列表项内间距
   * @descEN Padding of small item
   */
  itemPaddingSM: string;
  /**
   * @desc 列表项内间距
   * @descEN Padding of item
   */
  itemPadding: string;
  /**
   * @desc 头部区域背景色
   * @descEN Background color of header
   */
  headerBg: string;
  /**
   * @desc 底部区域背景色
   * @descEN Background color of footer
   */
  footerBg: string;
  /**
   * @desc 空文本内边距
   * @descEN Padding of empty text
   */
  emptyTextPadding: CSSProperties['padding'];
  /**
   * @desc Meta 下间距
   * @descEN Margin bottom of meta
   */
  metaMarginBottom: CSSProperties['marginBottom'];
  /**
   * @desc 头像右间距
   * @descEN Right margin of avatar
   */
  avatarMarginRight: CSSProperties['marginRight'];
  /**
   * @desc 标题下间距
   * @descEN Margin bottom of title
   */
  titleMarginBottom: CSSProperties['marginBottom'];
  /**
   * @desc 描述文字大小
   * @descEN Font size of description
   */
  descriptionFontSize: number;
}

/**
 * @desc List 组件的 Token
 * @descEN Token for List component
 */
interface ListToken extends FullToken<'List'> {
  /**
   * @desc 列表项类名
   * @descEN Class name of list item
   */
  listBorderedCls: string;
  /**
   * @desc 最小高度
   * @descEN Minimum height
   */
  minHeight: number | string;
}
```

## FAQ {#faq}

### List 组件废弃后，有替代方案吗？ {#faq-listy-replacement}

有，请使用 `antd@6.6.0` 起提供的 [Listy](/components/listy) 组件，它是 List 的继任者，内置了虚拟滚动、分组吸顶、程序化滚动等能力。并且支持灵活的自定义渲染方式，致力于满足不同场景下的列表需求。

### 如何从 List 迁移？ {#faq-migrate-from-list}

列表在不同场景下的表现形式各有不同，因此很难给出一份逐条对应的迁移指南。但得益于 Listy 提供的自定义渲染能力，List 中那些预设结构现在都可以在 `itemRender` 里用普通 JSX 重新组合。

对应关系如下：

- **数据与渲染**：`dataSource` 对应 `items`，`renderItem` 对应 `itemRender`；`rowKey` 含义不变，但在 Listy 中为必填且不再默认取 `key` 字段，原先依赖默认值的需显式传 `rowKey="key"`。列表数据量较大时无需借助第三方依赖，配合 `height` 开启 `virtual` 即可实现虚拟滚动。
- **行内的预设结构**：`List.Item`、`List.Item.Meta`、`actions`、`extra` 等均可在 `itemRender` 中自行组合。
- **列表外的结构**：`header` 与 `footer` 直接写在 Listy 外层，`loading` 用 [Spin](/components/spin) 包裹，`pagination` 自行切片后传入 `items` 并搭配 [Pagination](/components/pagination) 使用，`loadMore` 可参考[无限加载](/components/listy#listy-demo-infinite)示例。
- **样式相关**：`bordered`、`split`、`size` 通过语义化 DOM 的 `classNames`、`styles` 与主题变量调整；`grid` 场景不建议迁移到 Listy，请直接使用 [Row / Col](/components/grid) 搭配 [Card](/components/card) 实现卡片墙布局。


## 原生通用属性 {#jguang-common-props}


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

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


## 安装并复现示例

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

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

## 原生类型参考

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

- `vendor/components/list/Item.tsx`
- `vendor/components/list/context.ts`
- `vendor/components/list/index.tsx`
- `vendor/components/list/style/index.ts`

## 来源与许可

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

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

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt