介绍

第一阶段优化说明

AiBubbleListProps 已覆盖封装层新增的 messages、list、triggerIndices、autoScroll、maxHeight 和 showBackButton，并继续兼容底层 BubbleListProps。

import type {
  AiBubbleListExpose,
  AiBubbleListProps,
  AiBubbleListSlotContext,
} from '@zhiyongui/lingxi-ui'

BubbleList 基于 Bubble 组件，用于展示一组对话气泡列表。内置虚拟滚动（virtua/vue）、自动追底、滚动状态机、未读计数、双向分页加载、回底按钮和混合节点渲染，开箱即用，按需配置。

代码演示

基础使用

滚动控制方法

自动触底控制

返回底部按钮

流式跟随

模拟真实 SSE（全量累计）复现自动触底失效

极端场景：动态插槽高度与自动触底压力测试

双向分页加载

混合节点

插槽自定义

自定义主题

通过 ConfigProvider.themeOverrides 覆盖 BubbleList 的主题变量。完整变量表与可复制模板见：

• 主题变量总表
• /theme-overrides.template.ts

与 x-markdown-vue 结合使用

从 v2.0.0 开始，组件库不再内置 XMarkdown / XMarkdownAsync。如需 Markdown 渲染，请使用独立包 x-markdown-vue，或查看专属文档：XMarkdown。

安装

npm install x-markdown-vue
npm install katex
npm install shiki shiki-stream

TIP

如果需要代码块语法高亮功能，请安装 shiki 和 shiki-stream。否则控制台可能会报错：Streaming highlighter initialization failed: Error: Failed to load shiki-stream module

基础用法

雾化效果

API 标准表

Props

属性	类型	默认值	说明
messages	AiChatMessage[]	[]	简化的 user/assistant 消息列表。
list	BubbleListItemProps[]	undefined	底层 BubbleList 原生列表数据，优先级高于 messages。
autoScroll	boolean	true	新消息到达时是否自动滚动到底部。
maxHeight	string	'100%'	列表最大高度。
showBackButton	boolean	true	是否显示回到底部按钮。
triggerIndices	'only-last' | 'all' | number[]	'only-last'	控制哪些消息触发 complete。

Events

事件	参数	说明
complete	instance, index	指定气泡打字完成。
scrollStateChange	state	滚动状态变化。
unreadCountChange	count: number	未读数变化。
loadMoreTop	-	请求加载更早消息。
loadMoreBottom	-	请求加载更晚消息。

Slots

插槽	参数	说明
avatar / header / content / footer / loading	{ item }	定制单条消息局部内容。
backToBottom	{}	自定义回到底部按钮。
topStatus / bottomStatus / item	Record<string, unknown>	自定义边界状态或非气泡项。

Exposes

方法	参数	说明
scrollToTop()	-	滚动到顶部。
scrollToBottom()	-	滚动到底部。
scrollToBubble(index)	number	滚动到指定消息。

样式入口

import '@zhiyongui/lingxi-ui/ai-bubble-list/style.css'

FAQ

messages 和 list 应该选哪个？

普通聊天数据用 messages；需要完整控制底层气泡属性时用 list。