TinyRobot AI对话组件库完整使用指南

TinyRobot 全组件使用指南：打造 AI 聊天界面，一次搞定

从头到尾梳理 TinyRobot 的每个组件——从常用的 Bubble、Sender 到冷门但实用的 DragOverlay、McpServerPicker——帮助你快速上手，减少踩坑，提升效率。

---

一、Bubble 气泡组件 —— 消息展示的核心容器

构建聊天界面时，Bubble 是最基础的组件。它负责渲染每条消息——无论是文字、图片、Markdown 还是 AI 推理过程，都由它统一处理。

核心功能

• 消息展示：支持文本、图片、Markdown 等多种内容类型渲染
• 流式输出：content 支持响应式更新，动态赋值可实现打字机效果
• 消息分组：连续相同角色的消息自动合并，避免界面滚动混乱
• 自定义渲染器：Box 渲染器控制气泡样式布局，Content 渲染器控制内容展示
• 状态管理：通过 state 属性存储 UI 数据，支持点赞、展开收起等交互

快速上手

通过简单配置即可生成消息气泡。

头像与位置设置

placement 支持 start（靠左）和 end（靠右），avatar 支持自定义 Vue 节点或组件。

气泡形状选择

通过 shape 属性设置气泡形状，支持三种风格：

• corner（默认）：经典聊天气泡，带小尖角
• rounded：圆角矩形，现代感较强
• none：无圆角，适合极简风格

流式文本 —— AI 回答打字机效果

content 支持响应式更新，动态赋值即可实现流式输出：

Markdown 渲染配置

需要先安装依赖：

npm install markdown-it dompurify

通过 fallbackContentRenderer 设置 Markdown 渲染器：

渲染器系统 —— 灵活定制内容展示

Bubble 渲染器架构分为两层：

• Box 渲染器：负责气泡外层容器样式与布局
• Content 渲染器：负责气泡内容展示，包括文本、图片、Markdown 等

渲染器通过 find 函数匹配，优先级由 priority 控制，数值越小越优先。内置渲染器包括：

• BubbleRenderers.Text：默认文本渲染
• BubbleRenderers.Markdown：Markdown 渲染
• BubbleRenderers.Image：图片渲染
• BubbleRenderers.Loading：加载状态
• BubbleRenderers.Reasoning：推理内容（AI 思考过程）
• BubbleRenderers.Tool：工具调用

自定义渲染器可通过编写 Vue 组件，使用 markRaw 包装并配置匹配规则实现：

BubbleList —— 消息列表组件

BubbleList 用于批量渲染消息并管理分组：

关键 Props 说明：

属性	说明
messages	消息数组（必填）
groupStrategy	分组策略：consecutive（连续合并）或 divider（按分割角色分组）
roleConfigs	各角色默认配置（头像、位置、形状等）
autoScroll	是否自动滚动到底部

样式定制方法

Bubble 提供丰富的 CSS 变量，涵盖背景色、圆角、字号、阴影等：

:root {
  --tr-bubble-box-bg: #f0f0f0;          /* 气泡背景色 */
  --tr-bubble-text-font-size: 14px;      /* 文字大小 */
  --tr-bubble-box-shape-rounded-radius: 12px; /* 圆角 */
}

---

二、Sender 消息输入框 —— 用户输入的核心工具

Sender 是 TinyRobot 中功能最丰富的组件——一个高度可组合的聊天输入框，支持文本输入、自动联想、@提及、模板填充、语音输入、文件上传等多种交互方式。

输入模式选择

支持 single（单行）和 multiple（多行）两种模式，单行模式下内容超宽时自动切换为多行：

状态控制

加载状态下点击停止按钮会触发 cancel 事件，便于取消 AI 响应。

提交方式设置

三种快捷键方案供选择：

• submitType="enter"：Enter 提交，Ctrl+Enter/Shift+Enter 换行
• submitType="ctrlEnter"：Ctrl+Enter 提交，Enter 换行
• submitType="shiftEnter"：Shift+Enter 提交，Enter 换行

扩展系统 —— Sender 的核心特性

v0.4 的 Sender 通过 extensions prop 实现可插拔功能扩展，所有扩展支持响应式数据自动同步。

模板填充（Template）

import { TrSender } from '@opentiny/tiny-robot'const extensions = [TrSender.template(templates)]
// 或使用标准配置
const extensions = [TrSender.Template.configure({ items: templateData })]

模板数据变化时自动更新编辑器内容，光标自动聚焦到第一个可编辑字段。

提及功能（Mention）

const extensions = [TrSender.mention(mentions, '@')]
// 支持自定义触发字符
const extensions = [TrSender.mention(mentions, '#')]

输入触发字符（默认 @）弹出选择列表，支持键盘导航和搜索过滤。

智能联想（Suggestion）

// 不过滤，直接显示所有建议
const extensions = [TrSender.suggestion(suggestions)]// 自定义过滤
const extensions = [TrSender.suggestion(suggestions, { filterFn: customFilter })]

支持三种高亮模式：自动匹配、精确指定、自定义函数。选中建议项时显示灰色补全提示，按 Tab 一键应用。

语音输入集成

通过独立的 VoiceButton 组件实现：

支持浏览器内置语音识别和第三方语音服务（阿里云、百度等），可自定义录音 UI。

文件上传功能

通过 UploadButton 组件实现：

支持文件类型过滤、大小限制和数量限制。

自定义插槽说明

Sender 提供 header、prefix、footer、footer-right、content、actions-inline 等多个插槽。其中 footer 和 footer-right 插槽提供 editor、hasContent、disabled、loading 等状态数据以及 focus、insert、append、replace 等操作方法，便于功能按钮定制。

字数限制设置

超出限制时红色标示，且无法提交。

样式定制方式

CSS 变量丰富，可调出多种风格：

.my-sender {
  --tr-sender-bg-color: #f5f5f5;
  --tr-sender-text-color: #333;
  --tr-sender-button-size: 40px;
}

---

三、Container 容器 —— 聊天窗口的基础框架

Container 是聊天窗口的“外框”，提供标题栏、内容区域和底部操作栏，支持全屏和窗口两种模式。

全屏模式下自动添加 fullscreen 类名，可通过 .fullscreen 选择器自定义样式。

属性	说明
v-model:show	是否显示容器
v-model:fullscreen	是否全屏
title	容器标题（默认 'OpenTiny NEXT'）

插槽包括 default（主体内容）、title（自定义标题区域）、operations（标题栏右侧操作区）、footer（底部操作栏）。

---

四、Prompts 提示集 —— 引导用户交互的起点

Prompts 用于展示提示列表，常用于聊天界面的欢迎页面，引导用户点击预设问题开始对话。

关键特性：

• 三种尺寸：small、medium（默认）、large
• 徽章：badge 属性为提示项添加角标
• 纵向展示：vertical 属性切换为垂直排列
• 自动换行：wrap 属性让提示项超出宽度时自动折行
• 响应式布局：配合 wrap + item-style 实现自适应
• 禁用状态：disabled 属性灰掉提示项

---

五、Welcome 欢迎组件 —— 聊天界面的初始印象

Welcome 组件展示欢迎信息，包含标题、描述和图标，常用于新对话的起始页面。

align 支持 left、center（默认）、right 三种对齐方式。icon 支持自定义 Vue 节点或 JSX。footer 插槽用于放置提示列表等内容。

---

六、Attachments 附件卡片 —— 文件交互支持

Attachments 组件展示文件列表，支持图片预览、文件下载、状态显示，让聊天界面具备文件处理能力。

展示形式

• auto（默认）：自动检测——全是图片则使用图片墙，否则使用文件卡片
• picture：强制图片墙
• card：强制文件卡片

文件状态

• success：上传成功，显示文件大小等元信息
• uploading：上传中，显示加载动画
• error：上传失败，显示错误信息和“重试”按钮

自定义操作按钮

const actions = [
  { type: 'preview', label: '预览' },
  { type: 'download', label: '下载' },
  { type: 'custom', label: '分享', handler: (file) => shareFile(file) }
]

内置 7 种文件类型识别（image、pdf、word、excel、ppt、folder、other），可通过 fileMatchers 扩展自定义类型，通过 fileIcons 替换默认图标。

---

七、Feedback 气泡反馈 —— 增强用户交互体验

Feedback 组件附加在消息气泡下方，提供操作按钮、动作按钮和数据来源，让 AI 回答具备交互能力。

内置支持的 action 图标：copy、refresh、like、dislike。也可传入自定义图标。

使用 operationsLimit、actionsLimit、sourcesLinesLimit 控制默认显示数量，超出部分自动折叠。

---

八、History 历史记录 —— 对话追溯功能

History 组件展示对话历史列表，支持分组、重命名、删除、自定义菜单项等操作。

数据支持两种格式：

• 直接数组：HistoryItem[]
• 分组数组：HistoryGroup[]

// 分组格式
const historyData = [
  { group: '今天', items: [{ id: '1', title: '帮我写代码' }] },
  { group: '昨天', items: [{ id: '2', title: '翻译文档' }] }
]

支持自定义菜单项（默认提供重命名和删除），提供 item-prefix 和 item-title 两个插槽用于自定义显示。

---

九、SuggestionPills 建议按钮组 —— 横向快捷建议

SuggestionPills 是一个横向排列的建议按钮组，适合在输入框上方或聊天界面的快捷操作区域使用。

关键特性：

• overflowMode：多余项的处理方式——expand（展开显示）或 scroll（横向滚动）
• showAllButtonOn：显示“更多”按钮的时机——hover（默认）或 always
• 每个药丸项必须包含 text 或 icon 至少一个

---

十、SuggestionPopover 建议弹出框 —— 弹出式建议列表

SuggestionPopover 是弹出式的建议列表组件，支持分组数据、自定义渲染、加载状态和移动端适配。

触发方式支持 click（点击触发）和 manual（手动控制显示状态）。

数据支持普通项和分组项两种格式，分组项添加 group 字段即可。提供 trigger、item、loading、empty、header、body 六个插槽，灵活度较高。

---

十一、DropdownMenu 下拉菜单 —— 轻量级菜单组件

DropdownMenu 是一个轻量级下拉菜单组件，主要用于 SuggestionPills 的“更多”操作。

支持三种触发方式：click、hover、manual。show 属性在 click/hover 模式下支持双向绑定，manual 模式下仅单向绑定。

---

十二、DragOverlay 拖拽浮层 —— 文件拖入视觉提示

DragOverlay 提供拖拽上传的视觉反馈，由 v-dropzone 指令和 组件协同工作。

支持自定义浮层内容（通过 overlay 插槽）、全屏模式、禁用状态。文件被拒绝时会触发 onError，提示具体原因（文件类型不符、超大小、超数量等）。

---

十三、Theme 主题 —— 一键换肤与暗黑模式

ThemeProvider 是主题管理组件，通过 CSS 变量实现主题和暗黑/亮色模式切换。

颜色模式

• light：亮色
• dark：暗色
• auto（默认）：跟随系统

自定义主题 CSS

[data-tr-theme='custom-theme'][data-tr-color-mode='dark'] {
  --tr-bubble-box-bg: #2a2a2a;
  --tr-sender-bg-color: #1e1e1e;
}

useTheme 组合式函数

const { toggleColorMode, setColorMode, setTheme } = useTheme()
toggleColorMode()  // 切换亮/暗
setColorMode('dark')  // 设置暗色模式
setTheme('custom-theme')  // 切换自定义主题

支持嵌套主题、主题数据持久化（通过 storage 和 storageKey 属性），刷新页面自动恢复。

---

十四、SenderCompat —— v0.3 升级过渡组件

从 v0.3.x 升级的用户可使用 SenderCompat 作为过渡桥梁——保留大部分 v0.3 的 API，底层基于 v0.4 实现，改动最小。

// 只需修改一行导入
import { TrSenderCompat as TrSender } from '@opentiny/tiny-robot'

需要处理的 5 个破坏性变更：

1. 紧凑模式：class="tr-sender-compact" → size="small"
2. 装饰内容插槽：#decorativeContent → #content + disabled
3. 模板数据设置：新增 setTemplateData() 便捷方法
4. 插槽名变更：#actions → #actions-inline，#footer-left → #footer
5. 移除不必要的 key 绑定

最终迁移路径：v0.3 Sender → SenderCompat → v0.4 Sender

---

十五、McpAddForm 插件添加表单 —— MCP 插件入口

McpAddForm 是添加 MCP 插件的表单组件，支持表单添加和代码添加两种方式。

表单数据结构：

interface McpAddFormData {
  name: string
  description: string
  type: 'sse' | 'streamableHttp'
  url: string
  headers: string
  thumbnail: File | null
}

addType 支持 form（表单模式）和 code（代码模式），两种方式可自由切换。

---

十六、McpServerPicker 插件选择器 —— MCP 插件管理中心

McpServerPicker 是 MCP 插件的全生命周期管理组件，支持已安装插件和市场插件两个标签页。

核心功能

• 双标签页：已安装插件 + 市场插件
• 搜索和分类筛选：内置搜索框，市场支持分类筛选
• 插件状态管理：启用/禁用插件和工具
• 添加状态控制：idle（未添加）→ loading（添加中）→ added（已添加）
• 两种弹出方式：fixed（固定定位）和 drawer（抽屉），通过 popupConfig 配置

// 添加状态控制示例
const handlePluginAdd = (plugin) => {
  targetPlugin.addState = 'loading'  // 显示添加中
  addPluginToServer(plugin)
    .then(() => { targetPlugin.addState = 'added' })
    .catch(() => { targetPlugin.addState = 'idle' })  // 失败重置
}

---

完整组合示例：构建全功能聊天界面

将所有组件组合，构建完整的 AI 聊天界面：

---

总结

TinyRobot 的 16 个组件，从消息展示（Bubble）到用户输入（Sender），从窗口容器（Container）到主题管理（Theme），从文件处理（Attachments、DragOverlay）到 MCP 插件管理（McpServerPicker、McpAddForm），覆盖了 AI 聊天界面的主要功能场景。

组件速查表：

组件	定位
Bubble / BubbleList	消息气泡与列表
Sender	消息输入框（含扩展系统）
SenderCompat	v0.3 升级过渡组件
Container	聊天窗口容器
Prompts	提示集（预设问题列表）
Welcome	欢迎信息展示
Attachments	附件卡片（文件/图片列表）
Feedback	消息反馈（点赞、复制、来源）
History	对话历史记录
SuggestionPills	横向建议按钮组
SuggestionPopover	弹出式建议列表
DropdownMenu	下拉菜单
DragOverlay	拖拽上传浮层
ThemeProvider / useTheme	主题与暗黑模式
McpAddForm	MCP 插件添加表单
McpServerPicker	MCP 插件选择器

使用这套组件库，一个完整的 AI 聊天界面从开发到上线，所需时间可能比泡一杯咖啡还短（调试除外）。