vue-chat-bubble

v1.0.0

Published

5 months ago

A floating chat bubble component for Vue 3 and vanilla JavaScript

0High
0Medium
0Low

nekolas

vue vue3 chat bubble component customer-service iframe webcomponent

Vue Chat Bubble

一个基于 Vue 3 和 Web Components 的浮动聊天气泡组件，支持嵌入 iframe 聊天界面。

特性

🚀 支持 Vue 3 组件和 Web Components 两种使用方式
💫 可自定义位置、尺寸、主题
📱 响应式设计，适配移动端
🎨 基于 Element Plus 图标
📦 TypeScript 支持
🔧 零配置，开箱即用

安装

npm install vue-chat-bubble

使用方式

Vue 3 组件方式

1. 全局注册

import { createApp } from 'vue'
import VueChatBubble from 'vue-chat-bubble'
import 'vue-chat-bubble/style.css'

const app = createApp(App)
app.use(VueChatBubble)

2. 局部引入

<template>
  <div>
    <ChatBubble
      :chat-url="chatUrl"
      :user-id="userId"
      position="bottom-right"
      size="medium"
      theme="primary"
      @open="onChatOpen"
      @close="onChatClose"
      @toggle="onChatToggle"
    />
  </div>
</template>

<script setup>
import { ChatBubble } from 'vue-chat-bubble'
import 'vue-chat-bubble/style.css'

const chatUrl = 'https://your-chat-service.com/chat'
const userId = 'user123'

const onChatOpen = () => {
  console.log('聊天窗口打开')
}

const onChatClose = () => {
  console.log('聊天窗口关闭')
}

const onChatToggle = (isOpen) => {
  console.log('聊天窗口状态:', isOpen)
}
</script>

3. 通过 ref 调用方法

<template>
  <div>
    <ChatBubble ref="chatBubbleRef" :chat-url="chatUrl" />
    <button @click="openChat">打开聊天</button>
    <button @click="closeChat">关闭聊天</button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { ChatBubble } from 'vue-chat-bubble'

const chatBubbleRef = ref()

const openChat = () => {
  chatBubbleRef.value?.open()
}

const closeChat = () => {
  chatBubbleRef.value?.close()
}
</script>

Web Components 方式

1. 引入脚本

<!doctype html>
<html>
  <head>
    <title>Chat Bubble Example</title>
  </head>
  <body>
    <!-- 引入 Web Component 脚本 -->
    <script src="https://unpkg.com/vue-chat-bubble/dist/webcomponent.js"></script>

    <!-- 使用自定义元素 -->
    <chat-bubble
      chat-url="https://your-chat-service.com/chat"
      user-id="user123"
      position="bottom-right"
      size="medium"
      theme="primary"
    >
    </chat-bubble>

    <script>
      // 监听事件
      const chatBubble = document.querySelector('chat-bubble')

      chatBubble.addEventListener('open', () => {
        console.log('聊天窗口打开')
      })

      chatBubble.addEventListener('close', () => {
        console.log('聊天窗口关闭')
      })

      chatBubble.addEventListener('toggle', (event) => {
        console.log('聊天窗口状态:', event.detail.isOpen)
      })

      // 调用方法
      setTimeout(() => {
        chatBubble.open() // 3秒后自动打开聊天窗口
      }, 3000)
    </script>
  </body>
</html>

2. 通过 JavaScript 动态创建

// 创建聊天气泡元素
const chatBubble = document.createElement('chat-bubble')
chatBubble.setAttribute('chat-url', 'https://your-chat-service.com/chat')
chatBubble.setAttribute('user-id', 'user123')
chatBubble.setAttribute('position', 'bottom-left')
chatBubble.setAttribute('theme', 'success')

// 添加到页面
document.body.appendChild(chatBubble)

// 监听事件
chatBubble.addEventListener('toggle', (event) => {
  console.log('Chat toggled:', event.detail.isOpen)
})

API 文档

Props / Attributes

| 属性 | 类型 | 默认值 | 说明 | | ---------- | -------------------------------------------------------------- | ------------------------------------------ | ---------------------------- | | chat-url | string | 'http://localhost:3000/pages/chat/index' | 聊天页面的 URL | | user-id | string | '' | 用户 ID，会作为 URL 参数传递 | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | 气泡位置 | | size | 'small' \| 'medium' \| 'large' | 'medium' | 气泡尺寸 | | theme | 'primary' \| 'success' \| 'warning' \| 'danger' | 'primary' | 气泡主题色 |

Events (Vue 组件)

| 事件名 | 参数 | 说明 | | -------- | ------------------- | ---------------------- | | open | - | 聊天窗口打开时触发 | | close | - | 聊天窗口关闭时触发 | | toggle | (isOpen: boolean) | 聊天窗口状态切换时触发 |

Methods

| 方法名 | 说明 | | ---------- | ----------------------------------- | | open() | 打开聊天窗口 | | close() | 关闭聊天窗口 | | toggle() | 切换聊天窗口状态 | | isOpen() | 获取当前是否打开状态（仅 Vue 组件） |

Custom Events (Web Components)

// 监听自定义事件
chatBubble.addEventListener('open', () => {})
chatBubble.addEventListener('close', () => {})
chatBubble.addEventListener('toggle', (event) => {
  console.log(event.detail.isOpen)
})

样式定制

CSS 变量

你可以通过 CSS 变量来自定义组件样式：

:root {
  --chat-bubble-z-index: 1000;
  --chat-bubble-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  --chat-iframe-width: 350px;
  --chat-iframe-height: 500px;
  --chat-iframe-border-radius: 8px;
}

尺寸配置

| 尺寸 | 宽高 | 字体大小 | | -------- | ----------- | -------- | | small | 50px × 50px | 20px | | medium | 60px × 60px | 24px | | large | 70px × 70px | 28px |

主题色配置

| 主题 | 背景色 | 激活时背景色 | | --------- | ------- | ------------ | | primary | #409eff | #f56c6c | | success | #67c23a | #f56c6c | | warning | #e6a23c | #f56c6c | | danger | #f56c6c | #409eff |

示例项目

查看 examples 目录获取完整示例：

开发

# 克隆项目
git clone https://github.com/yourusername/vue-chat-bubble.git

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 构建 Vue 组件
npm run build:vue

# 构建 Web Component
npm run build:webcomponent

浏览器支持

Chrome >= 63
Firefox >= 63
Safari >= 13.1
Edge >= 79

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！