# itoolball

**Repository Path**: helloFF/itoolball

## Basic Information

- **Project Name**: itoolball
- **Description**: 一个快速在页面上创建操作球的工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-27
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ToolBall 工具球组件

一个功能丰富的 JavaScript 组件，用于在网页中快速创建工具球和工具面板。

## ✨ 特性

- 🎯 **工具球**：40×40px 圆形，支持拖拽移动，始终吸附在页面右侧
- 📋 **工具面板**：200px 宽度，支持工具分组显示
- 🔧 **内置工具**：按钮、开关、下拉选择、滑块、文本框五种工具类型
- 🎨 **样式隔离**：使用 Shadow DOM 实现与主页面的样式隔离
- 📡 **事件系统**：完整的事件监听和触发机制
- 🎪 **动画效果**：100ms ease-out 滑入滑出效果

## 🚀 快速开始

### 1. 引入组件

**开发版本（源码）**：
```html
<script src="src/toolball.js"></script>
```

**生产版本（压缩）**：
```html
<script src="dist/toolball.min.js"></script>
```

### 2. 初始化工具球

```javascript
const toolBall = initToolBall({
    ball: {
        name: '我的工具',
        id: 'main-toolball',
        theme: 'light'
    },
    panel: {
        width: 250,
        layout: 'list',
        groups: true
    }
});
```

### 3. 添加工具

```javascript
// 添加按钮工具
toolBall.addTool('button', {
    id: 'btn-save',
    name: '保存',
    icon: '💾',
    group: '常用工具',
    onClick: async () => {
        console.log('保存数据');
        await new Promise(resolve => setTimeout(resolve, 1000));
        alert('保存成功！');
    }
});

// 添加开关工具
toolBall.addTool('switch', {
    id: 'switch-auto-save',
    name: '自动保存',
    group: '设置',
    defaultValue: true,
    onChange: (value) => {
        console.log('自动保存:', value ? '开启' : '关闭');
    }
});

// 添加下拉选择工具
toolBall.addTool('select', {
    id: 'select-theme',
    name: '主题',
    group: '设置',
    options: [
        { value: 'light', label: '浅色主题' },
        { value: 'dark', label: '深色主题' }
    ],
    defaultValue: 'light',
    onChange: (value) => {
        console.log('主题切换为:', value);
    }
});

// 添加滑块工具
toolBall.addTool('slider', {
    id: 'slider-volume',
    name: '音量',
    group: '设置',
    min: 0,
    max: 100,
    defaultValue: 50,
    onChange: (value) => {
        console.log('音量设置为:', value);
    }
});
```

## 📖 API 文档

### 初始化配置

```javascript
initToolBall({
    ball: {
        name: '工具球名称',        // 工具球显示名称
        id: 'unique-id',          // 唯一标识符
        theme: 'light'            // 主题模式 'light'|'dark'
    },
    panel: {
        width: 200,              // 面板宽度（像素）
        layout: 'list',          // 布局模式 'list'|'grid'
        groups: true             // 是否启用分组
    }
})
```

### 工具球实例方法

```javascript
// 显示/隐藏工具球
toolBall.show();
toolBall.hide();

// 添加工具
const tool = toolBall.addTool(type, config);

// 删除工具
toolBall.removeTool(toolId);

// 更新工具
toolBall.updateTool(toolId, updates);

// 获取工具
const tool = toolBall.getTool(toolId);
```

### 工具类型

#### 按钮工具 (button)
```javascript
const buttonTool = toolBall.addTool('button', {
    id: 'btn-1',
    name: '按钮名称',
    icon: '🔧',                 // 图标（可选）
    group: '分组名称',           // 分组（可选）
    onClick: async () => {      // 点击回调
        // 异步操作
    }
});

// 触发点击
buttonTool.click();

// 设置启用/禁用
buttonTool.setEnabled(true);
```

#### 开关工具 (switch)
```javascript
const switchTool = toolBall.addTool('switch', {
    id: 'switch-1',
    name: '开关名称',
    defaultValue: true,         // 默认状态
    onChange: (value) => {     // 状态变化回调
        console.log('状态:', value);
    }
});

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

// 设置状态
switchTool.setValue(true);

// 获取状态
const value = switchTool.getValue();
```

#### 下拉选择工具 (select)
```javascript
const selectTool = toolBall.addTool('select', {
    id: 'select-1',
    name: '选择名称',
    options: [                  // 选项列表
        { value: 'option1', label: '选项1' },
        { value: 'option2', label: '选项2' }
    ],
    defaultValue: 'option1',   // 默认值
    onChange: (value) => {     // 值变化回调
        console.log('选择:', value);
    }
});

// 设置值
selectTool.setValue('option2');

// 获取值
const value = selectTool.getValue();
```

#### 滑块工具 (slider)
```javascript
const sliderTool = toolBall.addTool('slider', {
    id: 'slider-1',
    name: '滑块名称',
    min: 0,                     // 最小值
    max: 100,                   // 最大值
    step: 1,                    // 步长
    defaultValue: 50,          // 默认值
    onChange: (value) => {     // 值变化回调
        console.log('值:', value);
    }
});

// 设置值
sliderTool.setValue(75);

// 获取值
const value = sliderTool.getValue();
```

### 事件监听

```javascript
// 监听工具球事件
toolBall.on('show', () => console.log('工具球显示'));
toolBall.on('hide', () => console.log('工具球隐藏'));
toolBall.on('panel:show', () => console.log('面板打开'));
toolBall.on('panel:hide', () => console.log('面板关闭'));
toolBall.on('tool:added', (tool) => console.log('工具添加:', tool.name));
toolBall.on('tool:removed', (toolId) => console.log('工具删除:', toolId));

// 监听工具事件
tool.on('change', (value) => console.log('值变化:', value));
tool.on('click', () => console.log('工具点击'));
tool.on('error', (error) => console.error('工具错误:', error));
```

## 🎨 样式定制

组件使用 Shadow DOM 实现样式隔离，所有样式都通过 JavaScript 动态注入。如需自定义样式，可以修改 `TOOLBALL_STYLES` 常量中的 CSS 代码。

## 📁 文件结构

```
toolball/
├── src/
│   └── toolball.js          # 主组件文件（包含所有功能）
├── dist/
│   └── toolball.min.js      # 压缩后的生产版本
├── examples/
│   ├── demo.html           # 使用示例
│   └── test-minified.html  # 压缩版本测试
├── docs/
│   ├── ToolBall组件设计文档.md
│   └── 沟通记录.md
├── package.json            # 项目配置
├── webpack.config.js       # Webpack配置
├── BUILD.md                # 构建说明
└── README.md
```

## 🔧 构建说明

### 安装依赖
```bash
npm install
```

### 构建生产版本
```bash
npm run build
```

### 构建开发版本
```bash
npm run build:dev
```

### 使用 Terser 压缩
```bash
npm run minify
```

### 文件大小对比
| 版本 | 文件大小 | 说明 |
|------|----------|------|
| 源码 | 38.7 KB | 原始源码 |
| 生产版本 | 20.3 KB | Webpack + Terser 压缩 |
| 压缩率 | 47% | 文件大小减少近一半 |

## 🌟 示例

查看 `examples/demo.html` 文件获取完整的使用示例。

## 🔧 技术实现

- **Shadow DOM**：实现样式隔离
- **Custom Elements**：使用 Web Components 标准
- **事件系统**：完整的事件发射器模式
- **拖拽交互**：原生鼠标事件处理
- **动画效果**：CSS transition 实现

## 📄 许可证

MIT License