List
纵向展示同类对象集合。中文惯用名：列表。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.list |
| 名称 | List |
| 二级分类 | 数据展示（data-display） |
| 用途 | 纵向展示同类对象集合 |
| 描述 | 中文惯用名：列表。 |
预览
静态结构：List 渲染为 <ul> 根节点（data-slot="list"），每行 <li> 为 flex 三段式——左侧可选圆形 avatar（avatar 值匹配 http(s):/data:/路径协议时渲染 36px 圆形 <img>，否则渲染同尺寸圆形占位文本块）、中部 title（font-medium）与可选 description（弱化色，均单行 truncate 截断）、右侧可选 extra 弱化文本。split（缺省 true）以 divide-y 实现行间分隔线，bordered 为根节点外边框与圆角；items 为空时复用 Empty 原语渲染「暂无数据」空态（bordered 仍生效）。
DSL 结构
{
"type": "List",
"props": {
"items": [
{
"key": "1",
"title": "订单 #PO20260922001",
"description": "金额 ¥1,280.00 · 已支付"
},
{
"key": "2",
"title": "订单 #PO20260922002",
"description": "金额 ¥356.00 · 待审核"
}
],
"split": true
}
}何时用
何时使用
- 纵向展示同类对象集合：成员、文件、动态、消息摘要等结构一致的条目。
- 条目以浏览、识别为主：标题 + 辅助描述 + 头像 / 缩略图 + 行尾元信息。
- 内容区或卡片内的轻量列表，行数有限、无复杂行内操作。
何时不用
- 承载一个独立主题或对象摘要：使用 Card；List 表达的是集合而非单个对象。
- 需要按行列对齐、排序、筛选或行内密集操作结构化数据：使用 Table；高密度编辑与虚拟化使用 DataTable。
- 展示层级数据：使用 Tree；按时间顺序展示事件：使用 Timeline。
- 超大数据量的连续滚动：List 不分页不虚拟化，应使用带加载策略的专业列表方案。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认（split） | 行间细分隔线的纵向列表 | 常规对象集合，缺省形态 |
| split=false 无分隔 | 无分隔线的紧凑行 | 行数少或依靠留白分组的轻量列表 |
| bordered 带边框 | 外边框 + 圆角容器 | 独立成块的列表区，需与页面背景区分边界 |
| 带头像（图片） | 36px 圆形图片 | 成员、联系人等有人格化头像的条目 |
| 带头像（占位文本） | 36px 圆形灰底文本块 | 无图时用首字 / 缩写占位（如「张」「API」） |
| 空态 | Empty 原语「暂无数据」 | items 为空或数据未返回时的兜底呈现 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | ListItemData[] | [] | 列表数据（可含表达式解析后的数组）；项结构 { key?, title, description?, avatar?, extra? }；为空时渲染空态 |
split | boolean | true | 行间分隔线 |
bordered | boolean | false | 外边框（含圆角）；空态同样生效 |
className | string | — | 通用：根节点 class（与内置样式合并） |
style | CSSProperties | — | 通用：根节点内联样式 |
使用规范
- 行结构固定为三段：avatar（可选）→ title + description → extra（可选）；title 为主文本、description 与 extra 为弱化辅文本，均单行截断，长内容靠详情页承载。
- avatar 按值形态判定：图片地址（http(s):/data:/相对路径）渲染图片，其余文本渲染圆形占位块；同列表内保持一致形态。
- extra 仅承载字符串元信息（时间、数量、状态短文案），不放操作按钮；行内操作场景改用 Table。
- items 为空时必须呈现空态，不留空白区域；空态下 bordered 边框保留，避免容器塌陷。
- List 无内置分页 / 加载更多 / 虚拟化，数据量受控（建议数十行内）；行间分隔（split）缺省开启，密集列表保持默认。
正例
- ✓ 成员列表：avatar 传头像图片地址，title 姓名，description 角色，extra 展示加入时间。
- ✓ 接口资源列表：avatar 传「API」占位文本，split + bordered 组成独立资源区块。
- ✓ 数据未返回：items 传空数组，自动呈现「暂无数据」空态，容器边框不塌。
反例
- ✕ 在 extra 中塞入操作按钮或长段文本（extra 仅字符串元信息；操作列表改用 Table）。
- ✕ 用 List 展示层级数据或时间线（应分别使用 Tree / Timeline）。
- ✕ 同列表内混用图片头像与文本占位头像，或关闭 split 后条目过密无法分辨行边界。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。