Skip to content

AiBubble 对话气泡 ​

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

基础用法 ​

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

基础用法

进阶功能与变体 ​

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

进阶组合

打字特效与视觉反馈 (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] 等文字段落上悬浮,观察动态出现带有链接及标题的精细化气泡弹出组件。

引用来源

多模态渲染 (Multimodal) ​

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

多模态展示

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

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

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

更多示例 ​

自定义头像 ​

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

自定义头像

自定义头部/尾部插槽 ​

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

自定义头部/尾部

气泡位置控制 ​

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

气泡位置

系统消息 ​

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

系统消息

纯文本模式 ​

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

纯文本模式

完整对话流 ​

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

完整对话流

JSON 结构化数据 ​

展示结构化的 JSON 数据。

JSON 结构化数据

思维链展示 ​

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

思维链

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

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

特性:

  • 逐行流式显示执行结果
  • 彩色前缀区分不同类型输出(> 运行中、← 返回值、✓ 成功、✗ 错误)
  • 支持 WebContainer 和浏览器两种运行环境
代码块流式输出

在线运行代码:Monaco + WebContainer ​

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

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

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

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

Playground 开发服务器已自动配置上述响应头,可直接测试 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 API ​

远程 Python API

XSS 防护示例 ​

XSS 防护

自定义白名单 ​

自定义白名单

AiBubbleList 虚拟滚动 (Large List Performance) ​

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

虚拟滚动 - 性能优化

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

Released under the MIT License.