EntityCard

三层结构实体摘要卡：图标/标题/标签、描述与操作按钮。中文惯用名：实体卡片。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.entity-card`
名称	EntityCard
二级分类	业务组件（`business`）
用途	三层结构实体摘要卡：图标/标题/标签、描述与操作按钮
描述	中文惯用名：实体卡片。

预览

静态结构：三层纵向结构——上层左侧图标（logo 图片优先，其次 icon 白名单图标，底衬 bg-muted 圆角块）+ 标题/副文案，右侧标签组（Tag，EntityCardTag 的 color 映射语义色）；中层描述（line-clamp-2 固定两行截断）与右侧 meta 平铺，仅两者任一存在时渲染；下层操作按钮组（EntityCardAction，居右，footerBackground=true 时带浅底栏背景，负 margin 对齐 Card 内边距），未配置 actions 不渲染。整卡点击与按钮点击解耦（footer 容器 stopPropagation），hoverable 时整卡手型 + hover 高亮。

DSL 结构

DslNode

{
  "type": "EntityCard",
  "props": {
    "icon": "cube",
    "title": "客户实体",
    "subtitle": "cust_profile",
    "tags": [
      {
        "text": "启用",
        "color": "green"
      }
    ],
    "description": "客户画像主实体，含基础属性与扩展属性。",
    "meta": "创建于 2026-09-01",
    "actions": [
      {
        "text": "编辑",
        "key": "edit"
      },
      {
        "text": "删除",
        "key": "remove",
        "variant": "text",
        "danger": true
      }
    ]
  },
  "events": {
    "onClick": {
      "action": "navigate",
      "params": {
        "to": "/entity/detail"
      }
    },
    "onAction": {
      "action": "setState",
      "params": {
        "lastAction": "edit"
      }
    }
  }
}

何时用

何时使用

列表 / 网格页中展示业务实体摘要：图标（logo）、标题、副文案、状态标签、描述与维护信息。
摘要卡需要承载操作入口（编辑、配置、删除等），且操作与整卡点击解耦。
作为 CardList 的列表项底层卡片，与其他 business 组合组件配合。

何时不用

纯图文卡片、无实体语义（无操作区）：使用基础 Card。
只展示数据字段的平铺说明（键值对）：使用 Descriptions。

变体

变体	视觉形态	适用场景
icon / logo 图标形态	白名单图标（bg-muted 圆角底）或 logo 图片（size-9 rounded-md）	无品牌图片用图标，有 logo 时 logo 优先
标签组	上层右侧 Tag 语义色标签组	状态 / 分类标注（已发布、启用、灰度）
操作按钮组	下层居右按钮组，支持 ButtonVariant 与 danger	实体级操作入口；footerBackground 控制浅底栏
hoverable 整卡可点	手型光标 + hover 边框 / 背景高亮	点击卡片进入详情页

API 属性

属性	类型	默认值	说明
`icon`	`string`	—	图标名（Icon 白名单）；与 logo 二选一，logo 优先
`logo`	`string`	—	Logo 图片地址（alt 取 title）
`title`	`string`	—	主标题
`subtitle`	`string`	—	标题下方辅助短文案（版本号、编码等）
`tags`	`EntityCardTag[]`	—	上层右侧标签组：{ text, color? }
`description`	`string`	—	中层描述说明，固定两行高度、超出截断
`meta`	`string`	—	中层右侧维护信息（与描述平铺）
`actions`	`EntityCardAction[]`	—	下层操作按钮组：{ text, key?, variant?, danger? }；key 缺省取 text
`footerBackground`	`boolean`	true	下层是否带浅底栏背景
`hoverable`	`boolean`	false	整卡可点：手型 + hover 高亮
`contentClassName / className / style`	`string / CSSProperties`	—	内容区 / 根节点样式
`onClick`	`() => void`	—	整卡点击（操作区不触发）
`onAction`	`(event: { key: string; text: string; index: number }) => void`	—	操作按钮点击，回传 { key, text, index }

使用规范

标题 + 描述只放摘要信息，实体详情通过整卡点击进入详情页，不堆砌字段。
操作按钮按权重排列，危险操作（danger）与常规操作分组或置于末尾。
每个 EntityCardAction 给稳定 key（缺省取 text）：事件编排按 key 分发，文案变更不破坏逻辑。
卡片组合场景使用 CardList 统一网格 / 间距 / 空态，不逐卡手写布局。

正例

✓ 实体列表页：CardList 渲染 EntityCard，onItemClick 进详情，操作「编辑 / 删除」经 onItemAction 分发。
✓ 卡片墙：tags 标注「已发布 / 草稿」，footerBackground 开启浅底栏承载操作。

反例

✕ 把整页详情字段都塞进 EntityCard（应只放摘要，详情走跳转）。
✕ 在操作按钮上嵌套整卡点击语义（footer 已内置事件解耦，不应再包一层 onClick）。

Design Token 映射

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