001code-html--cocos/FriendToggle-使用说明.md

好友开关组件使用说明

📦 组件概述

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

🚀 快速开始

1. 引入组件

<!-- 方式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. 基础使用

// 创建一个默认配置的好友开关
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 方法

基础方法

const toggle = new FriendToggle();

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

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

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

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

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

配置更新

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

📡 事件监听

回调函数方式

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

全局事件监听

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

🎯 使用示例

示例1: 基础聊天功能

// 创建好友开关
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: 多人协作模式

// 创建协作模式开关
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: 与现有项目集成

// 在 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>;
    }
}

🎨 主题定制

使用预设主题

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

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

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

自定义样式

/* 自定义主题样式 */
.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%);
}

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

🔧 高级用法

多实例管理

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' });

动态配置

// 根据屏幕尺寸调整组件
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 种主题
• 支持自动隐藏、事件回调等功能