🎈 悬浮球组件

一个功能强大、高度可定制的 Vue 3 悬浮球组件。

✨ 特性

• 🎨 7 种主题 - 默认、极简、毛玻璃、实心、暗黑、🌈 幻彩、🎨 自定义颜色
• 🖱️ 拖拽移动 - 支持鼠标和触摸拖拽
• 🧲 边缘吸附 - 自动吸附到屏幕边缘
• 💾 位置记忆 - 刷新页面保持位置
• 📱 移动端支持 - 完美适配移动设备
• 🎯 高度可定制 - 插槽系统，自定义图标和内容
• 🎮 内置演示 - 完整的配置和演示页面
• 📦 多种集成 - NPM 包、Vue 插件、iframe 方式
• 🔧 TypeScript - 完整的类型支持

🚀 快速开始

本地开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

📦 集成方式

本组件支持 两种集成方式：

方式 1：NPM 包（Vue 3 项目）

# 1. 在其他项目中安装
npm install flex-floating-ball

# 2. 使用
import { SimpleFloatingBall } from 'flex-floating-ball'
import 'flex-floating-ball/dist/floating-ball.css'

👉 完整 NPM 使用指南

方式 2：iframe（任意项目）

# 1. 构建并部署
npm run build
# 将 dist/ 目录部署到服务器

# 2. 在任何项目中使用
<script src="https://your-domain.com/floating-ball-iframe.js"></script>
<script>
  new FloatingBallIframe('https://your-domain.com');
</script>

👉 完整 iframe 使用指南

📖 使用示例

基础用法

<template>
  <SimpleFloatingBall show-toggle-button>
    <!-- 自定义图标 -->
    <template #icon>
      <el-icon :size="24">
        <ChatDotRound />
      </el-icon>
    </template>

    <!-- 自定义内容 -->
    <div>
      <h2>这是自定义面板</h2>
      <p>在这里放置您的业务内容</p>
    </div>
  </SimpleFloatingBall>
</template>

<script setup>
import SimpleFloatingBall from "./components/SimpleFloatingBall.vue";
import { ChatDotRound } from "@element-plus/icons-vue";
</script>

NPM 包使用

// main.ts
import { createApp } from "vue";
import { FloatingBall } from "flex-floating-ball";
import App from "./App.vue";

const app = createApp(App);
app.component("FloatingBall", FloatingBall);
app.mount("#app");

Vue 插件方式

// main.ts
import { createApp } from "vue";
import FloatingBallPlugin from "flex-floating-ball";
import App from "./App.vue";

const app = createApp(App);
app.use(FloatingBallPlugin, {
  componentName: "FloatingBall", // 可选，默认为 'FloatingBall'
});
app.mount("#app");

🎨 主题系统

组件内置 7 种主题：

| 主题 | 描述 | 效果 | | --------- | ------------ | --------------- | | default | 默认紫色渐变 | 渐变背景 + 阴影 | | minimal | 极简白色 | 纯白背景 + 边框 | | glass | 毛玻璃效果 | 半透明 + 模糊 | | solid | 实心蓝色 | 纯色背景 | | dark | 暗黑模式 | 深色背景 | | rainbow | 🌈 幻彩主题 | 彩虹渐变 + 动画 | | custom | 🎨 自定义 | 任意颜色 🆕 |

幻彩主题

幻彩主题使用 RequestAnimationFrame 实现流畅的 60fps 动画：

• 🌈 多层渐变叠加（径向 + 锥形 + 线性）
• ✨ 12 个 CSS 变量动态更新
• 💫 复合阴影系统（外部 + 内部）
• 🎨 三角函数控制渐变中心移动
• 🎭 多重动画叠加（浮动 + 呼吸 + 脉冲）

详见 RAINBOW_THEME.md

🔌 插槽系统

图标插槽

自定义悬浮球图标：

<SimpleFloatingBall>
  <template #icon>
    <!-- Element Plus 图标 -->
    <el-icon :size="24"><Service /></el-icon>
    
    <!-- 或文字 -->
    <span style="font-size: 20px">客服</span>
    
    <!-- 或图片 -->
    <img src="icon.png" style="width: 32px" />
  </template>
</SimpleFloatingBall>

内容插槽

自定义面板内容：

<SimpleFloatingBall>
  <div class="custom-content">
    <h2>业务内容</h2>
    <el-button>操作按钮</el-button>
  </div>
</SimpleFloatingBall>

详见 SLOTS.md

⚙️ Props

| 属性 | 类型 | 默认值 | 说明 | | -------------------- | --------- | ------- | -------------------------- | | show-toggle-button | boolean | false | 是否显示设置按钮（悬停时） |

🎯 功能配置

在内置演示页面中可以配置：

• 徽章数量 - 显示未读消息数
• 主题切换 - 6 种主题任意切换
• 位置记忆 - 开启后刷新页面保持位置
• 边缘吸附 - 开启后自动吸附到边缘
• 尺寸调整 - 悬浮球大小（40-100px）
• 面板宽度 - 自定义面板宽度（300-600px）

📁 项目结构

floating-ball/
├── src/
│   ├── components/
│   │   └── SimpleFloatingBall.vue    ← 核心组件
│   ├── App.vue                        ← 演示页面
│   ├── main.ts                        ← 入口文件
│   ├── index.ts                       ← 组件导出
│   ├── vue-plugin.ts                  ← Vue 插件
│   └── style.css                      ← 全局样式
├── examples/                          ← 使用示例
├── ARCHITECTURE.md                    ← 架构文档
├── DESIGN.md                          ← 设计文档
├── RAINBOW_THEME.md                   ← 幻彩主题技术说明
└── SLOTS.md                           ← 插槽使用指南

🌟 应用场景

• 💬 在线客服 - 聊天窗口
• 📊 数据仪表板 - 实时数据展示
• 📝 快速笔记 - 便签工具
• 🔔 消息通知 - 通知中心
• ⚙️ 工具面板 - 快捷操作
• 🎮 游戏辅助 - 控制面板

🛠️ 技术栈

• 框架: Vue 3.5+
• 构建工具: Vite 7.x
• 语言: TypeScript 5.x
• UI 组件: Element Plus
• CSS: Tailwind CSS + SCSS
• 状态管理: Pinia
• 工具库: Axios, Moment.js

📚 文档

使用指南

• 快速开始 - NPM 和 iframe 方式快速开始
• NPM 完整指南 - NPM 包详细使用方法
• Vue 插件使用 - 插件方式完整示例 🆕
• iframe 完整指南 - iframe 集成详细说明

功能文档

• 插槽系统 - 自定义插槽使用指南
• 幻彩主题 - 幻彩主题技术详解

技术文档

• 架构设计 - 组件架构和设计思路
• 设计文档 - 完整的设计方案

🎮 演示

在线体验

1. 克隆项目：

   git clone <repo-url>
   cd floating-ball

2. 安装依赖：

   npm install

3. 启动开发服务器：

   npm run dev

4. 打开浏览器，悬停悬浮球，点击 ⚙️ 设置按钮查看完整演示

快速测试

• 拖拽 - 鼠标按住悬浮球拖动
• 点击 - 点击悬浮球打开自定义面板
• 主题 - 在演示页面切换不同主题
• 配置 - 调整各项功能开关

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🌈 特别说明

幻彩主题 是本组件的一大亮点，完全复刻了 BreathingColorfulBall.vue 的效果，并增加了拖拽、配置等额外功能。

切换到幻彩主题，享受梦幻般的视觉效果！✨

Happy Coding! 🎉