---
title: 开发文档
order: 3
category: pro
---

# PisellEntityCard 开发文档

## 1. 基础信息

- **组件名称**：PisellEntityCard
- **组件版本**：1.0
- **组件分类**：Data Display / Pro Components
- **依赖**：基于 PisellBaseCard 封装，不依赖 PisellBasicCardProps。

## 2. 需求点罗列

1. **Object Summary 必选结构**：媒体区（Avatar/Thumbnail/Icon）+ 主文案 + 次级文案 + 标签，均可配置显隐与数据源。
2. **信息密度**：B1-Line / B2-Mini / B5-Standard / B9-Extended，控制展示行数与字段数量。
3. **布局**：Horizontal / Vertical，可配置。
4. **数据源**：结构化配置（media、primaryText、secondaryTexts、tags、actions），支持字段显隐与排序（通过数组顺序）。
5. **可选 Footer/Actions**：支持文本/按钮/icon，可控制显隐与样式。
6. **左滑删除**：本次直接实现，可配置开关与删除回调。
7. **样式**：Card 背景、圆角、边框、阴影、padding、gap；文本字号/字重/颜色/行数；媒体尺寸与圆角；标签位置等，透传或扩展 BaseCard。
8. **宽度**：内容撑满 / 固定宽度 / 撑满父容器。
9. **插槽**：renderMedia、renderPrimary、renderSecondary、renderTags、renderActions，用于完全自定义某一块。

## 3. 组件描述

PisellEntityCard 是基于 PisellBaseCard 的实体展示卡片，用于统一展示“一个实体”的识别信息（头像/缩略图、主标题、次级信息、标签）及可选的底部操作，支持多种信息密度与横/竖布局，支持左滑删除与插槽扩展。

## 4. 组件 API 罗列

- **继承自 PisellBaseCard**：className, style, hoverStyle, activeStyle, disabledStyle, clickable, disabled, onClick。
- **数据与显隐**：media, primaryText, secondaryTexts, tags, actions；showMedia, showPrimaryText, showSecondaryText,
  showTags, showActions（默认见 types）。
- **密度与布局**：density（B1/B2/B5/B9）, layout（horizontal/vertical）。
- **宽度**：width（'content' | 'full' | number）。
- **左滑删除**：swipeToDelete（默认 false）, onDelete。
- **样式扩展**：mediaSize, mediaShape, tagPosition 等（见 types.ts）。
- **插槽**：renderMedia, renderPrimary, renderSecondary, renderTags, renderActions。

## 5. 模块拆解与实现方案

### 5.1 组成与引用

- **PisellBaseCard**：根容器，承载四态与点击。
- **Object Summary 区**：媒体 + 主文案 + 次级文案 + 标签，由密度与 layout 决定排版与行数。
- **Actions 区**：可选底部，根据 actions 配置渲染文本/按钮/icon。
- **左滑删除**：使用 touch/mouse 事件或现有滑动组件（若 utils/materials 有则复用）实现滑动露出删除按钮并触发 onDelete。

### 5.2 结构图

```
PisellEntityCard（根：PisellBaseCard）
├── [左滑层] 滑动容器
│   ├── 内容层（Object Summary + 可选 Actions）
│   │   ├── Object Summary（Horizontal：媒体 | 文案区；Vertical：媒体 在上，文案区 在下）
│   │   │   ├── 媒体区（Avatar/Thumbnail/Icon，可由 renderMedia 覆盖）
│   │   │   ├── 文案区
│   │   │   │   ├── 主文案（可由 renderPrimary 覆盖）
│   │   │   │   ├── 次级文案列表（可由 renderSecondary 覆盖）
│   │   │   │   └── 标签区（可由 renderTags 覆盖）
│   │   │   └── 标签位置可为 inline 或 below
│   │   └── Footer / Actions（可选，可由 renderActions 覆盖）
│   └── 删除层（左滑露出，swipeToDelete 时存在）
└── 宽度由 width 控制（content | full | number）
```

### 5.3 实现要点

- **密度**：B1 仅一行（主文案或媒体+主文案等）；B2 主+次级最多 2 行；B5 次级最多 5 行；B9 全部展示。缺字段则不渲染对应块；超出密度限制的
  secondaryTexts/tags 按数组顺序截断。
- **省略**：同一行优先省略后面字段；文本使用 CSS line-clamp 或单行省略。
- **左滑删除**：手势识别滑动距离，超过阈值露出删除按钮，点击触发 onDelete；支持 touch 与 mouse。
- **样式**：类名带 `pisell-entity-card-` 前缀，不设置 font-family；覆盖 antd 时使用 `pisell-lowcode-xxx`。

## 6. 组件通用性与扩展

- 通过结构化配置适配不同实体类型（人、联系人、搜索结果等）。
- 通过 density/layout 适配列表、选择器、预览等场景。
- 通过插槽支持完全自定义某一块，同时保留默认展示能力。
