刘宇飞
6e0a1fbcbb
Includes scratch-gui, scratch-vm, scratch-blocks, scratch-render, scratch-l10n, and deployment config. Co-authored-by: Cursor <cursoragent@cursor.com>
334 lines
7.7 KiB
Markdown
334 lines
7.7 KiB
Markdown
# 好友开关组件使用说明
|
||
|
||
## 📦 组件概述
|
||
|
||
好友开关组件是一个独立的、可重用的悬浮按钮组件，支持多种配置选项和主题样式。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 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 种主题
|
||
- 支持自动隐藏、事件回调等功能 |