游乐游手机版
首页/前端开发/文章详情

TinyRobot AI对话组件库全组件使用教程

时间：2026-06-15 06:57
TinyRobotAI对话组件库包含Bubble、Sender等核心组件，支持气泡渲染、流式输出、消息分组、输入扩展、主题切换，提供丰富CSS变量与可扩展渲染器系统，助力快速构建高度自定义的聊天界面，且易于集成与多端适配，支持多种预设样式与灵活扩展接口。

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

TinyRobot 组件库是开发 AI 对话界面的高效工具。本指南将系统梳理该库的全部组件——从高频使用的 Bubble、Sender，到相对冷门但实用的 DragOverlay、McpServerPicker——帮助开发者快速上手，提升开发效率，减少踩坑。

TinyRobot AI 对话组件库全组件使用指南

一、Bubble 气泡组件 —— 消息的核心渲染容器

构建聊天界面时，Bubble 是必须掌握的基础组件。它负责渲染每一条消息的内容——无论是纯文本、图片、Markdown 格式文本，还是 AI 的推理过程，均由其统一处理。

核心能力

  • 消息展示：支持文本、图片、Markdown 等多种内容类型的一站式渲染
  • 流式输出：content 属性支持响应式数据绑定，动态赋值即可实现类似打字机的流式效果
  • 消息分组：连续发送且角色相同的消息会自动合并，避免消息列表“一条条滚动”的繁琐体验
  • 自定义渲染器：Box 渲染器控制气泡的整体样式与布局，Content 渲染器专注于内容展示，灵活性极高
  • 状态管理：通过 state 属性存储 UI 状态数据，可用于管理点赞、展开/收起等交互

快速上手

这段代码即可生成一个基础的对话气泡。

头像和位置

placement 属性支持 start（靠左）和 end（靠右）两种位置，a vatar 属性则允许传入自定义的 Vue 组件或节点。

气泡形状

通过 shape 属性可以切换气泡的显示风格，共提供三种样式：

  • corner（默认）：经典的聊天气泡样式，带有小尖角
  • rounded：圆角矩形，更符合现代 UI 设计风格
  • none：无圆角，适合追求极简主义的界面

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

content 属性是响应式的。只需动态更新 content 的值，气泡内容便会自动刷新：

Markdown 渲染

如需渲染 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 气泡反馈 —— 让用户与AI回答互动

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 是弹出式的建议列表组件，支持分组数据、自定义渲染、加载状态和移动端适配。