30 分钟接入 Vue 聊天机器人界面：vue-bot-ui 实战笔记

30 分钟接入 Vue 聊天机器人界面：vue-bot-ui 实战笔记

【免费下载链接】vue-bot-uiFor the one who is finding a customizable chatbot UI.项目地址: https://gitcode.com/gh_mirrors/vu/vue-bot-ui

接到"给网站加一个在线客服机器人"的需求时，很多 Vue 开发者第一反应是打开组件库找现成组件，结果发现 Element、Vuetify 里根本没有聊天窗口这种东西。vue-bot-ui 正是为解决这个空白而生的：一个开箱即用的 Vue 2 聊天机器人界面组件，消息气泡、输入框、按钮选项、"正在输入"动画全部替你做好，你要做的只是往里灌数据、把用户消息转发给你的机器人接口。

这篇文章按我实际接入的顺序记录，从零到能跑通一轮对话，全程读完约 30 分钟。

为什么我放弃手写聊天窗口，改用现成组件

网上不乏手搓聊天界面的教程，但我评估之后放弃了，原因很实在：

• 动画和过渡：气泡弹出、面板开关、输入按钮切换这些微交互，手写要花大量时间调试
• 消息滚动：新消息到达自动滚到底部，看似简单，自己做总是差一口气
• "正在输入"指示器：这个小细节决定对话的真实感，组件里已经内置
• 按钮选项消息：postback（发给接口）和url（打开链接）两种交互，手写还得处理事件冒泡

一句话总结：业务逻辑才是我们的核心价值，界面细节交给组件。

第一步：安装并注册组件

如果你用 npm：

npm install vue-bot-ui

用 yarn 则执行：

yarn add vue-bot-ui

然后在组件里引入并注册：

import { VueBotUI } from 'vue-bot-ui' export default { components: { VueBotUI } }

这一步没有任何坑，装完就能在模板里写<VueBotUI />了。

第二步：用消息数组让界面先动起来

组件的核心数据是一个messages数组，每条消息最少包含三个字段：

先塞两条最朴素的文本消息：

data () { return { messages: [ { agent: 'bot', type: 'text', text: '你好，我是智能助手' } ] } }

模板中绑定即可：

<VueBotUI :messages="messages" :options="botOptions" @msg-send="handleSend" />

刷新页面，右下角会出现一个气泡按钮，点击弹出聊天面板，第一条机器人消息就显示出来了。

第三步：让机器人学会"给选项"

光会打字不算客服，得让机器人抛出可选按钮。这就是第二种气泡类型type: 'button'：

{ agent: 'bot', type: 'button', text: '请选择你遇到的问题类型：', disableInput: true, options: [ { text: '订单查询', value: 'order_query', action: 'postback' }, { text: '商品咨询', value: 'product_consult', action: 'postback' }, { text: '查看帮助文档', value: 'https://docs.example.com', action: 'url' } ] }

每个选项的action决定点击后的行为：

• postback：把整个选项对象抛回给父组件，由你在msg-send里处理，适合继续追问、查接口
• url：直接以新标签页打开链接，value就是跳转地址

注意我把disableInput设成了true，这样在用户点按钮之前无法打字输入，保证流程不会被乱入的文本打断。

用事件串起你的机器人接口：msg-send 的正确用法

组件对外只有一个核心事件msg-send，它同时覆盖两种来源：用户在输入框回车发送，以及点击按钮选项。它返回的value是一个对象，文本输入时取value.text，按钮选项时则是整个 option 对象。

一个完整的对话循环长这样（参考了仓库里的 src/App.vue）：

methods: { handleSend (value) { // 1. 先把用户消息追加进数组，界面立即回显 this.messages.push({ agent: 'user', type: 'text', text: value.text }) // 2. 亮起"正在输入"指示器，模拟真实等待 this.botTyping = true // 3. 假装请求你的机器人 API fetch('/api/bot', { method: 'POST', body: JSON.stringify({ text: value.text }) }) .then(res => res.json()) .then(reply => { this.botTyping = false this.messages.push({ agent: 'bot', ...reply }) }) } }

botTyping是组件的一个 prop，设为true时消息区尾部会出现三个跳动的小圆点。用它模拟延迟，比机器人秒回要自然得多。

另外两个生命周期事件也值得知道：

想在页面其他地方控制聊天窗口开关？

msg-send是组件向外发事件，反过来，你也可以在任意代码里通过三个全局自定义事件遥控它：

用法也很直白，比如在导航栏放一个"联系我们"按钮：

document.dispatchEvent(new CustomEvent('botui-open'))

加上is-open和open-delay两个 prop，你还能控制页面加载后自动弹窗：is-open设为true表示初始化即打开，配一个毫秒级的open-delay做延迟，很适合做欢迎弹窗。

15 个配置项，把界面调成你品牌的样子

options对象支持 15 个配置项，覆盖颜色、尺寸、文案三层，常用清单如下：

举个例子，把整体改成绿色调、机器人用浅色气泡、用户用品牌深色：

botOptions: { botTitle: '商城小助手', colorScheme: '#13c2a2', msgBubbleBgBot: '#f6ffed', msgBubbleBgUser: '#13c2a2', inputPlaceholder: '输入您的问题…' }

主题色一变，整个界面气质立刻就统一了。

还不够用？插槽和 CSS 类名给你兜底

配置项解决不了的需求，还有两招：

第一招：插槽替换。组件预留了 5 个插槽，常见的是在输入框旁边加功能按钮：

<VueBotUI :messages="messages" :options="botOptions"> <template v-slot:actions> <button @click="openEmoji">😊</button> <button @click="uploadFile">📎</button> </template> </VueBotUI>

其余插槽一览：header（面板头部）、sendButton（发送按钮）、bubbleButton（悬浮气泡按钮）、botTyping（打字指示器）。

第二招：改 CSS。每个组件都带独立的类名，前缀为qkb-，例如机器人消息是.qkb-msg-bubble--bot。样式覆盖不了的细节，直接写一段全局样式即可，不用动源码。

我踩过的三个坑，提前帮你避开

1. 按钮流程中忘了disableInput：点击选项后组件并不自动锁输入框，如果下一轮机器人还在"思考"，用户可能会连发多条。正确做法是回复消息里带上disableInput: true，或自己维护一个输入锁定状态。

2. is-open与open-delay必须配合：单独设open-delay而没有is-open: true是不会生效的，因为延时打开的逻辑挂在is-open分支里。

3. 动画开关影响测试：写单元测试或做自动化截图时，记得把animation设为false，否则transition会造成断言时机不稳定。

想在本地跑起完整 Demo 摸索源码

如果边看代码边学效率更高，可以克隆仓库本地运行：

git clone https://gitcode.com/gh_mirrors/vu/vue-bot-ui cd vue-bot-ui yarn yarn serve

本地开发服务器默认跑在 1901 端口，打开就能看到带模拟消息流、按钮选项、打字指示器的完整示例，配合 src/App.vue 和 src/helpers/fake-messages.js 读，数据流一目了然。

写在最后

接入 vue-bot-ui 的过程比我想象中短得多，真正写业务代码的时间不超过一顿午饭。它把聊天界面里最琐碎的部分（气泡、动画、滚动、输入控制）都封装好了，留给你的是最核心的问题：你的机器人到底该说什么、怎么接你的业务接口。

顺带一提，作者在 README 里列了待办清单：按钮选项的target属性、更多消息气泡类型、完整测试覆盖都还在路上。等它更成熟，这个组件值得放进你 Vue 项目的工具箱。

如果你的下一个需求恰好是"快速交付一个能用的聊天机器人界面"，不妨现在就 clone 下来跑一遍 demo——百闻不如一跑。

【免费下载链接】vue-bot-uiFor the one who is finding a customizable chatbot UI.项目地址: https://gitcode.com/gh_mirrors/vu/vue-bot-ui