# 好友开关组件使用说明

## 📦 组件概述

好友开关组件是一个独立的、可重用的悬浮按钮组件，支持多种配置选项和主题样式。

## 🚀 快速开始

### 1. 引入组件

```html
<!-- 方式1: 直接引入 -->
<script src="./scratch-gui/src/components/friend-toggle/FriendToggle.js"></script>

<!-- 方式2: ES6 模块导入 -->
<script type="module">
    import FriendToggle from './scratch-gui/src/components/friend-toggle/FriendToggle.js';
</script>
```

### 2. 基础使用

```javascript
// 创建一个默认配置的好友开关
const friendToggle = new FriendToggle();

// 创建一个自定义配置的好友开关
const customToggle = new FriendToggle({
    position: 'top-right',    // 位置
    size: 'large',           // 大小
    theme: 'dark',           // 主题
    autoHide: false,         // 关闭自动隐藏
    initialState: true,      // 初始激活状态
    onToggle: (isActive) => {
        console.log('状态改变:', isActive);
    }
});
```

## ⚙️ 配置选项

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `position` | string | `'bottom-right'` | 位置：`'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'` |
| `size` | string | `'medium'` | 大小：`'small'`, `'medium'`, `'large'` |
| `theme` | string | `'default'` | 主题：`'default'`, `'dark'`, `'colorful'` |
| `autoHide` | boolean | `true` | 是否自动隐藏（3秒后） |
| `onToggle` | function | `null` | 状态切换回调函数 |
| `initialState` | boolean | `false` | 初始状态（激活/未激活） |
| `zIndex` | number | `9999` | CSS z-index 值 |

## 🎨 API 方法

### 基础方法

```javascript
const toggle = new FriendToggle();

// 切换状态
toggle.toggle();

// 设置状态
toggle.setState(true);  // 激活
toggle.setState(false); // 未激活

// 获取状态
const isActive = toggle.getState();

// 显示/隐藏组件
toggle.show();
toggle.hide();

// 销毁组件
toggle.destroy();
```

### 配置更新

```javascript
// 动态更新配置
toggle.updateConfig({
    position: 'top-left',
    theme: 'colorful',
    autoHide: false
});
```

## 📡 事件监听

### 回调函数方式

```javascript
const toggle = new FriendToggle({
    onToggle: (isActive) => {
        if (isActive) {
            console.log('好友模式开启');
            // 开启好友相关功能
        } else {
            console.log('好友模式关闭');
            // 关闭好友相关功能
        }
    }
});
```

### 全局事件监听

```javascript
// 监听自定义事件
document.addEventListener('friendToggleChange', (event) => {
    const { isActive, instance } = event.detail;
    console.log('组件状态变化:', isActive);
    console.log('组件实例:', instance);
});
```

## 🎯 使用示例

### 示例1: 基础聊天功能

```javascript
// 创建好友开关
const chatToggle = new FriendToggle({
    position: 'bottom-right',
    theme: 'default',
    onToggle: (isActive) => {
        if (isActive) {
            // 显示聊天窗口
            showChatWindow();
        } else {
            // 隐藏聊天窗口
            hideChatWindow();
        }
    }
});

function showChatWindow() {
    // 你的聊天窗口显示逻辑
    console.log('显示聊天窗口');
}

function hideChatWindow() {
    // 你的聊天窗口隐藏逻辑
    console.log('隐藏聊天窗口');
}
```

### 示例2: 多人协作模式

```javascript
// 创建协作模式开关
const collaborationToggle = new FriendToggle({
    position: 'top-right',
    size: 'large',
    theme: 'colorful',
    autoHide: false,
    onToggle: (isActive) => {
        toggleCollaborationMode(isActive);
    }
});

function toggleCollaborationMode(enabled) {
    if (enabled) {
        // 启用协作功能
        enableRealTimeSync();
        showCollaborators();
        console.log('协作模式已开启');
    } else {
        // 禁用协作功能
        disableRealTimeSync();
        hideCollaborators();
        console.log('协作模式已关闭');
    }
}
```

### 示例3: 与现有项目集成

```javascript
// 在 Scratch GUI 中集成
import FriendToggle from './components/friend-toggle/FriendToggle.js';

class MyComponent extends React.Component {
    componentDidMount() {
        // 创建好友开关
        this.friendToggle = new FriendToggle({
            position: 'bottom-left',
            onToggle: this.handleFriendToggle.bind(this)
        });
    }
    
    componentWillUnmount() {
        // 清理组件
        if (this.friendToggle) {
            this.friendToggle.destroy();
        }
    }
    
    handleFriendToggle(isActive) {
        // 处理状态变化
        this.setState({ friendModeActive: isActive });
        
        if (isActive) {
            this.initializeFriendFeatures();
        } else {
            this.cleanupFriendFeatures();
        }
    }
    
    render() {
        // 你的组件渲染逻辑
        return <div>My Component</div>;
    }
}
```

## 🎨 主题定制

### 使用预设主题

```javascript
// 默认主题（蓝紫渐变）
const defaultToggle = new FriendToggle({ theme: 'default' });

// 深色主题（黑灰渐变）
const darkToggle = new FriendToggle({ theme: 'dark' });

// 彩色主题（粉色渐变）
const colorfulToggle = new FriendToggle({ theme: 'colorful' });
```

### 自定义样式

```css
/* 自定义主题样式 */
.friend-toggle.custom-theme {
    background: linear-gradient(135deg, #ff6b6b 0%, #feca57 100%);
    color: white;
}

.friend-toggle.custom-theme.active {
    background: linear-gradient(135deg, #48dbfb 0%, #0abde3 100%);
}
```

```javascript
// 应用自定义主题
const customToggle = new FriendToggle({
    theme: 'custom-theme'
});
```

## 🔧 高级用法

### 多实例管理

```javascript
class FriendToggleManager {
    constructor() {
        this.instances = new Map();
    }
    
    create(id, config) {
        const toggle = new FriendToggle(config);
        this.instances.set(id, toggle);
        return toggle;
    }
    
    destroy(id) {
        const toggle = this.instances.get(id);
        if (toggle) {
            toggle.destroy();
            this.instances.delete(id);
        }
    }
    
    destroyAll() {
        this.instances.forEach(toggle => toggle.destroy());
        this.instances.clear();
    }
}

// 使用管理器
const manager = new FriendToggleManager();
manager.create('chat', { position: 'bottom-right' });
manager.create('collaboration', { position: 'top-right' });
```

### 动态配置

```javascript
// 根据屏幕尺寸调整组件
function createResponsiveToggle() {
    const isMobile = window.innerWidth < 768;
    
    return new FriendToggle({
        size: isMobile ? 'small' : 'medium',
        position: isMobile ? 'bottom-left' : 'bottom-right',
        autoHide: isMobile // 移动设备自动隐藏
    });
}

// 监听窗口大小变化
window.addEventListener('resize', () => {
    // 重新创建响应式组件
});
```

## 🐛 常见问题

### Q: 组件没有显示？
A: 确保正确引入了 JavaScript 文件，并且调用了 `new FriendToggle()`。

### Q: 样式冲突怎么办？
A: 组件使用了独立的 CSS 类名和高 z-index，如果仍有冲突，可以调整 `zIndex` 配置。

### Q: 如何自定义图标？
A: 可以通过 CSS 覆盖 `.friend-toggle .icon` 的内容，或修改组件源码中的图标。

### Q: 能否在移动设备上使用？
A: 可以，组件支持触摸事件，建议在移动设备上使用较小的尺寸。

## 📝 测试说明

1. 打开 `test-friend-toggle.html` 文件
2. 在浏览器中查看效果
3. 使用控制面板测试各种配置
4. 观察右下角的悬浮按钮

## 🔄 更新记录

- v1.0.0: 初始版本，支持基本的开关功能
- 支持 4 种位置、3 种大小、3 种主题
- 支持自动隐藏、事件回调等功能