AiBubble 对话气泡

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

基础用法

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

基础用法

进阶功能与变体

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

进阶组合

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

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

TIP

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

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

打字特效动画

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

引用来源

多模态渲染 (Multimodal)

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

多模态展示

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

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

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

主题定制 (Theme Overrides)

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

实例级主题覆盖

API

Props

属性名	说明	类型	默认值
`content`	会话文本，支持 Markdown	`string`	`''`
`markdown`	开启 Markdown 和代码高亮解析引擎	`boolean`	`true`
`role`	发送方身份	`'user' \| 'assistant' \| 'system'`	`'assistant'`
`placement`	气泡排列位置	`'start' \| 'end'`	根据 role 自动推断
`shape`	气泡边角形制	`'corner' \| 'round'`	`'round'`
`variant`	气泡视觉变体风格	`'filled' \| 'outlined' \| 'shadow' \| 'borderless'`	`'filled'`
`time`	气泡顶部时间标签	`string`	—
`avatar`	自定义气泡头像地址	`string`	—
`loading`	是否正在输出	`boolean`	`false`
`typing`	显示打字特效动画	`boolean`	`false`
`streaming`	启用流式增量渲染 (逐字/逐句显示)	`boolean`	`false`
`stream-mode`	流式渲染模式	`'word' \| 'sentence' \| 'paragraph'`	`'word'`
`stream-speed`	流式渲染速度 (每次渲染的字符数)	`number`	`1`
`stream-interval`	流式渲染间隔 (ms)	`number`	`20`
`citations`	参考引用列表	`AiCitation[]`	`[]`
`multimodal`	多模态内容 (图片、音频、文件等)	`AiMultimodal[]`	`[]`
`markdown-options`	Markdown 行为与能力配置	`AiMarkdownOptions`	`{}`
`structured-data`	结构化数据 (JSON/表格/思维导图/思路线)	`AiStructuredData`	—
`enable-python-runtime`	是否启用 Python 代码运行支持	`boolean`	`false`
`python-runtime`	Python 运行时类型	`'browser' \| 'remote'`	`'browser'`
`python-api-url`	远程 Python API 地址	`string`	—
`pyodide-url`	Pyodide CDN 地址	`string`	—
`enable-sanitizer`	是否启用内置 XSS 防护	`boolean`	`true`
`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 \| boolean`	`true`
`latex`	是否启用 LaTeX 公式渲染	`AiLatexOptions \| boolean`	`true`
`filePreview`	是否启用内置文件预览	`AiFilePreviewOptions \| boolean`	`true`
`linkify`	是否自动识别链接	`boolean`	`true`
`html`	是否允许 HTML 标签	`boolean`	`false`
`typographer`	是否启用智能排版	`boolean`	`true`
`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 代码运行支持	`boolean`	`false`
`pythonRuntime`	Python 运行时类型	`'browser' \| 'remote'`	`'browser'`
`pythonApiUrl`	远程 Python API 地址	`string`	—
`pyodideUrl`	Pyodide CDN 地址	`string`	见下方说明

XSS 防护 Props

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

Python 沙盒与 XSS 防护示例

浏览器端 Python 运行 (Pyodide)

浏览器端 Python 运行

远程 Python API

XSS 防护示例

XSS 防护

自定义白名单

AiBubbleList 虚拟滚动 (Large List Performance)

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

虚拟滚动 - 性能优化

AiBubbleList Props

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

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-bg`	AI 气泡背景色	`var(--yh-fill-color-light)`
`--yh-ai-bubble-assistant-color`	AI 气泡文字颜色	`var(--yh-text-color-primary)`
`--yh-ai-bubble-border-radius`	气泡圆角大小	`12px`

AiBubble 对话气泡

基础用法

进阶功能与变体

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

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

多模态渲染 (Multimodal)

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

更多示例

自定义头像

自定义头部/尾部插槽

气泡位置控制

系统消息

纯文本模式

完整对话流

JSON 结构化数据

思维链展示

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

在线运行代码：Monaco + WebContainer

主题定制 (Theme Overrides)

API

Props

Events / Callbacks

AiCitation

AiMultimodal

AiMarkdownOptions

AiStructuredData

Slots

Python 沙盒 Props

XSS 防护 Props

Python 沙盒与 XSS 防护示例

浏览器端 Python 运行 (Pyodide)

远程 Python API

XSS 防护示例

自定义白名单

AiBubbleList 虚拟滚动 (Large List Performance)

AiBubbleList Props

AiBubbleList Slots

AiBubbleList Methods

在 Nuxt 中使用

主题变量

AiBubble 对话气泡 ​

基础用法 ​

进阶功能与变体 ​

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

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

多模态渲染 (Multimodal) ​

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

更多示例 ​

自定义头像 ​

自定义头部/尾部插槽 ​

气泡位置控制 ​

系统消息 ​

纯文本模式 ​

完整对话流 ​

JSON 结构化数据 ​

思维链展示 ​

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

在线运行代码：Monaco + WebContainer ​

主题定制 (Theme Overrides) ​

API ​

Props ​

Events / Callbacks ​

AiCitation ​

AiMultimodal ​

AiMarkdownOptions ​

AiStructuredData ​

Slots ​

Python 沙盒 Props ​

XSS 防护 Props ​

Python 沙盒与 XSS 防护示例 ​

浏览器端 Python 运行 (Pyodide) ​

远程 Python API ​

XSS 防护示例 ​

自定义白名单 ​

AiBubbleList 虚拟滚动 (Large List Performance) ​

AiBubbleList Props ​

AiBubbleList Slots ​

AiBubbleList Methods ​

在 Nuxt 中使用 ​

主题变量 ​

AiBubble 对话气泡

基础用法

进阶功能与变体

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

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

多模态渲染 (Multimodal)

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

更多示例

自定义头像

自定义头部/尾部插槽

气泡位置控制

系统消息

纯文本模式

完整对话流

JSON 结构化数据

思维链展示

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

在线运行代码：Monaco + WebContainer

主题定制 (Theme Overrides)

API

Props

Events / Callbacks

AiCitation

AiMultimodal

AiMarkdownOptions

AiStructuredData

Slots

Python 沙盒 Props

XSS 防护 Props

Python 沙盒与 XSS 防护示例

浏览器端 Python 运行 (Pyodide)

远程 Python API

XSS 防护示例

自定义白名单

AiBubbleList 虚拟滚动 (Large List Performance)

AiBubbleList Props

AiBubbleList Slots

AiBubbleList Methods

在 Nuxt 中使用

主题变量