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

# PisellContactBrief 开发文档

## 1. 基础信息

- **组件名称**：PisellContactBrief（Contact Info）
- **组件版本**：1.0
- **组件分类**：Data Display / Plus 类展示组件
- **依赖**：基于 PisellEntityCard 封装；新建/编辑弹窗内部实现。

## 2. 需求点罗列

1. **联系人展示**：基于 Entity Card，展示头像（无则占位）、姓名（主文案）、电话（副标题同行）、邮箱及扩展字段（次级文案），右侧编辑图标点击调起编辑弹窗。
2. **CreateButton**：独立导出 `PisellContactBrief.CreateButton`，点击后打开新建联系人弹窗，保存后由调用方更新数据并展示新联系人。
3. **新建/编辑弹窗**：组件内部实现；表单含姓名、电话、邮箱 + 可配置扩展字段（key/label）；支持取消、保存；提交回调 `onSubmit`
   回传表单值。
4. **可增加字段**：扩展字段由 props 配置（如 `extraFields: { key, label }[]`），卡片展示顺序与弹窗表单项顺序一致。
5. **左滑删除**：复用 PisellEntityCard 的 swipeToDelete / onDelete，无额外实现。
6. **多语言**：使用 `locales.getText(key)`，提供中、英、繁文案（组件内 locales 文件，由业务 init 或组件内 init）。
7. **布局与换行**：支持 horizontal/vertical；宽度不足时文本换行，与右侧保持 8px 间距。
8. **文本过长**：按配置省略（主文案/次级文案行数限制）。

## 3. 组件描述

PisellContactBrief 是基于 PisellEntityCard
的联系人简要信息展示组件，用于客户详情、表单选择、沟通模块等场景。提供联系人卡片（内置编辑入口）与“新建联系人”按钮（CreateButton），新建/编辑弹窗在组件内部实现，表单包含基础字段与可配置扩展字段。

## 4. 组件 API 罗列

### 4.1 PisellContactBrief（卡片）

- **数据**：`name`, `phone`, `email`, `avatar`（可选）, `extraData`（扩展字段 key-value，与 extraFields 配置对应）。
- **扩展字段配置**：`extraFields?: { key: string; label: string }[]`，顺序即展示与表单顺序。
- **弹窗回调**：`onSubmit?: (values: ContactFormValues) => void`（编辑时提交）, `onDelete?: () => void`（左滑删除时）。
- **显隐**：`showAvatar`, `showPhone`, `showEmail` 等（缺省按有值则展示）。
- **布局**：`layout?: 'horizontal' | 'vertical'`，透传 Entity Card。
- **左滑删除**：`swipeToDelete?: boolean`, `onDelete?: () => void`，透传 Entity Card。
- **样式**：继承 BaseCard 的 className, style 等；主/次级行数限制 `primaryLineClamp`, `secondaryLineClamp`。
- **多语言**：文案通过 locales.getText 获取，键名见 locales 文件。

### 4.2 PisellContactBrief.CreateButton（新建入口）

- **点击**：`onClick` 打开新建弹窗（或 `onClick?: () => void` 由调用方自行打开弹窗时，则仅渲染按钮不内置弹窗；此处采用内置弹窗方案）。
- **新建提交**：弹窗内提交后触发 `onCreate?: (values: ContactFormValues) => void`，调用方保存数据后可将新联系人加入列表。
- **扩展字段**：与卡片一致，通过 `extraFields` 传入，弹窗内表单项与之一致。
- **样式**：`className`, `style`；展示“Add Contact”+ 占位头像 + plus 图标（与设计稿一致）。

### 4.3 新建/编辑弹窗（内部）

- **标题**：新建 / 编辑，由 getText 获取。
- **表单**：姓名、电话、邮箱 + extraFields 中每项的 input。
- **按钮**：取消、保存（编辑时可选删除，或删除由左滑暴露，弹窗内仅取消/保存）。
- **受控**：visible 由内部 state 控制；CreateButton 点击设为 true，关闭设为 false；卡片编辑点击同理。

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

### 5.1 组成与引用

- **PisellEntityCard**：直接复用，将 contact 数据映射为
  media、primaryText、subtitleText、secondaryTexts；右侧操作区渲染编辑图标，点击打开编辑弹窗。
- **PisellContactBrief**：负责数据映射、编辑弹窗 state、弹窗表单与提交/取消逻辑；左滑删除透传 Entity Card。
- **CreateButton**：占位头像 + “Add Contact” 文案 + plus 图标，点击打开新建弹窗；弹窗表单与编辑弹窗共用组件。
- **ContactFormModal**：内部子组件，表单含 name、phone、email + extraFields；提交触发 onCreate（新建）或 onSubmit（编辑），取消关闭弹窗。

### 5.2 结构图

```
PisellContactBrief（根：PisellEntityCard）
├── 数据映射：name → primaryText, phone → subtitleText, email + extraData → secondaryTexts
├── 媒体区：avatar 或默认占位
├── 右侧操作：编辑图标 → 打开 ContactFormModal（mode=edit）
└── 左滑删除：swipeToDelete / onDelete 透传 Entity Card

PisellContactBrief.CreateButton
├── 占位 Avatar + 文案 "Add Contact" + plus 图标
└── 点击 → 打开 ContactFormModal（mode=create）→ onCreate(values)

ContactFormModal（内部）
├── Modal 标题：新建 / 编辑（getText）
├── Form：name, phone, email + extraFields 动态表单项
└── 取消 / 保存（+ 可选删除，若需要）
```

### 5.3 实现要点

- **数据映射**：contact.name → primaryText；contact.phone → subtitleText；contact.email + extraFields 顺序映射 extraData 到
  secondaryTexts。
- **无头像**：Entity Card media 使用默认占位 Avatar（src 不传即可）。
- **弹窗复用**：新建与编辑共用 ContactFormModal，通过 mode 区分标题与提交回调（onCreate vs onSubmit）。
- **扩展字段**：extraFields 遍历生成 Form.Item 与 secondaryTexts 项，key 与 extraData[key] 对应。
- **多语言**：组件内维护 locales 文件（中/英/繁），键如 `pisell.contact.brief.addContact`、`pisell.contact.brief.edit`、
  `pisell.contact.brief.modal.title.create`、`pisell.contact.brief.modal.title.edit`、`pisell.contact.brief.modal.cancel`、
  `pisell.contact.brief.modal.save`、`pisell.contact.brief.delete` 等；使用 `locales.getText(key)`。Entity Card
  若需多语言（如“删除”按钮文案），在 Entity Card 侧补充 locales 或由调用方通过 props 传入文案。
- **样式**：类名前缀 `pisell-contact-brief-`；换行与 8px 间距由布局与 padding 保证。

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

- 通过 extraFields + extraData 适配不同业务的可增加字段，无需改组件结构。
- 通过 layout、行数限制适配列表与详情等不同布局。
- 新建/编辑逻辑内聚，调用方只需提供 onCreate/onSubmit 与数据源。
