Initial commit of 001code-html Scratch frontend project.

Includes scratch-gui, scratch-vm, scratch-blocks, scratch-render, scratch-l10n, and deployment config.

Co-authored-by: Cursor <cursoragent@cursor.com>

FriendToggle-使用说明.md

@@ -0,0 +1,334 @@
+# 好友开关组件使用说明
+
+## 📦 组件概述
+
+好友开关组件是一个独立的、可重用的悬浮按钮组件，支持多种配置选项和主题样式。
+
+## 🚀 快速开始
+
+### 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 种主题
+- 支持自动隐藏、事件回调等功能