238 lines
6.1 KiB
Markdown
238 lines
6.1 KiB
Markdown
# AI智能客服浮动按钮组件
|
||
|
||
## 组件介绍
|
||
|
||
AI智能客服浮动按钮组件是一个可以在任何页面中使用的浮动AI客服按钮，点击按钮可以弹出完整的AI智能客服聊天界面。该组件基于现有的AI聊天消息组件，提供了丰富的交互功能和配置选项。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ **浮动按钮** - 可自定义位置的浮动AI客服按钮
|
||
- ✅ **聊天弹窗** - 点击按钮弹出完整的AI聊天界面
|
||
- ✅ **全屏模式** - 支持全屏/窗口模式切换
|
||
- ✅ **未读消息** - 显示未读消息数量小红点
|
||
- ✅ **多种消息类型** - 支持文本、文件、图片、音频、视频、链接等
|
||
- ✅ **流式对话** - 支持流式AI回复效果
|
||
- ✅ **响应式设计** - 适配不同屏幕尺寸
|
||
- ✅ **自定义配置** - 丰富的配置选项
|
||
|
||
## 安装使用
|
||
|
||
### 1. 引入组件
|
||
|
||
在需要使用AI客服浮动按钮的页面中引入组件：
|
||
|
||
```json
|
||
// 页面配置文件 pages/xxx/xxx.json
|
||
{
|
||
"usingComponents": {
|
||
"ai-chat-float": "@/components/ai-chat-float/ai-chat-float"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 在页面中使用
|
||
|
||
```vue
|
||
<!-- 页面模板 pages/xxx/xxx.vue -->
|
||
<template>
|
||
<view class="page">
|
||
<!-- 页面内容 -->
|
||
<view class="content">
|
||
<!-- 您的页面内容 -->
|
||
</view>
|
||
|
||
<!-- AI客服浮动按钮 -->
|
||
<ai-chat-float
|
||
ref="aiChatFloat"
|
||
:position="position"
|
||
:show-float-button="showButton"
|
||
:auto-open="autoOpen"
|
||
:initial-messages="initialMessages"
|
||
@chat-open="onChatOpen"
|
||
@chat-close="onChatClose"
|
||
@message-sent="onMessageSent"
|
||
@ai-response="onAIResponse"
|
||
@unread-update="onUnreadUpdate" />
|
||
</view>
|
||
</template>
|
||
|
||
<script>
|
||
import aiChatFloat from '@/components/ai-chat-float/ai-chat-float.vue'
|
||
|
||
export default {
|
||
components: {
|
||
aiChatFloat
|
||
},
|
||
data() {
|
||
return {
|
||
position: 'bottom-right',
|
||
showButton: true,
|
||
autoOpen: false,
|
||
initialMessages: []
|
||
}
|
||
},
|
||
methods: {
|
||
onChatOpen() {
|
||
console.log('AI客服聊天窗口打开')
|
||
},
|
||
onChatClose() {
|
||
console.log('AI客服聊天窗口关闭')
|
||
},
|
||
onMessageSent(message) {
|
||
console.log('用户发送消息:', message)
|
||
},
|
||
onAIResponse(message) {
|
||
console.log('AI回复消息:', message)
|
||
},
|
||
onUnreadUpdate(count) {
|
||
console.log('未读消息数量:', count)
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
## 组件属性
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|--------|------|--------|------|
|
||
| position | String | 'bottom-right' | 按钮位置，可选值：'bottom-right', 'bottom-left', 'top-right', 'top-left' |
|
||
| offset | Object | { bottom: '100rpx', right: '40rpx', top: '100rpx', left: '40rpx' } | 按钮距离边缘的距离 |
|
||
| userAvatar | String | '/static/images/default-avatar.png' | 用户头像 |
|
||
| aiAvatar | String | '/static/images/ai-avatar.png' | AI头像 |
|
||
| initialMessages | Array | [] | 初始聊天消息 |
|
||
| showFloatButton | Boolean | true | 是否显示浮动按钮 |
|
||
| autoOpen | Boolean | false | 是否自动打开聊天窗口 |
|
||
|
||
## 事件监听
|
||
|
||
| 事件名 | 参数 | 说明 |
|
||
|--------|------|------|
|
||
| chat-open | - | 聊天窗口打开事件 |
|
||
| chat-close | - | 聊天窗口关闭事件 |
|
||
| message-sent | message | 用户发送消息事件 |
|
||
| ai-response | message | AI回复消息事件 |
|
||
| unread-update | count | 未读消息数量更新事件 |
|
||
| history-loaded | messages | 历史消息加载完成事件 |
|
||
| file-preview | message | 文件预览事件 |
|
||
| audio-play | message | 音频播放事件 |
|
||
| video-play | message | 视频播放事件 |
|
||
| link-open | message | 链接打开事件 |
|
||
| product-view | message | 商品查看事件 |
|
||
| action-click | {action, message} | 操作按钮点击事件 |
|
||
| input-change | value | 输入内容变化事件 |
|
||
|
||
## 方法调用
|
||
|
||
通过组件引用可以调用以下方法：
|
||
|
||
```javascript
|
||
// 获取组件引用
|
||
const aiChatFloat = this.$refs.aiChatFloat
|
||
|
||
// 打开聊天窗口
|
||
aiChatFloat.openChat()
|
||
|
||
// 关闭聊天窗口
|
||
aiChatFloat.closeChat()
|
||
|
||
// 添加消息
|
||
aiChatFloat.addMessage({
|
||
role: 'ai',
|
||
type: 'text',
|
||
content: '这是一条新消息',
|
||
read: false
|
||
})
|
||
|
||
// 清空聊天记录
|
||
aiChatFloat.clearMessages()
|
||
|
||
// 标记所有消息为已读
|
||
aiChatFloat.markAllAsRead()
|
||
```
|
||
|
||
## 配置示例
|
||
|
||
### 基本配置
|
||
|
||
```vue
|
||
<ai-chat-float
|
||
position="bottom-right"
|
||
:show-float-button="true"
|
||
:auto-open="false" />
|
||
```
|
||
|
||
### 自定义位置
|
||
|
||
```vue
|
||
<ai-chat-float
|
||
position="top-left"
|
||
:offset="{ top: '200rpx', left: '60rpx' }" />
|
||
```
|
||
|
||
### 自定义头像
|
||
|
||
```vue
|
||
<ai-chat-float
|
||
:user-avatar="/static/avatars/user.jpg"
|
||
:ai-avatar="/static/avatars/ai.jpg" />
|
||
```
|
||
|
||
### 初始消息
|
||
|
||
```vue
|
||
<ai-chat-float
|
||
:initial-messages="[
|
||
{
|
||
id: 1,
|
||
role: 'ai',
|
||
type: 'text',
|
||
content: '欢迎使用AI客服！',
|
||
timestamp: Date.now(),
|
||
read: false
|
||
}
|
||
]" />
|
||
```
|
||
|
||
## 样式定制
|
||
|
||
组件支持通过CSS变量进行样式定制：
|
||
|
||
```css
|
||
/* 自定义主题色 */
|
||
.ai-float-button {
|
||
--primary-color: #ff4544;
|
||
--primary-gradient: linear-gradient(135deg, #ff4544, #ff6b6b);
|
||
}
|
||
|
||
/* 自定义尺寸 */
|
||
.ai-float-button {
|
||
--button-size: 120rpx;
|
||
--icon-size: 48rpx;
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **依赖组件**：本组件依赖 `ai-chat-message` 组件，请确保该组件已正确安装
|
||
2. **图标字体**：组件使用了 iconfont 图标，请确保项目中已引入相应的图标字体
|
||
3. **响应式设计**：组件已适配移动端和PC端，但在特殊场景下可能需要额外调整
|
||
4. **性能优化**：在大量消息时建议启用消息数量限制
|
||
|
||
## 演示页面
|
||
|
||
访问 `/pages/ai-chat-float/index` 查看完整的演示效果，包含所有配置选项的实时预览。
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2024-11-03)
|
||
- ✨ 初始版本发布
|
||
- ✨ 支持浮动按钮和聊天弹窗
|
||
- ✨ 支持多种消息类型
|
||
- ✨ 支持流式对话
|
||
- ✨ 支持全屏模式
|
||
- ✨ 支持未读消息提示
|
||
|
||
## 技术支持
|
||
|
||
如有问题或建议，请联系开发团队。 |