List
List
最基础的列表展示，可承载文字、列表、图片、段落，常用于后台数据展示页面。
基础示例
基础用法
列表的基本使用方法。可用于承载文字、列表、图片和段落。
外观与状态
不同尺寸
列表组件提供了三种大小 sm, md, lg ，可根据业务需求自行选择。
内容与布局
前缀与后缀
本组配置对照
| 配置 | 作用 | 相关示例 |
|---|---|---|
bordered | 外边框 | 自定义内容 |
data | 数据，与 item 插槽配合 | 自定义内容 |
list-item 只提供 prefix / 默认内容 / suffix 三列布局。头像、标题、操作都由业务自己组合。
自定义内容
主体和两侧插槽都可以放任意内容。分页、栅格请自行组合 Pagination / Grid。
同时提供默认插槽与 data 时，默认插槽优先，item 插槽不会被调用。loading 仅表示整张列表首次加载或刷新；需要滚动分页时请使用 InfiniteScroll 组合。
滚动与虚拟列表
容器滚动
本组配置对照
| 配置 | 作用 | 相关示例 |
|---|---|---|
data | 数据，与 item 插槽配合 | 容器滚动、无限长列表、虚拟定位 |
virtual-list-props | 数据模式虚拟化；default插槽存在时忽略 | 无限长列表、虚拟定位 |
max-height | 普通列表最大高度；数字px/CSS长度，0不限 | 容器滚动 |
scrollbar | 普通列表自定义滚动条；false使用原生滚动 | 容器滚动 |
size | 仅实现 sm/md/lg，不支持 xs/xl | 容器滚动 |
split | 头尾及列表项分隔线，与边框独立 | 容器滚动 |
无限长列表
通过指定 virtualListProps 来开启虚拟列表，在大量数据时获得高性能表现。 在使用虚拟列表时，如果列表元素之间高度变化较大可能导致滚动时视口出现空白区域，可通过调整 virtualListProps.buffer 属性解决，使用方式。
虚拟定位
示例使用 Space direction="column" 将操作区放在列表上方，列表独占可用宽度；estimatedSize 是未测量行的估计高度，不要求业务行采用固定高度。
定位优先使用已渲染行的真实边界，行高测量会同步更新虚拟留白。程序滚动触发的渲染保留当前对齐；不同位置的原生滚动、新命令、数据替换、停用或卸载会取消旧补偿。auto 对已完整可见行不改变滚动位置和渲染窗口；这不代表持续追踪任意异步行高变化。
生命周期
保留命令与 KeepAlive 生命周期
本组配置对照
| 配置 | 作用 | 相关示例 |
|---|---|---|
data | 数据，与 item 插槽配合 | 保留命令与 KeepAlive 生命周期 |
virtual-list-props | 数据模式虚拟化；default插槽存在时忽略 | 保留命令与 KeepAlive 生命周期 |
API
List Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| data | 数据，与 item 插槽配合 | unknown[] | undefined |
| size | 仅实现 sm/md/lg，不支持 xs/xl | 'sm' | 'md' | 'lg' | md |
| bordered | 外边框 | boolean | true |
| split | 头尾及列表项分隔线，与边框独立 | boolean | true |
| loading | 首次加载/刷新反馈，不管理分页 | boolean | false |
| max-height | 普通列表最大高度；数字px/CSS长度，0不限 | number | string | 0 |
| virtual-list-props | 数据模式虚拟化；default插槽存在时忽略 | ListVirtualListProps | undefined |
| scrollbar | 普通列表自定义滚动条；false使用原生滚动 | boolean | ListScrollbarProps | true |
虚拟列表使用独立视口，不额外嵌套自定义滚动条。virtualListProps.height 优先于 maxHeight；均省略时虚拟视口默认 200px。数字/带单位CSS长度受支持，非法或非正 max-height 不限制高度。
ListVirtualListProps 支持 height、threshold、fixedSize、estimatedSize、buffer、itemKey、component。没有废弃的 isStaticItemHeight；data 统一由 List.data 提供。数据量小于或等于 threshold 时渲染全部；非固定高度使用测量值与 estimatedSize 估计，buffer 控制前后预渲染行数。
ListScrollbarProps 支持 type: 'track'|'embed'、outerClass、outerStyle、hide、disableHorizontal、disableVertical。属性作为 JavaScript 对象字段使用 camelCase。
Events / Methods
- scroll(event: Event)：真实滚动事件，一次滚动通知一次。
- scrollIntoView({ index?, key?, align })：虚拟列表定位，index 优先；align 为 top/bottom/auto。auto 在项目已完整可见时不滚动，否则最小滚动使其可见。无效目标、非虚拟模式不操作。
Slots
List：default（优先于data）、item({ item, index })、header、footer、empty。空态仅无默认插槽、无数据、非加载时渲染。ListItem：prefix、default、suffix，保持列表项语义，不管理按钮/业务交互。
类型
ListProps、ListSize、ListVirtualListProps、ListScrollbarProps、ListExpose、ListSlots、ListEmits、ListInstance、ListItemInstance。
List 与 InfiniteScroll 分工独立：List管理展示与可选虚拟视口；无限分页应组合 InfiniteScroll 的 status/target 交互，不在 List 中重复维护加载状态机。
样式变量
| Token | Default |
|---|---|
--c-list-background | transparent |
--c-list-empty-padding | 16px |
--c-list-empty-color | var(--c-list-text-color) |
--c-list-loading-padding | 0px |
--c-list-border-width | 1px |
--c-list-border-color | var(--c-color-neutral-3) |
--c-list-border-radius | var(--c-border-radius-md) |
--c-list-text-color | var(--c-color-text-1) |
--c-list-font-size | var(--c-font-size-body-3) |
--c-list-line-height | var(--c-line-height) |
--c-list-text-color-header | var(--c-color-text-1) |
--c-list-font-size-header | var(--c-font-size-title-1) |
--c-list-font-weight-header | var(--c-font-weight-500) |
--c-list-line-height-header | 1.5 |
--c-list-size-sm-padding-vertical-header | var(--c-spacing-4) |
--c-list-size-sm-padding-horizontal-header | var(--c-spacing-8) |
--c-list-size-sm-padding-vertical-item | 9px |
--c-list-size-sm-padding-horizontal-item | var(--c-spacing-8) |
--c-list-size-md-padding-vertical-header | var(--c-spacing-6) |
--c-list-size-md-padding-horizontal-header | var(--c-spacing-8) |
--c-list-size-md-padding-vertical-item | 13px |
--c-list-size-md-padding-horizontal-item | var(--c-spacing-8) |
--c-list-size-lg-padding-vertical-header | var(--c-spacing-7) |
--c-list-size-lg-padding-horizontal-header | var(--c-spacing-8) |
--c-list-size-lg-padding-vertical-item | 17px |
--c-list-size-lg-padding-horizontal-item | var(--c-spacing-8) |
--c-list-item-prefix-margin-right | var(--c-spacing-8) |
--c-list-item-suffix-margin-left | var(--c-spacing-8) |
--c-list-size-sm-padding-vertical-footer | var(--c-list-size-sm-padding-vertical-item) |
--c-list-size-sm-padding-horizontal-footer | var(--c-list-size-sm-padding-horizontal-item) |
--c-list-size-md-padding-vertical-footer | var(--c-list-size-md-padding-vertical-item) |
--c-list-size-md-padding-horizontal-footer | var(--c-list-size-md-padding-horizontal-item) |
--c-list-size-lg-padding-vertical-footer | var(--c-list-size-lg-padding-vertical-item) |
--c-list-size-lg-padding-horizontal-footer | var(--c-list-size-lg-padding-horizontal-item) |