---
nav:
  title: 组件
  order: 1
group:
  title: Data Display
  order: 1
title: PisellEntityCard
order: 1
category: pro
---

# PisellEntityCard 实体卡片

基于 **PisellBaseCard**
的实体展示卡片，用于统一展示「一个实体」的识别信息：媒体区（头像/缩略图/图标）、主文案、副标题、次级信息、标签，以及可选的右侧操作区。支持多种信息密度（B1/B2/B5/B9）、横/竖布局、左滑删除与插槽扩展。

## 设计文档

详见 [设计文档](./pisellEntityCard.$tab-design.md)。

## 何时使用

- 列表项、搜索结果中的实体摘要（人、联系人、客户、商品等）
- 选择器中的选项展示
- 详情页关联实体引用
- 需要左滑删除的列表项

## 代码示例

### 基础用法（横向 B2）

```tsx
import {PisellEntityCard} from '@pisell/materials';

export default function Demo() {
    return (
        <PisellEntityCard
            primaryText="张三"
            subtitleText="+86 138 0000 0000"
            secondaryTexts={[
                {text: '产品经理 · 杭州'},
                {text: '钉钉事业部'},
            ]}
            media={{
                type: 'avatar',
                src: 'https://ui-avatars.com/api/?name=Zhang+San&size=48',
                alt: '头像',
                size: 48,
            }}
            density="B2"
            layout="horizontal"
        />
    );
}
```

### 带操作区与标签

```tsx
import {PisellEntityCard} from '@pisell/materials';
import {EditOutlined} from '@ant-design/icons';

export default function Demo() {
    return (
        <PisellEntityCard
            primaryText="张三"
            secondaryTexts={[{text: '产品经理'}]}
            tags={[{text: '在职'}, {text: '正式'}]}
            media={{type: 'avatar', src: '', alt: '头像', size: 40}}
            showActions
            actions={[
                {type: 'icon', icon: <EditOutlined/>, onClick: () => console.log('编辑')},
                {type: 'text', label: '查看详情', onClick: () => console.log('详情')},
            ]}
        />
    );
}
```

### 竖向布局

```tsx
import {PisellEntityCard} from '@pisell/materials';

export default function Demo() {
    return (
        <PisellEntityCard
            primaryText="实体名称"
            secondaryTexts={[{text: '描述信息'}]}
            media={{
                type: 'avatar',
                src: 'https://ui-avatars.com/api/?name=Entity&size=64',
                alt: '头像',
                size: 64,
            }}
            density="B2"
            layout="vertical"
        />
    );
}
```

### 左滑删除

```tsx
import {PisellEntityCard} from '@pisell/materials';

export default function Demo() {
    return (
        <PisellEntityCard
            primaryText="可删除项"
            secondaryTexts={[{text: '左滑显示删除'}]}
            media={{type: 'avatar', src: '', alt: ''}}
            swipeToDelete
            onDelete={() => console.log('已删除')}
        />
    );
}
```

### 密度 B5 / B9

```tsx
import {PisellEntityCard} from '@pisell/materials';

export default function Demo() {
    return (
        <PisellEntityCard
            primaryText="多行次级"
            secondaryTexts={[
                {text: '第一行'},
                {text: '第二行'},
                {text: '第三行'},
                {text: '第四行'},
                {text: '第五行'},
            ]}
            tags={[{text: '标签1'}, {text: '标签2'}]}
            density="B5"
            layout="horizontal"
        />
    );
}
```

## API

| 属性                 | 说明                 | 类型                            | 默认值          |
|--------------------|--------------------|-------------------------------|--------------|
| media              | 媒体区（头像/缩略图/图标）     | EntityCardMediaConfig         | -            |
| primaryText        | 主文案                | string                        | -            |
| subtitleText       | 副标题（与主标题同行）        | string                        | -            |
| secondaryTexts     | 次级文案列表             | EntityCardSecondaryItem[]     | []           |
| tags               | 标签列表               | EntityCardTagItem[]           | []           |
| actions            | 操作项（需 showActions） | EntityCardActionItem[]        | []           |
| showMedia          | 显示媒体区              | boolean                       | true         |
| showPrimaryText    | 显示主文案              | boolean                       | true         |
| showSubtitle       | 显示副标题              | boolean                       | true         |
| showSecondaryText  | 显示次级文案             | boolean                       | true         |
| showTags           | 显示标签               | boolean                       | true         |
| showActions        | 显示操作区              | boolean                       | false        |
| density            | 信息密度               | 'B1' \| 'B2' \| 'B5' \| 'B9'  | 'B2'         |
| layout             | 布局方向               | 'horizontal' \| 'vertical'    | 'horizontal' |
| width              | 卡片宽度               | 'content' \| 'full' \| number | 'content'    |
| swipeToDelete      | 开启左滑删除             | boolean                       | false        |
| onDelete           | 左滑删除回调             | () => void                    | -            |
| tagPosition        | 标签位置               | 'inline' \| 'below'           | 'below'      |
| contentGap         | 内容间距               | number \| string              | -            |
| primaryLineClamp   | 主文案行数限制            | number                        | -            |
| secondaryLineClamp | 次级文案行数限制           | number                        | -            |

继承自 PisellBaseCard：`className`、`style`、`hoverStyle`、`activeStyle`、`disabledStyle`、`clickable`、`disabled`、`onClick`。

插槽：`renderMedia`、`renderPrimary`、`renderSubtitle`、`renderSecondary`、`renderTags`、`renderActions`。

更多见 [types.ts](../types.ts)。
