CardList

网格展示实体摘要卡片，附带新建占位与结果计数。中文惯用名：卡片列表（基于 EntityCard 组合）。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.card-list`
名称	CardList
二级分类	业务组件（`business`）
用途	网格展示实体摘要卡片，附带新建占位与结果计数
描述	中文惯用名：卡片列表（基于 EntityCard 组合）。

预览

静态结构：根节点 data-slot="card-list"，内层网格容器 data-slot="card-list-grid"（gridTemplateColumns: repeat(columns, minmax(0,1fr)) + gap）；items 为空且未配置 createText 时渲染 Empty 空态；配置 createText 时首格渲染虚线新建占位卡（居中 icon + 文案，icon 默认 plus）；showCount 时底部渲染「共 N 个」计数（i18n pactor.cardList.total）。列表项事件在 EntityCard 回调上包装，回传 { item, index }；CardListItem 字段与 EntityCard props 同形并带索引签名，可携带额外业务字段原样回传。

DSL 结构

DslNode

{
  "type": "CardList",
  "props": {
    "columns": 3,
    "createText": "新建插件",
    "items": [
      {
        "icon": "code",
        "title": "规则引擎",
        "subtitle": "v1.2.0",
        "tags": [
          {
            "text": "已发布",
            "color": "green"
          }
        ],
        "description": "可视化规则配置与评分引擎。",
        "actions": [
          {
            "text": "配置",
            "key": "config"
          }
        ]
      },
      {
        "icon": "database",
        "title": "数据源管理",
        "subtitle": "v0.9.1",
        "tags": [
          {
            "text": "灰度",
            "color": "orange"
          }
        ],
        "description": "数据源接入与字段元数据维护。",
        "actions": [
          {
            "text": "配置",
            "key": "config"
          }
        ]
      }
    ]
  },
  "events": {
    "onItemClick": {
      "action": "navigate",
      "params": {
        "to": "/plugins/detail"
      }
    },
    "onCreateClick": {
      "action": "navigate",
      "params": {
        "to": "/plugins/create"
      }
    }
  }
}

何时用

何时使用

列表页以响应式网格展示实体摘要卡片（EntityCard），统一列数、间距与空态。
列表需要「新建」入口（首格虚线占位卡）与结果计数（共 N 个）。

何时不用

行式表格列表（列对齐、排序、批量操作）：使用 Table。
单卡片展示：直接用 EntityCard，不需要列表编排。

变体

变体	视觉形态	适用场景
正常网格	repeat(columns, minmax(0,1fr)) 响应式网格	实体摘要卡片墙
新建占位卡	首格虚线边框卡：居中图标 + createText	列表内置创建入口
空态	Empty 空态（emptyText 可定制）	无数据且无新建入口时
计数条	底部「共 N 个」	结果数量反馈（showCount）

API 属性

属性	类型	默认值	说明
`items`	`CardListItem[]`	[]	卡片数据；字段与 EntityCard props 同形，可携带额外业务字段（事件原样回传）
`columns`	`number`	3	网格列数
`gap`	`number`	16	卡片间距（px）
`createText`	`string`	—	配置后首格展示虚线新建占位卡
`createIcon`	`string`	'plus'	新建占位卡图标
`hoverable`	`boolean`	false	卡片整卡可点（透传 EntityCard）
`showCount`	`boolean`	false	底部展示「共 N 个」计数
`emptyText`	`string`	i18n pactor.table.empty	空数据文案
`className / style`	`string / CSSProperties`	—	根节点样式
`onItemClick`	`(event: { item: CardListItem; index: number }) => void`	—	整卡点击
`onItemAction`	`(event: { key: string; text: string; item: CardListItem; index: number }) => void`	—	卡内操作按钮点击
`onCreateClick`	`() => void`	—	新建占位卡点击

使用规范

列表事件统一经 onItemClick / onItemAction / onCreateClick 编排，卡片内部不直接写业务逻辑。
CardListItem 的额外业务字段靠索引签名携带，事件回传完整 item，避免在事件里反查数据源。
空态与新建入口互斥展示：有 createText 时渲染占位卡网格，不再显示 Empty。

正例

✓ 插件市场：columns=3 卡片网格 + createText「新建插件」+ showCount。
✓ 实体概览：items 携带 entityId 等业务字段，onItemClick 以 item.entityId 跳详情。

反例

✕ 用 CardList 渲染行式表格数据（应使用 Table）。
✕ 在 items 里塞展示逻辑所需的大对象（额外字段只放事件参数所需的最小集）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。