# 何时使用

- 对话式 UI 中单条消息展示（用户 / 助手）
- 需要消息列表 + 按角色渲染不同气泡样式
- 不适用：纯列表无对话语义时可用 antd-mobile `List` 等

---

# API

## Bubble（单条）

| 属性            | 类型                                                                 | 是否必传 | 说明 |
| --------------- | -------------------------------------------------------------------- | -------- | ---- |
| role            | `'user' \| 'assistant'`                                              | 是       | 角色 |
| content         | `string`                                                             | 否       | 文本内容 |
| avatar          | `string` \| `React.ReactNode`                                        | 否       | 头像 |
| name            | `string`                                                             | 否       | 名称 |
| loading         | `boolean` \| `React.ReactNode`                                       | 否       | 加载展示 |
| time            | `number` \| `string`                                                 | 否       | 时间 |
| status          | `'success' \| 'error' \| 'pending'`                                  | 否       | 状态（如失败重试） |
| onRefresh       | `() => void`                                                         | 否       | 刷新 / 重试 |
| showHeader      | `boolean`                                                            | 否       | 是否展示头部（头像、名称） |
| header          | `React.ReactNode` \| `((props: BubbleProps) => React.ReactNode)`     | 否       | 头部插槽 |
| footer          | `React.ReactNode` \| `((props: BubbleProps) => React.ReactNode)`     | 否       | 底部插槽 |
| footerPlacement | `'inner' \| 'outside'`                                               | 否       | 底部插槽在气泡内或外 |
| variant         | `'outlined' \| 'filled' \| 'shadow' \| 'borderless'`                 | 否       | 视觉变体 |
| shape           | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`       | 否       | 圆角尾巴方向 |
| className       | `string`                                                             | 否       | |

## Bubble.List

| 属性                 | 类型 | 是否必传 | 说明 |
| -------------------- | ---- | -------- | ---- |
| roles                | `Role[]` | 是   | 角色元数据（与消息 role 对应） |
| messages             | `Message[]` | 是 | 消息数据 |
| fallbackPlaceholder  | `string` \| `React.ReactNode` | 否 | 列表加载占位 |
| loading              | `boolean` | 否 | 列表加载态 |
| children             | `(props: BubbleListPropsItem) => React.ReactNode` | 是 | 渲染每条消息 |
| className            | `string` | 否 | |
| style                | `React.CSSProperties` | 否 | |

### Role / Message

与类型文件一致：`Role` 含 `role`、`avatar`、`name`；`Message` 含 `role`、`content`、`loading`、`time`、`status`、`onRefresh`。

---

# FAQ

- 导出包含 `RoleEnum`、`Bubble`（默认导出与命名导出均可按构建结果使用）。
- 流式输出由业务侧拼字符串传入 `content`，组件本身不负责 SSE。