@pisell/materials 1.8.38 → 1.8.41

package/es/components/pisellEntityCard/PisellEntityCard.less

@@ -0,0 +1,362 @@
+/**
+ * PisellEntityCard 样式
+ * 按 Figma Entity Card 设计：8px 圆角、8px 内边距、Gray/300 边框、标题 14px Semibold、次级 14px Regular #667085、间距 6px/4px、标签 pill
+ */
+/* Figma 设计稿：卡片圆角 8px、边框 #D0D5DD */
+@entity-card-radius: 8px;
+@entity-card-padding: 8px;
+@entity-card-border: 1px solid #d0d5dd;
+@entity-card-bg: #ffffff;
+/* 标题：Text sm/Semibold 14px #000，行高 20 */
+@entity-card-title-size: 14px;
+@entity-card-title-weight: 600;
+@entity-card-title-color: #000000;
+@entity-card-title-line-height: 20px;
+/* 次级：Text sm/Regular 14px #667085，行高 20 */
+@entity-card-secondary-size: 14px;
+@entity-card-secondary-color: #667085;
+@entity-card-secondary-line-height: 20px;
+/* 媒体与文案间距 6px，文案列内间距 4px */
+@entity-card-gap-media-text: 6px;
+@entity-card-gap-text-inner: 0;
+/* 标签：xs/Medium 12px，行高 18，pill 圆角 16px，padding 2px 8px */
+@entity-card-tag-size: 12px;
+@entity-card-tag-line-height: 18px;
+@entity-card-tag-padding: 2px 8px;
+@entity-card-tag-radius: 16px;
+
+.pisell-entity-card-wrap {
+  box-sizing: border-box;
+  min-width: 0;
+
+  &.pisell-entity-card-wrap-swipe {
+    overflow: hidden;
+    border-radius: @entity-card-radius;
+  }
+}
+
+.pisell-entity-card-swipe-container {
+  position: relative;
+  overflow: hidden;
+  border-radius: @entity-card-radius;
+  touch-action: none;
+}
+
+.pisell-entity-card-swipe-delete {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #ff4d4f;
+  color: #fff;
+  font-size: 14px;
+  cursor: pointer;
+  user-select: none;
+  z-index: 0;
+  border-radius: 0 @entity-card-radius @entity-card-radius 0;
+}
+
+.pisell-entity-card-swipe-content {
+  position: relative;
+  z-index: 1;
+  background: inherit;
+  transition: transform 0.2s ease;
+  border-radius: @entity-card-radius;
+}
+
+/* 根节点：布局；Figma 默认 8px 圆角/内边距/边框由组件传入 style 合并 */
+.pisell-entity-card-root {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.pisell-entity-card-summary {
+  display: flex;
+  min-width: 0;
+  flex: 1;
+
+  /* 横向：头像靠上，文案区垂直居中 */
+  &[data-layout='horizontal'] {
+    flex-direction: row;
+    align-items: flex-start;
+  }
+
+  &[data-layout='vertical'] {
+    flex-direction: column;
+    align-items: center;
+  }
+}
+
+.pisell-entity-card-summary[data-layout='horizontal'] .pisell-entity-card-media-wrap {
+  align-self: flex-start;
+}
+
+.pisell-entity-card-summary[data-layout='horizontal'] .pisell-entity-card-text-wrap {
+  align-self: center;
+}
+
+.pisell-entity-card-media-wrap {
+  flex-shrink: 0;
+}
+
+.pisell-entity-card-media {
+  display: block;
+}
+
+.pisell-entity-card-media-avatar {
+  border-radius: 50%;
+}
+
+.pisell-entity-card-text-wrap {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: @entity-card-gap-text-inner;
+  overflow: hidden;
+}
+
+.pisell-entity-card-summary[data-layout='horizontal'] .pisell-entity-card-text-wrap {
+  margin-left: @entity-card-gap-media-text;
+}
+
+.pisell-entity-card-summary[data-layout='vertical'] .pisell-entity-card-text-wrap {
+  margin-top: @entity-card-gap-media-text;
+  align-items: center;
+  text-align: center;
+}
+
+/* 主文案行：标题与副标题同一行时垂直居中对齐；空间不够时副标题与标签整体换行 */
+.pisell-entity-card-primary-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: @entity-card-gap-media-text;
+  min-width: 0;
+}
+
+/* 竖向布局：主标题单独一行，副标题与标签单独一行并居中 */
+.pisell-entity-card-summary[data-layout='vertical'] .pisell-entity-card-primary-row {
+  justify-content: center;
+}
+
+.pisell-entity-card-summary[data-layout='vertical'] .pisell-entity-card-primary-row .pisell-entity-card-primary {
+  flex: 0 0 100%;
+  width: 100%;
+  text-align: center;
+}
+
+.pisell-entity-card-summary[data-layout='vertical'] .pisell-entity-card-primary-row .pisell-entity-card-primary-extra {
+  flex: 0 0 100%;
+  width: 100%;
+  justify-content: center;
+}
+
+/* 副标题与 inline 标签的容器：不压缩，空间不够时整块换行；换行后各自可省略 */
+.pisell-entity-card-primary-extra {
+  flex: 1 0 auto;
+  min-width: min-content;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+  overflow: hidden;
+  max-width: 100%;
+}
+
+/* 主标题：先占内容宽度，不主动压缩，让副标题/标签先换行；仅在极窄时单行省略 */
+.pisell-entity-card-primary {
+  flex: 0 1 auto;
+  min-width: 0;
+  max-width: 100%;
+  overflow: hidden;
+}
+
+/* Figma Title text: 14px Semibold #000, line-height 20；宽度不足时单行省略号 */
+.pisell-entity-card-primary-text {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: @entity-card-title-size;
+  font-weight: @entity-card-title-weight;
+  color: @entity-card-title-color;
+  line-height: @entity-card-title-line-height;
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+
+  /* 有行数限制时：多行截断并省略，覆盖 antd 与默认单行样式；需有宽度约束 line-clamp 才生效 */
+
+  &.pisell-entity-card-primary-text-has-line-clamp {
+    display: -webkit-box !important;
+    -webkit-line-clamp: 1; /* 默认 1 行，2/3 行等由组件 style 覆盖 */
+    -webkit-box-orient: vertical !important;
+    overflow: hidden !important;
+    white-space: normal !important;
+    text-overflow: ellipsis;
+    width: 100%;
+    max-width: 100%;
+    min-width: 0;
+  }
+}
+
+/* 副标题：与主标题/标签同行或换行，宽度不足时单行省略 */
+.pisell-entity-card-subtitle-wrap {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.pisell-entity-card-subtitle {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  display: block;
+  font-size: @entity-card-secondary-size;
+  font-weight: 400;
+  color: @entity-card-secondary-color;
+  line-height: @entity-card-secondary-line-height;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 100%;
+}
+
+.pisell-entity-card-secondary {
+  min-width: 0;
+}
+
+/* Figma Text information: 14px Regular #667085, line-height 20 */
+.pisell-entity-card-secondary-text {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  font-size: @entity-card-secondary-size;
+  font-weight: 400;
+  color: @entity-card-secondary-color;
+  line-height: @entity-card-secondary-line-height;
+}
+
+.pisell-entity-card-secondary-line {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-top: 0;
+  padding-bottom: 0;
+  display: block;
+  line-height: @entity-card-secondary-line-height;
+}
+
+.pisell-entity-card-secondary-tooltip-icon {
+  margin-right: 4px;
+  font-size: 12px;
+  color: @entity-card-secondary-color;
+}
+
+.pisell-entity-card-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: @entity-card-gap-media-text;
+  margin-top: 0;
+  min-width: 0;
+
+  /* inline 标签：可换行，宽度不足时整体收缩、单签可省略 */
+
+  &.pisell-entity-card-tags-inline {
+    flex: 0 1 auto;
+    min-width: 0;
+    overflow: hidden;
+    max-width: 100%;
+  }
+}
+
+/* Figma Badge: 12px Medium, pill 16px radius, padding 2px 8px */
+.pisell-entity-card-tag {
+  display: inline-block;
+  padding: @entity-card-tag-padding;
+  font-size: @entity-card-tag-size;
+  font-weight: 500;
+  line-height: @entity-card-tag-line-height;
+  border-radius: @entity-card-tag-radius;
+  background: #f5f5f5;
+  color: @entity-card-secondary-color;
+
+  /* inline 时单签过长可省略 */
+
+  .pisell-entity-card-tags-inline & {
+    max-width: 100%;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+}
+
+/* 设计稿：卡片内容一行，左侧 summary、右侧 actions（justify-between） */
+.pisell-entity-card-body {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  width: 100%;
+  min-width: 0;
+}
+
+/* Figma 13355-110786：Action 在右侧，与 summary 同一行；操作项支持文本/按钮/图标 */
+.pisell-entity-card-actions {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex-shrink: 0;
+}
+
+.pisell-entity-card-action {
+  padding: 4px 0;
+  border: none;
+  background: transparent;
+  font-size: 14px;
+  color: #475467;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+
+  &:focus-visible {
+    outline: 1px solid #1677ff;
+    outline-offset: 2px;
+  }
+
+  &.pisell-entity-card-action-text {
+    color: #1677ff;
+  }
+
+  &.pisell-entity-card-action-button {
+    padding: 4px 12px;
+    border: 1px solid #d0d5dd;
+    border-radius: 6px;
+    color: #344054;
+    background: #fff;
+
+    &:hover {
+      border-color: #1677ff;
+      color: #1677ff;
+    }
+  }
+
+  &.pisell-entity-card-action-icon {
+    padding: 4px;
+    color: #475467;
+
+    .anticon {
+      font-size: 20px;
+    }
+  }
+}

package/es/components/pisellEntityCard/docs/pisellEntityCard.$tab-design.md

@@ -0,0 +1,209 @@
+---
+title: 设计文档
+order: 2
+category: pro
+---
+
+# 资源链接
+
+## 任务链接
+
+ 
+
+## Figma链接
+
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=13355-110579&m=dev
+Implement this design from Figma.
+@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=13355-110786&m=dev
+
+# 1. 组件概述
+
+| **组件名称（英文）**                                                                                 | Entity Card                                                                                                                          |
+|----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| **组件编号**                                                                                     | pcp\_dd\_entityCard\_V1.0                                                                                                            |
+| **组件类型**                                                                                     | Pro Components                                                                                                                       |
+| **组件分类**                                                                                     | Data Display                                                                                                                         |
+| **<span style="color: rgb(216,57,49); background-color: rgba(254,212,164,0.8)">依赖组件</span>** | 基于[ Base Card](https://m1ed09stz4r.feishu.cn/wiki/A0MHwnavCi3CSek3nX6c3Uw2nCb)封装，在Base Card的基础上确定了内容以及展示的样式                          |
+| **简介**                                                                                       | **Entity Card** 是一个基于 **Base Card** 的中间层组件，用于在界面中**统一展示、识别和理解一个稳定存在的实体（Entity）**。<br />它并不承载具体业务流程，而是为上层 Plus 组件提供**一致、可复用的实体展示骨架**。 |
+
+# 2. 版本
+
+| **版本**   | 1.0  |
+|----------|------|
+| **更新简介** | 首次发布 |
+
+# 3. 组件设计目的
+
+* 建立统一的 **实体信息展示范式**
+
+* 解耦实体展示与具体业务逻辑
+
+* 为多个领域 Plus 组件提供稳定的中间层依赖
+
+* 支持不同信息密度下的实体识别需求
+
+# 4. 适用场景
+
+* 人员 / 联系人 / 用户列表
+
+* 实体搜索结果
+
+* 实体选择器、引用卡片
+
+* 轻量级实体信息预览
+
+# 5. UI 设计
+
+## 5.1 组件结构
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NmM4YTlmZTBjMTVhOWZmOGJhZTAwMzUxYmI5ODIxY2VfN0NxU1BDNUNveVhJTFBPSjdGcEpwWkFzZllxdGZKZ3FfVG9rZW46UDczemI0T1plbzBzeE94Zms5U2N2b08ybnpmXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+* Entity Card
+
+  * Object Summary（实体识别区）
+
+    * Avatar / Thumbnail / Icon
+
+    * &#x20;Primary Text（Name / Title）
+
+    * Secondary Text（Meta / Description）
+
+    * Tags / Badges
+
+  * Optional Footer / Actions
+
+    * View Detail
+
+    * Select / Link
+
+    * Contextual Action
+
+  **Object Summary 是 Entity Card 的核心结构，不可缺省。**
+
+## 5.2 信息密度等级
+
+Entity Card 通过信息密度等级，控制实体在不同场景下的**展示深度**。
+
+> 密度等级仅影响**信息量与布局**，不改变实体语义与职责。
+
+## 5.3 展示样式
+
+组件展示样式分为Horizontal和Vertical
+
+### 5.3.1 B1-Line
+
+* 展示的最小单位，可以为一个标题文本或者图片、头像、缩略图
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=YjFmMzdmZmI4N2QxNjM3NDU0NTVkNzNjZjBjMjJlZWNfY1NRS08zMzF2QnlmbnVJNGRUcThHM0JRNldENElWTEdfVG9rZW46TTNZRmJKTzRjb0VJUnh4OUhIT2NYVnB2bmFlXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+* 一行展示，字段可以并列，但也是最多展示一行信息
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=ZmUwMmQxMDg5MDE4ODM2N2ExNGUyOWNjNzM4OGIwN2VfUjVQT01FVmJLdFoxcXpvVDRkM01ldGNkSVhiWnljQjhfVG9rZW46VHB4cmJVa3BOb0ZkRTd4Nm1PZ2NkRUQ4blBrXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+### 5.3.2 B2-Mini
+
+* 文本信息两行展示，第二行文本字数显示可以为多行
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NmRlMTljMDMyYzEwN2ZiM2RmY2E0NTI4MDQ5NTA2OWNfWWZaWFBPTkpwaTZpTXJwZW5sdjYyTlhpR05lTUdmNGZfVG9rZW46WXdVRWI5d2Fjb0NkTFF4Z3M3M2NlM0Z3bjFjXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+* 当缺少其他信息时，默认不展示
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NmQ1YjlkYjQwMTRkODBmNDY0OGMxMDBjMTk3NzFkMmJfWjNYVEVRbExqM1Z6U3RaT1hiNmprOEVwWEdmMUZiY0lfVG9rZW46S21McmJjUlhDb01hOGR4a1pqT2NmUElEbkpmXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+* 竖向展示
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=ZTlkOTVjYTc1Y2NjODk1ZTg4N2ZhMDg2NDE2NWIzYWFfM1J0cmtLalZybzVERlpZcHhGR1BIZFhUZEhCeDBVUWRfVG9rZW46T2xMZ2JjU1ZXbzBZMkp4YzBnM2NVU3JPbktmXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=OTMxYTE1NWYxM2UwYWZkMWQwOGUzODUxOTllYjM5ZGVfV0JkUjNYblJ2eWVBWm5WVnU1SE1zTU9sbU1FWmh2ZWlfVG9rZW46VlFJbGJnVkplbzZuc2t4T3o2QmN6Vm1ybldiXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+### 5.3.3 B5-Standard
+
+* 文本信息展示最多为5行，超出不显示
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=MzExMTBhMjI0NzY2M2RlYjY2MDE3ZGJkMTQ1Zjc0NWVfSmZZdEE1b1VXTWJSY3ZidWhwUGJaQjJRbGFadHRzTGlfVG9rZW46VTRwWGJ6bXNWbzM2d2Z4VzZoTGN4RHVsbm9jXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+* 竖向展示
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=NzM2Mjc5NGU5NzA1ZGY3YzljY2VjOWRjNWIyZDgyMGFfWHdZWkxTZHNycWVjM1BWdERLY3RFTVl1ZjZmNGY3VlBfVG9rZW46S24yZmJjVGJ3bzNPa1V4MnJlRmNzaHBSbkNjXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+### 5.3.4 B9-Extended
+
+* 所有字段全部显示
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=MGI3NzAzNzBiNGQwZWU5ZmNlYjhiN2QwMDQ3OTVlOTJfSVM5cTNmZUlVTk5TTlNDTlFIVFBFaEJEVGZ4dU9idnVfVG9rZW46TU8xbWJmRzVEb1pVVXp4RzJZZGNHeVMwbktjXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+## 5.4 自适应规则
+
+* 宽度默认为跟随内容撑满，内容文本区域超出时显示省略
+
+* 当字段处于同一行时，优先省略后面的信息，当省略到最后一个字母还不能满足时，全部省略此字段，以此类推
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=OWRhNTc2NWQ5N2JjZWM2Y2M0NGVmODhkNWFmMDQxNmVfc3pjVU5FdWxUckR2ZmhWaHdhNkJLRHJFYWpPckxqblFfVG9rZW46SXpPb2JKY3JKb2FaWUl4OFR6SWNNRVFjbmhDXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=MDE2NmEyODU2NGI4ZTc3MzYwZDA3MDJhY2IzMWM2OGVfb244ZUY2T2ZSQnoyOEtIY25QbkQ5ZnQ0UXZ1Tm9MUHZfVG9rZW46V0VGd2J1aUFCbzJJS0Z4aTZoUGM2aW5XbjFlXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=ZWIxNGVhMmYwOTFhMTYzNTU1NmYyOWNjY2NmYTY0NzdfTzI2RzNwZWVHY1RlandVZFdadzlKNmN2Wlg2aThmVWRfVG9rZW46RjZhQ2J4Sk11b0JpUWJ4WEdRU2NwN1lIbk1nXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+* 竖向放置时内容的排列方式默认为左右居中对齐
+
+## 5.5 **视觉设计规范（需要主题模块完成）**
+
+### 5.5.1 颜色规范
+
+### 5.5.2 尺寸规范
+
+### 5.5.3 间距规范
+
+# 6. 交互准则
+
+* 当信息字段缺少时，不显示，例如选择了B5，但字段只有两个，那跟B2长得一样
+
+* 当字段超出规范时，不展示，例如选择了B2，但是字段有5个，默认只展示排列在前面的两个
+
+# 7. 配置项
+
+## 7.1 样式自定义
+
+* 可以切换选择Horizontal和Vertical
+
+* Card 的背景、圆角、边框、阴影、padding、gap都可以在默认的基础上去的自定义
+
+* 内容的文本，包括标题文本和次级文本信息，可以自定义大小、粗细、颜色、显示行数、宽度
+
+* card的宽度默认为内容撑满也可更改为固定宽度、撑满父容器
+
+* 内容区域的icon可以更改大小、颜色
+
+* 图片、头像、缩略图可以更改大小和圆角
+
+* 可控制自定义标签的展示位置
+
+## 7.2 功能配置
+
+* 可以自定义字段信息的数据源
+
+* 可以对字段进行显隐和排序，默认展示规则为从上往下展示
+
+* 是否显示图片、头像、缩略图，默认显示
+
+* 是否显示主标题文本，默认显示
+
+* 是否显示次级文本信息，默认显示
+
+* 可以手动添加次级文本信息，并可开启提示icon
+
+* 可以控制显隐tag标签，并能添加和自定义样式
+
+* 可以控制是否开启左滑删除，默认关闭
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=YzEzMjNhMzU2Nzc0MmQxMzA3MzgzMDZkNzc3YTViNzhfWFoySWVDVXcxU1NkdTY2OWs2OVZtSEN5QmZSZ2p1ZGdfVG9rZW46RzlXb2JLYWNOb05ndUh4ZkFyMGNyOFFabkNjXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+* 可以控制是否开启Action区域，默认关闭
+
+* 可以控制Action内的操作为文本、按钮、icon，并能各自更改样式
+
+![](https://m1ed09stz4r.feishu.cn/space/api/box/stream/download/asynccode/?code=YjdlOTUxZjM4OTU1ZTc4NTNkNzlkZjUxOWIxMzNhZTVfRmZ6Q2xyYU1IY2drTFA0VElwRFNid0VwQVYzdnF0TkVfVG9rZW46VEVObWJjd2xWb2VadXl4Y29KVWNERWhlbldmXzE3NzI2OTAzOTc6MTc3MjY5Mzk5N19WNA)
+
+* 可开启插槽
+

package/es/components/pisellEntityCard/docs/pisellEntityCard.$tab-dev.md

@@ -0,0 +1,82 @@
+---
+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 适配列表、选择器、预览等场景。
+- 通过插槽支持完全自定义某一块，同时保留默认展示能力。