Skip to content

AiBubble 对话气泡

承载对话消息的冒泡显示。

基础用法

可以展示 userassistant 的样式差异,以及加载动画效果!

人工智能(AI)是一种能够执行通常需要人类智能的任务的技术。

那它能自己写代码吗?

基础用法

进阶功能与变体

AiBubble 直接内置了强大的 Markdown 引擎与 highlight.js 代码高亮解析。并提供了丰富的变体 (variant) 与形制 (shape)、以及时间等信息传递的支持。

10:23 AM

这是一段 Markdown 的渲染示例。来看一段代码:

typescript
const greeting = 'Hello World';
console.log(greeting);

真棒!可以更换样式吗?

当然可以,这是 outlined 模式。

看起来非常有质感。

如果您不喜欢外轮廓,可以使用 borderless 模式。

进阶组合

打字特效与视觉反馈 (Typing & Ripple Effect)

这不仅仅是一个空 loading,它允许文字在一个一个吐出时跟随一个强烈的闪烁光标(类似光标指针的效果),以模仿正在被 AI 书写的感觉。

TIP

增强反馈:当开启 typing 模式时,组件会自动在最后一行附加**“光标闪烁”效果,并伴随背景的“温和波纹”**流光动效,让生成过程更具生命感。

  • 极致性能 (Streaming Performance):在底层我们引入了 requestAnimationFrame 截流刷新机制。当在 typing 模式下接收大量文本包进行 Markdown 复杂频繁重绘时,不仅能防止引发页面主线程卡死,更能将您的打印机的刷新率恒定在舒适的 60 帧每秒!
打字特效动画

引用来源与幻觉标注 (Citations & Reference Tooltip)

AI 回复的信息通常需要来源支撑以避免模型幻觉。除了底部展示详细的长串被引地址,我们在底层注入了智能学术脚注(Citation)解析器。 当且仅当属性 citations 数组有内容时,若大模型在 Markdown 返回内容中包含 [1][2] 这样的结构:气泡将其自动转义拦截拦截为带有交互光效状态的学术悬浮角标! 💡 试一试: 停留在下方的 [1], [2], [3] 等文字段落上悬浮,观察动态出现带有链接及标题的精细化气泡弹出组件。

根据最新的 YH-UI 指南 1,我们建议在处理 AI 对话时使用组合式 API 2。此外,Vite 的构建优化 3 也能显著提升用户体验。

引用来源

多模态渲染 (Multimodal)

组件支持多种媒体格式的直接展示,包括图片网格、带波形动画的语音播放器以及标准化的文件/下载卡片。

设计稿预览 1
设计稿预览 2

这是我为你生成的语音素材和参考文档。

0:02
YH-UI-Requirement.pdf
1.2 MB
多模态展示

高级配置:Markdown & 结构化数据

通过 markdown-optionsstructured-data 以及回调 on-run-code / on-explain-code,你可以让 AiBubble 直接承载更复杂的 Markdown 交互与结构化内容渲染。

这是一段 Markdown 的渲染示例。来看一段代码:

typescript
const greeting = 'Hello World';
console.log(greeting);
指标数值
Tokens256
Latency(ms)120
高级配置:Markdown & 结构化数据

更多示例

自定义头像

通过 avatar 属性或 #avatar 插槽自定义气泡的头像。

你好!我是 AI 助手,有什么可以帮助你的吗?

我想了解如何使用这个组件库。

自定义头像

自定义头部/尾部插槽

使用 #header#footer 插槽自定义气泡的附加信息区域。

● 已送达10:30

这是一个带有自定义头部和尾部的气泡。

自定义头部/尾部

气泡位置控制

通过 placement 属性控制气泡的对齐位置。

左侧气泡(start)

右侧气泡(end)

气泡位置

系统消息

使用 role="system" 展示系统提示或公告信息。

⚠️ 系统提示:当前对话时长已超过 30 分钟,建议保存进度。

有什么我可以帮助你的?

系统消息

纯文本模式

关闭 Markdown 解析,显示纯文本内容。

这是一段纯文本内容,不会被解析为 Markdown。\n\n这里的换行会保留,但不会有**加粗**或代码高亮。
纯文本模式

完整对话流

展示多轮对话的完整效果。

你好!我是 AI 助手,今天有什么我可以帮助你的?

我想学习 Vue 3 的组合式 API。

组合式 API 是 Vue 3 引入的一种新的 API 风格,它允许你更好地组织组件逻辑。

能给我一个例子吗?

当然可以!

vue
<script setup>
import { ref, computed } from "vue"

const count = ref(0)
const doubled = computed(() => count.value * 2)
<\/script>

<template>
  <button @click="count++">Count: {{ count }}</button>
</template>

这就是一个简单的组合式 API 示例。

完整对话流

JSON 结构化数据

展示结构化的 JSON 数据。

以下是查询到的用户数据:

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "管理员",
  "status": "active"
}
JSON 结构化数据

思维链展示

使用 thought-chain 类型展示思考过程。

让我一步步思考这个问题:

理解问题
设计方案
实现代码
测试验证

编写测试用例,验证功能的正确性和稳定性。

思维链

代码块流式输出 (Streaming Code Output)

代码块支持真正的流式输出,执行结果会逐行实时显示,模仿真实终端体验。

特性:

  • 逐行流式显示执行结果
  • 彩色前缀区分不同类型输出(> 运行中、 返回值、 成功、 错误)
  • 支持 WebContainer 和浏览器两种运行环境
js
// 这段代码会流式输出执行结果
console.log('第一行输出');
console.log('第二行输出');
console.log('第三行输出');
return '最终返回值';
代码块流式输出

在线运行代码:Monaco + WebContainer

通过在 markdown-options.codeBlock 中将 runtime 设置为 webcontainer,代码块可以在内置的 WebContainer 沙箱 中运行,并使用内联 Monaco 编辑器进行编辑。

本地开发注意:WebContainer 需要以下条件才能在浏览器中运行:

  • HTTPSlocalhost 环境
  • 服务器响应头必须包含:
    • Cross-Origin-Embedder-Policy: require-corp
    • Cross-Origin-Opener-Policy: same-origin
  • 浏览器支持 SharedArrayBuffer

如果不满足条件,组件会自动降级为浏览器内联执行。

Playground 开发服务器已自动配置上述响应头,可直接测试 WebContainer 功能。

js
console.log('Hello from WebContainer!')
Monaco + WebContainer 运行代码

主题定制 (Theme Overrides)

除了全局 CSS 变量外,您还可以通过 theme-overrides 属性对单个气泡进行精细化的外观定制。

我已经根据您的品牌色调整了我的外观。

实例级主题覆盖

API

Props

属性名说明类型默认值
content会话文本,支持 Markdownstring''
markdown开启 Markdown 和代码高亮解析引擎booleantrue
role发送方身份'user' | 'assistant' | 'system''assistant'
placement气泡排列位置'start' | 'end'根据 role 自动推断
shape气泡边角形制'corner' | 'round''round'
variant气泡视觉变体风格'filled' | 'outlined' | 'shadow' | 'borderless''filled'
time气泡顶部时间标签string
avatar自定义气泡头像地址string
loading是否正在输出booleanfalse
typing显示打字特效动画booleanfalse
streaming启用流式增量渲染 (逐字/逐句显示)booleanfalse
stream-mode流式渲染模式'word' | 'sentence' | 'paragraph''word'
stream-speed流式渲染速度 (每次渲染的字符数)number1
stream-interval流式渲染间隔 (ms)number20
citations参考引用列表AiCitation[][]
multimodal多模态内容 (图片、音频、文件等)AiMultimodal[][]
markdown-optionsMarkdown 行为与能力配置AiMarkdownOptions{}
structured-data结构化数据 (JSON/表格/思维导图/思路线)AiStructuredData
enable-python-runtime是否启用 Python 代码运行支持booleanfalse
python-runtimePython 运行时类型'browser' | 'remote''browser'
python-api-url远程 Python API 地址string
pyodide-urlPyodide CDN 地址string
enable-sanitizer是否启用内置 XSS 防护booleantrue
sanitizer自定义 HTML 清理函数(html: string) => string
allowed-tags允许的标签白名单string[]默认常见安全标签
allowed-attributes允许的属性白名单string[]默认常见安全属性
allowed-schemes允许的协议白名单string[]['http', 'https', 'mailto', 'tel']
theme-overrides主题变量覆盖AiBubbleThemeVars

Events / Callbacks

名称说明类型
on-explain-code代码解释回调(code: string, language: string) => Promise<string>
on-run-code代码运行回调(code: string, language: string) => Promise<{ output: string; error?: string }>
on-citation-click引用项点击回调(citation: AiCitation) => void
on-stream-complete流式渲染完成回调() => void

AiCitation

属性名说明类型
id引用索引,对应文本中的标识string | number
title来源标题string
url详细链接string
source来源站点名称string
icon来源图标string

AiMultimodal

属性名说明类型
type媒体类型'image' | 'audio' | 'file' | 'video'
title标题/文件名string
url资源链接string
size文件大小string
extra额外参数(如语音 duration)Record<string, unknown>

AiMarkdownOptions

属性名说明类型默认值
codeBlock代码块交互能力配置AiCodeBlockOptions{}
mermaid是否启用 Mermaid 图表AiMermaidConfig | booleantrue
latex是否启用 LaTeX 公式渲染AiLatexOptions | booleantrue
filePreview是否启用内置文件预览AiFilePreviewOptions | booleantrue
linkify是否自动识别链接booleantrue
html是否允许 HTML 标签booleanfalse
typographer是否启用智能排版booleantrue
allowedProtocols允许的 URL 协议白名单string[][]

AiStructuredData

属性名说明类型
type数据类型'json' | 'table' | 'chart' | 'mindmap' | 'thought-chain'
data实际数据内容unknown
options渲染配置(图表等可选项)Record<string, unknown>

Slots

插槽名说明参数
default内容自定义
avatar自定义头像
header自定义头部区域
footer自定义尾部区域

Python 沙盒 Props

属性名说明类型默认值
enablePythonRuntime是否启用 Python 代码运行支持booleanfalse
pythonRuntimePython 运行时类型'browser' | 'remote''browser'
pythonApiUrl远程 Python API 地址string
pyodideUrlPyodide CDN 地址string见下方说明

XSS 防护 Props

属性名说明类型默认值
enableSanitizer是否启用内置 XSS 防护booleantrue
sanitizer自定义 HTML 清理函数(html: string) => string
allowedTags允许的标签白名单string[]见下方说明
allowedAttributes允许的属性白名单string[]见下方说明
allowedSchemes允许的协议白名单string[]['http', 'https', 'mailto', 'tel']

Python 沙盒与 XSS 防护示例

浏览器端 Python 运行 (Pyodide)

下面是一段 Python 代码,可以在浏览器中直接运行:

python
# Python 计算示例
result = sum(range(1, 101))
print(f'1 到 100 的累加和: {result}')
浏览器端 Python 运行

远程 Python API

python
# 远程 Python API 执行示例
import math
print(f'圆周率: {math.pi}')
远程 Python API

XSS 防护示例

这是一个包含 危险脚本的内容,但会被自动清理。

XSS 防护

自定义白名单

自定义 白名单 示例 移除非法链接

自定义白名单

AiBubbleList 虚拟滚动 (Large List Performance)

当对话历史极长(如超过 100 条)时,DOM 节点的过多渲染会导致页面滚动卡顿。AiBubbleList 结合了强大的虚拟滚动引擎,即使加载 10,000 条 消息也能保持丝滑的 60fps 滚动体验。

12:00 PM

这是第 1 个用户问题

12:00 PM

这是第 2 个 AI 回复,模拟大数据量下的极致性能表现。

12:00 PM

这是第 3 个用户问题

12:00 PM

这是第 4 个 AI 回复,模拟大数据量下的极致性能表现。

12:00 PM

这是第 5 个用户问题

12:00 PM

这是第 6 个 AI 回复,模拟大数据量下的极致性能表现。

12:00 PM

这是第 7 个用户问题

12:00 PM

这是第 8 个 AI 回复,模拟大数据量下的极致性能表现。

12:00 PM

这是第 9 个用户问题

虚拟滚动 - 性能优化

AiBubbleList Props

属性名说明类型默认值
items会话消息数据列表AiBubbleListItem[][]
virtual-scroll是否开启大屏数据虚拟滚动booleanfalse
height滚动区域容器高度number | string400
item-height列表项的预估高度number80
auto-scroll新增消息自动滚动到底部booleantrue
loading是否处于生成或加载中状态booleanfalse

AiBubbleList Slots

插槽名说明参数
bubble自定义每一项的对话气泡渲染{ item: AiBubbleListItem, index: number }
loading列表底部自定义加载渲染

AiBubbleList Methods

可以使用引用 (ref) 获取组件实例并调用以下方法:

方法名说明参数
scrollToBottom滚动到列表最底部
scrollToIndex虚拟滚动定位到指定的索引(index: number)

在 Nuxt 中使用

该组件完美支持 Nuxt 3/4。在 Nuxt 项目中,组件会被自动按需导入。

有关详细配置,请阅读 Nuxt 集成文档

主题变量

变量名说明默认值
--yh-ai-bubble-user-bg用户气泡背景色var(--yh-color-primary)
--yh-ai-bubble-user-color用户气泡文字颜色var(--yh-color-white)
--yh-ai-bubble-assistant-bgAI 气泡背景色var(--yh-fill-color-light)
--yh-ai-bubble-assistant-colorAI 气泡文字颜色var(--yh-text-color-primary)
--yh-ai-bubble-border-radius气泡圆角大小12px