# 列表 List

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

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

## 安装

```bash
npm install @arco-design/web-react@2.66.18
```

在入口引入 `@arco-design/web-react/dist/css/arco.css`，用 `ConfigProvider` 设置语言。React 19 项目还需在入口最先引入 `@arco-design/web-react/es/_util/react-19-adapter`，否则 Message、Modal 等命令式 API 无法渲染。

## 示例

- **基本用法**：最基础的列表展示，可承载文字、列表、图片、段落，常用于后台数据展示页面。
- **不同尺寸**：设置 `size` 可以使用三种尺寸（`small`, `default`, `large`）的列表，可根据业务需求自行选择。
- **基础列表**：使用 `List.Item.Meta` 可快速指定头像、标题、文字。
- **增加操作项**：通过 `actions` 来为列表添加操作项。
- **竖排列表样式**：这是一个包括分页、右侧内容、下方列表操作的示例。
- **栅格列表**：通过 `grid.span` 设置期望每行展示的列数。
- **响应式栅格**：通过 `grid.sm` 等响应式参数动态设置每个单项横跨的列数，注意此时不要设置 `grid.span`。
- **滚动加载列表**：可设置 `onReachBottom` 来动态滚动加载列表。当 `onReachBottom` 无法满足需求，可通过 `onListScroll` 来自定义列表滚动监听函数，此时默认的滚动监听函数将失效。
- **无限长列表**：通过指定 `virtualListProps` 来开启虚拟列表，在大量数据时获得高性能表现。 在使用虚拟列表时，如果列表元素之间高度变化较大可能导致滚动时视口出现空白区域，可以通过设定 `virtualListProps.itemHeight` 解决。`itemHeight` 用于计算实际需要渲染的 DOM 节点数目（视口高度 / 元素高度），其值越小实际渲染的 DOM 节点越多，性能开销也会随之增大。 **由于虚拟列表内部使用到了 ListItem 的 `ref`，因此如果你通过 `render` 返回了一个自定义函数组件，请使用 `React.forwardRef` 包裹它。**

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

## API

### List

|参数名|描述|类型|默认值|版本|
|---|---|---|---|---|
|bordered|是否显示边框|boolean |`true`|-|
|hoverable|列表项是否可悬浮|boolean |`-`|2.9.0|
|loading|是否加载中|boolean |`-`|-|
|split|是否显示分割线|boolean |`true`|-|
|defaultCurrent|滚动加载数据当前页码|number |`1`|-|
|offsetBottom|触发底部函数的距离阙值|number |`0`|-|
|throttleDelay|节流延时|number |`500`|-|
|size|列表的尺寸|'small' \| 'default' \| 'large' |`-`|-|
|children|当 dataSource 和 render 存在时，可不传此参数|ReactNode |`-`|-|
|footer|列表底部|ReactNode |`-`|-|
|header|列表头部|ReactNode |`-`|-|
|noDataElement|没有数据的时候显示的元素|ReactNode |`-`|-|
|scrollLoading|滚动加载状态时，滚动到底部的提示|string \| ReactNode |`-`|-|
|className|节点类名|string \| string[] |`-`|-|
|dataSource|列表渲染数据源，当children存在时，可不传此参数 (dataSource优先级更高）|T[] |`-`|-|
|grid|列表栅格配置|[ListGridProps](#listgridprops) |`-`|`column` in 2.20.0|
|listRef|当前列表的引用|MutableRefObject<[ListHandle](#listhandle)> |`-`|2.20.0|
|pagination|是否使用翻页，也可传入 `Pagination` 的配置|boolean \| [PaginationProps](pagination#pagination) |`-`|-|
|style|节点样式|CSSProperties |`-`|-|
|virtualListProps|传递虚拟列表属性，传入此参数以开启虚拟滚动|[AvailableVirtualListProps](#availablevirtuallistprops) |`-`|2.11.0|
|wrapperClassName|指定最外层包裹元素的类名|string \| string[] |`-`|-|
|wrapperStyle|指定最外层包裹元素的样式|CSSProperties |`-`|-|
|onListScroll|列表滚动回调函数,参数为列表滚动元素，当onReachBottom无法满足需求，可自定义滚动监听函数。|(elem: Element) => void |`-`|-|
|onReachBottom|滚动至底部触发函数|(currentPage: number) => void |`-`|-|
|render|单个列表渲染函数，当 children 存在时，可不传此参数|(item: T, index: number) => ReactNode |`-`|-|

### List.Item

|参数名|描述|类型|默认值|
|---|---|---|---|
|actionLayout|列表操作组的位置，默认horizontal，出现在右侧；vertical出现在下方。|'horizontal' \| 'vertical' |`horizontal`|
|extra|列表最右侧内容，额外内容|ReactNode |`-`|
|actions|列表项下方内容（列表操作组）|ReactNode[] |`-`|
|className|节点类名|string \| string[] |`-`|
|style|节点样式|CSSProperties |`-`|

### List.Item.Meta

|参数名|描述|类型|默认值|
|---|---|---|---|
|avatar|列表元素的图标|ReactNode |`-`|
|description|列表元素描述内容|ReactNode |`-`|
|title|列表元素标题|ReactNode |`-`|
|className|节点类名|string \| string[] |`-`|
|style|节点样式|CSSProperties |`-`|

### ListGridProps

```js
type ListGridProps = {
  column?: number;
} & Pick<RowProps, "gutter" | "justify" | "align"> &
  Pick<
    ColProps,
    "span" | "offset" | "order" | "pull" | "push" | GridResponsiveBreakpoint
  >;
```

### ListHandle

```js
export type ListHandle = {
  dom: HTMLDivElement;
  scrollIntoView: (index: number) => void;
};
```

### AvailableVirtualListProps

```js
export type AvailableVirtualListProps = Pick<
  VirtualListProps<any>,
  | "height"
  | "itemHeight"
  | "threshold"
  | "isStaticItemHeight"
  | "scrollOptions"
  | "onScroll"
  | "wrapperChild"
>;
```

### `<ListGridProps>`

|参数名|描述|类型|默认值|
|---|:---:|:---:|---:|
|gutter|行间距|`number`|`-`|
|span|栅格占位格数|`number`|`-`|
|xs|`xs` 对应的栅格占位格数|`number`|`-`|
|sm|`sm` 对应的栅格占位格数|`number`|`-`|
|md|`md` 对应的栅格占位格数|`number`|`-`|
|lg|`lg` 对应的栅格占位格数|`number`|`-`|
|xl|`xl` 对应的栅格占位格数|`number`|`-`|
|xxl|`xxl` 对应的栅格占位格数|`number`|`-`|

### VirtualListProps

|参数名|描述|类型|默认值|
|------|:----------:|:--------:|-----:|
|height|可视区高度 (`2.11.0` 开始支持如 `80%` 的 `string` 类型)|`number`|`200`|
|threshold|自动开启虚拟滚动的元素数量阈值，传入`null`以禁用虚拟滚动。|`number`\|`null`|`100`|
|isStaticItemHeight|是否为相同高度的静态元素|`boolean`|`true`|

---

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