Bubble 气泡组件

Bubble 气泡组件用于展示消息气泡，支持流式文本、头像、位置、加载中、终止状态、操作按钮等功能。

代码示例

基本示例

基本示例。使用 content 属性设置气泡内容，使用 css 变量 --tr-bubble-content-bg 设置气泡内容背景颜色。

更多 css 变量请参考 CSS 变量

头像和位置

通过 avatar 设置自定义头像，通过 placement 设置位置，提供了 start、end 两个选项

气泡形状

通过 shape 设置气泡形状。目前提供了 rounded 和 corner 两个选项。默认为 corner

加载中

通过 loading 设置加载中状态。或者使用 loading 插槽来实现自定义加载中状态

BubbleList 除了需要设置 loading，还需要设置 loading-role。需要注意的是，列表的加载中气泡实际上并没有新增一条消息，loading 设置为 false 后，加载中的气泡不会渲染

用户停止

通过 aborted 设置用户停止状态

最大宽度

通过 maxWidth 设置气泡最大宽度

渲染 markdown

流式文本

content 属性是响应式的，动态设置 content 即可实现流式文本

多种消息格式

BubbleProvider 管理和注册消息渲染器。渲染器注册机制

当 Bubble 组件的 content 是长度大于0的数组时，系统会：

1.检查每数组项的 type 字段
2.在 BubbleProvider 中查找匹配的渲染器
3.使用找到的渲染器渲染消息内容
4.如果未找到匹配的渲染器，则使用默认渲染方式

有三种方式可以实现自定义消息渲染器：

1.函数式渲染器：

typescript

const myRenderer: BubbleContentFunctionRenderer = (options) => {
  return h('div', options.content)
}

2.类式渲染器：

必须继承 BubbleContentClassRenderer 类

类渲染器通常用来复用复杂度较高的渲染器，比如MarkdownIt实例

typescript

class MyRenderer extends BubbleContentClassRenderer {
  render(options) {
    return h('div', options.content)
  }
}

注册时记得 new 一个实例，否则会导致渲染失败

vue

<template>
  <tr-bubble-provider :content-renderers="contentRenderers">
    <!-- other codes... -->
  </tr-bubble-provider>
</template>

<script>
const contentRenderers = { 'my-render': new MyRenderer() }
</script>

3.Vue 组件：

content 对象中的所有属性都将传递给组件，onXXX会当作事件传递给组件，非props属性会当作attrs传递给组件

vue

<template>
  <div>{{ props.content }}</div>
</template>

目前内置直接可用的的渲染器类型有

text(默认渲染器)
collapsible-text
tool

内置需要自行导入的渲染有

BubbleMarkdownContentRenderer 类渲染器

指定渲染属性

和大模型交互数据时，交互的原始数据中的 content 字段可能需要经过前端二次处理再展示到UI上，但此时我们又不想改动原始的 content 字段。此时可以通过 customContentField 属性来在前端指定你需要渲染的属性

插槽

气泡组件提供了四个插槽，分别是默认插槽, loading 插槽、footer 插槽和 trailer 插槽

schema 卡片渲染

列表

隐藏角色

角色配置中使用 hidden 来隐藏这个角色的所有消息

API

BubblePlacement

气泡位置类型：

typescript

type BubblePlacement = 'start' | 'end'

'start': 气泡位于左侧/起始位置
'end': 气泡位于右侧/结束位置

BubbleCommonProps

气泡通用属性配置。

属性	类型	默认值	说明
`placement`	`BubblePlacement`	-	气泡对齐位置 (`'start'` 或 `'end'`)
`avatar`	`VNode`	-	气泡头像部分的自定义 Vue 节点
`shape`	`'rounded' \| 'corner'`	`'corner'`	气泡形状
`contentRenderer`	`BubbleContentRenderer`	-	气泡内容渲染器（当 content 是非空数组时无效，使用 BubbleProvider 注册的渲染器）
`customContentField`	`string`	-	自定义气泡内容字段。比如 customContentField 设置为 'my-content'，则 Bubble 优先渲染 my-content 属性到气泡内容
`abortedText`	`string`	-	气泡中止文本
`maxWidth`	`string \| number`	`'（用户停止）'`	气泡内容的最大宽度

BubbleProps

单个气泡的属性配置（继承自 BubbleCommonProps）。

属性	类型	默认值	说明
`content`	`string \| BubbleContentItem[]`	-	气泡内容
`id`	`string \| number \| symbol`	-	气泡唯一标识
`role`	`string`	-	气泡角色标识，用于关联 `roles` 配置
`loading`	`boolean`	`false`	是否显示加载状态
`aborted`	`boolean`	`false`	是否显示为已中止状态

BubbleSlots

气泡组件的插槽定义。

插槽名	参数	说明
`default`	`{ bubbleProps: BubbleProps; index?: number }`	默认内容插槽，用于自定义气泡内容
`footer`	`{ bubbleProps: BubbleProps; index?: number }`	底部插槽，用于在气泡底部添加内容
`loading`	`{ bubbleProps: BubbleProps; index?: number }`	加载状态插槽，用于自定义加载状态显示
`trailer`	`{ bubbleProps: BubbleProps; index?: number }`	尾部插槽，用于在气泡内容外部添加内容

BubbleRoleConfig

角色配置类型（继承自 BubbleCommonProps）。

type BubbleRoleConfig = BubbleCommonProps & {
  hidden?: boolean
  slots?: BubbleSlots
}

BubbleListProps

气泡列表组件的属性配置。

属性	类型	默认值	说明
`items`	`(BubbleProps & { slots?: BubbleSlots })[]`	-	必填，气泡项数组
`roles`	`Record<string, BubbleRoleConfig>`	-	每个角色的默认配置项
`loading`	`boolean`	`false`	列表是否加载中
`loadingRole`	`string`	-	指定哪个角色可以有加载中状态
`autoScroll`	`boolean`	`false`	是否自动滚动到最新内容

BubbleProviderProps

type BubbleProviderProps = {
  contentRenderers?: Record<string, BubbleContentRenderer>
}

BubbleContentItem

单条消息对象的结构。

typescript

interface BubbleContentItem {
  type: string
  [key: string]: any
}

属性	类型	说明
`type`	`string`	消息类型，用于选择对应的渲染器
`[key: string]`	`any`	其他字段可自由扩展，用于携带消息所需的自定义数据

BubbleContentRenderer

用于渲染气泡消息内容的渲染器类型。

typescript

type BubbleContentRenderer = BubbleContentFunctionRenderer | BubbleContentClassRenderer | Component

BubbleContentFunctionRenderer: 函数式渲染器，返回 VNode
BubbleContentClassRenderer: 基于类的渲染器，需实现 .render() 方法
Component: 任意 Vue 组件，也可以用作渲染器

BubbleContentFunctionRenderer

函数式消息渲染器：

typescript

type BubbleContentFunctionRenderer = (options: { [key: string]: any }) => VNode

参数	类型	说明
`options`	`{ [key: string]: any }`	与消息类型 (`BubbleContentItem`) 对应的数据
返回值	`VNode`	渲染结果

BubbleContentClassRenderer

基于类的消息渲染器：

typescript

abstract class BubbleContentClassRenderer {
  abstract render(options: { [key: string]: any }): VNode
}

CSS 变量

Bubble 组件变量

Bubble 根元素

变量名	说明
`--tr-bubble-gap`	头像与内容间距
`--tr-bubble-max-width`	气泡最大宽度

avatar 头像

变量名	说明
`--tr-bubble-avatar-size`	头像尺寸

content 内容

变量名	说明
`--tr-bubble-content-bg`	内容背景色
`--tr-bubble-content-border-radius`	内容圆角大小
`--tr-bubble-content-box-shadow`	内容阴影效果
`--tr-bubble-content-padding`	内容内边距
`--tr-bubble-content-border`	内容边框样式
`--tr-bubble-content-items-gap`	内容项之间的间距（仅当 `content` 属性是数组时有效）

text 文本（仅当 content 属性是字符串时有效）

变量名	说明
`--tr-bubble-text-color`	文本文字颜色
`--tr-bubble-text-font-size`	文本字号
`--tr-bubble-text-line-height`	文本行高

loading 加载

变量名	说明
`--tr-bubble-loading-size`	加载图标尺寸

aborted 中止状态

变量名	说明
`--tr-bubble-aborted-color`	中止文字颜色
`--tr-bubble-aborted-font-size`	中止文字字号

footer 底部

变量名	说明
`--tr-bubble-footer-margin`	底部外边距

BubbleList 容器变量

变量名	说明
`--tr-bubble-list-gap`	气泡项之间的间距
`--tr-bubble-list-padding`	容器内边距

Bubble 气泡组件 ​

代码示例 ​

基本示例 ​

头像和位置 ​

气泡形状 ​

加载中 ​

用户停止 ​

最大宽度 ​

渲染 markdown ​

流式文本 ​

多种消息格式 ​

指定渲染属性 ​

插槽 ​

schema 卡片渲染 ​

列表 ​

隐藏角色 ​

API ​

BubblePlacement ​

BubbleCommonProps ​

BubbleProps ​

BubbleSlots ​

BubbleRoleConfig ​

BubbleListProps ​

BubbleProviderProps ​

BubbleContentItem ​

BubbleContentRenderer ​

BubbleContentFunctionRenderer ​

BubbleContentClassRenderer ​

CSS 变量 ​

Bubble 组件变量 ​

BubbleList 容器变量 ​

Bubble 气泡组件

代码示例

基本示例

头像和位置

气泡形状

加载中

用户停止

最大宽度

渲染 markdown

流式文本

多种消息格式

指定渲染属性

插槽

schema 卡片渲染

列表

隐藏角色

API

BubblePlacement

BubbleCommonProps

BubbleProps

BubbleSlots

BubbleRoleConfig

BubbleListProps

BubbleProviderProps

BubbleContentItem

BubbleContentRenderer

BubbleContentFunctionRenderer

BubbleContentClassRenderer

CSS 变量

Bubble 组件变量

BubbleList 容器变量