# ColorPicker

**Repository Path**: anyline/color-picker

## Basic Information

- **Project Name**: ColorPicker
- **Description**: 颜色选择器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ColorPicker - Chrome 风格颜色选择器插件

> 一个独立、轻量级、完全仿照 Chrome 浏览器的颜色选择器

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/your-repo/color-picker)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Size](https://img.shields.io/badge/gzip%20size-~5KB-orange.svg)](https://github.com/your-repo/color-picker)

## ✨ 特性

### 🎨 Chrome 风格设计
- **1:1 复刻布局**：完全仿照 Chrome 浏览器的颜色选择器布局和交互
- **大面积色板**：200×200 像素的饱和度/亮度调节区域
- **垂直色相滑块**：20×200 像素的色相条，带白色光标
- **简洁设计**：无冗余元素，专注于核心功能

### 🖱️ 流畅交互
- **拖拽调节**：色板和色相滑块支持鼠标拖拽
- **实时预览**：所有颜色操作实时反馈
- **回车确认**：HEX 输入框支持回车键快速确认
- **光标跟随**：拖动时光标平滑跟随，提供精确反馈

### 📝 多格式支持
- **HEX 输入**：
  - 完整格式：`#FF5733` 或 `FF5733`（自动补全#号）
  - 简写格式：`#F00` 或 `F00`（自动转换为`#FF0000`）
- **RGB 输入**：分别控制 R、G、B 三个通道（0-255）
- **HSL 输入**：分别控制色相、饱和度、亮度

### 🎯 丰富功能
- **预设颜色**：内置 50 个精心挑选的预设颜色，点击快速选择
- **格式互转**：支持 HEX、RGB、HSL 三种格式的相互转换
- **深色主题**：自动适配系统深色主题
- **响应式设计**：自动适配移动端屏幕
- **验证反馈**：无效输入时边框变红并抖动提示

### 🚀 开发友好
- **轻量级**：压缩后仅 ~5KB，无任何依赖
- **API 丰富**：完整的 API 接口，易于集成
- **零冲突**：使用 `cpp-` 前缀的类名，避免样式冲突
- **ES6+**：使用现代 JavaScript 特性

## 📦 安装

### 方式一：直接引入

```html
<!-- 引入样式文件 -->
<link rel="stylesheet" href="ColorPicker.css">

<!-- 引入脚本文件 -->
<script src="ColorPicker.js"></script>
```

### 方式二：ES Module（推荐）

```javascript
import ColorPicker from './ColorPicker.js';
```

### 方式三：UMD

```html
<script src="https://unpkg.com/color-picker-plugin@1.0.0/dist/ColorPicker.js"></script>
```

## 🚀 快速开始

### 基础用法

```javascript
// 创建颜色选择器实例
const picker = new ColorPicker({
    initialColor: '#FF5733',
    onColorSelect: (color) => {
        console.log('选择的颜色:', color);
    }
});

// 打开颜色选择器
picker.open();
```

### 与按钮绑定

```html
<button id="colorButton">选择颜色</button>
<div id="colorPreview"></div>

<script>
    const button = document.getElementById('colorButton');
    const preview = document.getElementById('colorPreview');
    
    const picker = new ColorPicker({
        initialColor: '#3B82F6',
        onColorSelect: (color) => {
            preview.style.backgroundColor = color;
            button.style.color = color;
        }
    });
    
    button.addEventListener('click', () => {
        picker.open();
    });
</script>
```

### 快速打开（单例模式）

```javascript
ColorPicker.open({
    initialColor: '#667eea',
    onColorSelect: (color) => {
        console.log('选择了:', color);
    }
});
```

## 📚 API 文档

### 构造函数选项

```javascript
new ColorPicker(options)
```

#### 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `initialColor` | String | `'#000000'` | 初始颜色值（HEX 格式） |
| `position` | String | `'center'` | 弹出位置：`'center'` \| `'top'` \| `'bottom'` |
| `zIndex` | Number | `1000` | 遮罩层的 z-index 值 |
| `showPresetColors` | Boolean | `true` | 是否显示预设颜色网格 |
| `presetColors` | Array | 预设色板 | 自定义预设颜色数组 |
| `onColorSelect` | Function | `null` | 颜色选择回调函数 |
| `onOpen` | Function | `null` | 打开颜色选择器回调 |
| `onClose` | Function | `null` | 关闭颜色选择器回调 |
| `className` | String | `''` | 自定义 CSS 类名 |
| `width` | String | `'320px'` | 容器宽度 |
| `theme` | String | `'light'` | 主题：`'light'` \| `'dark'` |

### 实例方法

#### `open(options)`

打开颜色选择器

```javascript
picker.open({
    initialColor: '#FF0000',
    onColorSelect: (color) => {
        console.log('选择了:', color);
    }
});
```

#### `close()`

关闭颜色选择器

```javascript
picker.close();
```

#### `getColor()`

获取当前选中的颜色（HEX 格式）

```javascript
const color = picker.getColor();
console.log(color); // '#FF5733'
```

#### `setColor(color)`

设置颜色

```javascript
picker.setColor('#00FF00');
```

#### `getRGB()`

获取当前颜色的 RGB 值

```javascript
const rgb = picker.getRGB();
console.log(rgb); // { r: 255, g: 87, b: 51 }
```

#### `setRGB(r, g, b)`

设置 RGB 颜色值

```javascript
picker.setRGB(255, 0, 0); // 设置为红色
```

#### `getHSL()`

获取当前颜色的 HSL 值

```javascript
const hsl = picker.getHSL();
console.log(hsl); // { h: 15, s: 100, l: 60 }
// h: 0-360 (色相), s: 0-100 (饱和度), l: 0-100 (亮度)
```

#### `setHSL(h, s, l)`

设置 HSL 颜色值

```javascript
picker.setHSL(120, 100, 50); // 设置为纯绿色
```

#### `setSaturation(saturation)`

设置饱和度值（0-100）

```javascript
picker.setSaturation(80);
```

#### `getSaturation()`

获取饱和度值

```javascript
const saturation = picker.getSaturation(); // 返回 80
```

#### `destroy()`

销毁颜色选择器实例，释放资源

```javascript
picker.destroy();
```

### 静态方法

#### `ColorPicker.open(options)`

快速打开一次性颜色选择器（无需手动创建实例）

```javascript
ColorPicker.open({
    initialColor: '#3B82F6',
    onColorSelect: (color) => {
        console.log('选择:', color);
    }
});
```

## 🎨 使用示例

### 示例 1：表单颜色选择

```html
<div class="form-group">
    <label>选择颜色</label>
    <div class="color-input-wrapper">
        <input type="text" id="colorInput" value="#3B82F6" readonly>
        <div id="colorDisplay" style="background-color: #3B82F6;"></div>
        <button id="openPicker">选择</button>
    </div>
</div>

<script>
    const input = document.getElementById('colorInput');
    const display = document.getElementById('colorDisplay');
    const button = document.getElementById('openPicker');
    
    const picker = new ColorPicker({
        initialColor: '#3B82F6',
        onColorSelect: (color) => {
            input.value = color;
            display.style.backgroundColor = color;
        }
    });
    
    button.addEventListener('click', () => {
        picker.open({
            initialColor: input.value
        });
    });
</script>
```

### 示例 2：自定义预设颜色

```javascript
const customColors = [
    '#FF6B6B', '#4ECDC4', '#45B7D1', '#FFA07A',
    '#98D8C8', '#F7DC6F', '#BB8FCE', '#85C1E2',
    '#E8F8F5', '#FEF9E7', '#F4ECF7', '#EBF5FB'
];

const picker = new ColorPicker({
    presetColors: customColors,
    onColorSelect: (color) => {
        document.body.style.backgroundColor = color;
    }
});
```

### 示例 3：深色主题

```javascript
const picker = new ColorPicker({
    theme: 'dark',
    position: 'top',
    onColorSelect: (color) => {
        console.log('深色主题选择了:', color);
    }
});
```

### 示例 4：实时预览

```html
<div class="preview-container">
    <div id="previewBox" style="background-color: #3B82F6;">
        <span>点击修改颜色</span>
    </div>
</div>

<script>
    const previewBox = document.getElementById('previewBox');
    
    const picker = new ColorPicker({
        initialColor: '#3B82F6',
        onColorSelect: (color) => {
            previewBox.style.backgroundColor = color;
        }
    });
    
    previewBox.addEventListener('click', () => {
        picker.open({
            initialColor: previewBox.style.backgroundColor
        });
    });
</script>
```

### 示例 5：响应式颜色选择器

```javascript
const picker = new ColorPicker({
    width: '100%',
    position: window.innerWidth < 480 ? 'bottom' : 'center',
    onOpen: () => {
        console.log('颜色选择器已打开');
    },
    onClose: () => {
        console.log('颜色选择器已关闭');
    }
});

// 窗口大小改变时更新弹出位置
window.addEventListener('resize', () => {
    picker.options.position = window.innerWidth < 480 ? 'bottom' : 'center';
});
```

### 示例 6：颜色格式转换

```javascript
// HEX 转 RGB
const rgb = picker.getRGB();
console.log(`RGB(${rgb.r}, ${rgb.g}, ${rgb.b})`);

// HEX 转 HSL
const hsl = picker.getHSL();
console.log(`HSL(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`);

// RGB 转 HEX
picker.setRGB(255, 0, 0);
const hex = picker.getColor();
console.log(hex); // '#FF0000'

// HSL 转 HEX
picker.setHSL(120, 100, 50);
const hex = picker.getColor();
console.log(hex); // '#00FF00'
```

## 🔧 高级功能

### HEX 输入支持

颜色选择器支持多种 HEX 格式输入：

```javascript
// 完整 6 位格式
picker.setColor('#FF5733');

// 3 位简写格式（自动转换为 6 位）
picker.setColor('#F00'); // 等同于 #FF0000

// 不带 # 号（自动补全）
picker.setColor('FF5733');
```

### 颜色格式转换

```javascript
// HEX 转 RGB
const rgb = picker.getRGB();
// { r: 255, g: 87, b: 51 }

// HEX 转 HSL
const hsl = picker.getHSL();
// { h: 15, s: 100, l: 60 }

// RGB 转 HEX
picker.setRGB(255, 0, 0);
const hex = picker.getColor();
// '#FF0000'

// HSL 转 HEX
picker.setHSL(120, 100, 50);
const hex = picker.getColor();
// '#00FF00'
```

### 事件监听

```javascript
const picker = new ColorPicker({
    onOpen: () => {
        console.log('打开颜色选择器');
    },
    onClose: () => {
        console.log('关闭颜色选择器');
    },
    onColorSelect: (color) => {
        console.log('选择了颜色:', color);
    }
});
```

## 🎯 界面布局

颜色选择器采用 Chrome 风格的垂直布局：

```
┌─────────────────────────────┐
│  颜色选择          [×]      │  ← 标题栏
├─────────────────────────────┤
│  ┌──────────┐  #FF5733      │  ← 预览 + HEX 输入
│  │  色板    │              │
│  │          │              │
│  │    ●     │   R: 255     │  ← RGB 输入
│  │          │   G: 87      │
│  └────┬─────┘   B: 51      │
│       │                     │
│  ┌────▼─────┐   预设颜色   │  ← 色相滑块
│  │  色相条  │  ■ ■ ■ ■    │
│  │    ───   │  ■ ■ ■ ■    │
│  └──────────┘  ■ ■ ■ ■    │
└─────────────────────────────┘
```

## 🌐 浏览器兼容性

| 浏览器 | 版本 | 支持状态 |
|--------|------|----------|
| Chrome | 60+ | ✅ 完全支持 |
| Firefox | 55+ | ✅ 完全支持 |
| Safari | 12+ | ✅ 完全支持 |
| Edge | 79+ | ✅ 完全支持 |
| Opera | 47+ | ✅ 完全支持 |
| IE | - | ❌ 不支持 |

## 🎨 样式自定义

### 自定义容器样式

可以通过 CSS 类名自定义样式：

```css
/* 自定义容器样式 */
.color-picker-plugin-container.custom-theme {
    border-radius: 16px;
    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.4);
}

/* 自定义预设颜色 */
.cpp-color-swatch {
    border-radius: 50%;
    transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
}

.cpp-color-swatch:hover {
    transform: scale(1.3);
}
```

然后在创建实例时传入：

```javascript
const picker = new ColorPicker({
    className: 'custom-theme'
});
```

### 覆盖默认样式

```css
/* 覆盖容器宽度 */
.color-picker-plugin-container {
    width: 400px !important;
}

/* 自定义标题栏 */
.cpp-modal-header {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

/* 自定义确定按钮 */
.cpp-btn-primary {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
```

## 🔍 常见问题

### Q: 如何获取当前选中的颜色？

```javascript
const color = picker.getColor();
```

### Q: 如何设置初始颜色？

```javascript
const picker = new ColorPicker({
    initialColor: '#3B82F6'
});
```

### Q: 支持哪些颜色格式？

- **HEX**: `#FF5733`, `#F00` (3位简写), `FF5733` (无#号)
- **RGB**: `{ r: 255, g: 87, b: 51 }`
- **HSL**: `{ h: 15, s: 100, l: 60 }`

### Q: 如何自定义预设颜色？

```javascript
const picker = new ColorPicker({
    presetColors: ['#FF6B6B', '#4ECDC4', '#45B7D1']
});
```

### Q: 如何改变弹出位置？

```javascript
const picker = new ColorPicker({
    position: 'top' // 'center' | 'top' | 'bottom'
});
```

### Q: HEX 输入框支持哪些格式？

```javascript
// 支持以下格式：
picker.setColor('#FF5733');  // 完整格式
picker.setColor('FF5733');   // 不带 # 号
picker.setColor('#F00');     // 3 位简写
picker.setColor('F00');      // 不带 # 号的 3 位简写
```

### Q: 如何监听打开和关闭事件？

```javascript
const picker = new ColorPicker({
    onOpen: () => {
        console.log('颜色选择器已打开');
    },
    onClose: () => {
        console.log('颜色选择器已关闭');
    }
});
```

### Q: 如何验证输入的颜色是否有效？

颜色选择器会自动验证 HEX 输入：

- 有效输入：立即应用颜色
- 无效输入：边框变红并抖动，恢复当前颜色值

### Q: 如何在移动端使用？

颜色选择器自动适配移动端，无需额外配置：

```javascript
const picker = new ColorPicker({
    // 自动适配移动端屏幕
    width: '100%'
});
```

## 📁 项目结构

```
.
├── ColorPicker.js       # 插件主文件（~700 行）
├── ColorPicker.css      # 样式文件（~400 行）
├── plugin-demo.html     # 演示页面
├── README.md           # 使用说明
└── image.png           # 效果预览图
```

## 🔧 开发

### 修改预设颜色

编辑 `ColorPicker.js` 文件中的 `PRESET_COLORS` 数组：

```javascript
const PRESET_COLORS = [
    '#1a1a1a', '#4a4a4a', '#7a7a7a', '#aaaaaa', '#d4d4d4',
    '#e53935', '#ef5350', '#ef9a9a', '#ffcdd2', '#ff8a80',
    // 添加更多自定义颜色...
];
```

### 修改默认配置

编辑 `ColorPicker.js` 文件中的 `DEFAULT_OPTIONS` 对象：

```javascript
const DEFAULT_OPTIONS = {
    initialColor: '#000000',
    position: 'center',
    zIndex: 1000,
    showPresetColors: true,
    theme: 'light',
    // 修改默认配置...
};
```

### 自定义样式

编辑 `ColorPicker.css` 文件，添加或修改样式规则。

## 📝 更新日志

### v1.0.0 (2024-03-20)

- ✨ 初始版本发布
- 🎨 Chrome 风格布局
- 🖱️ 拖拽调节功能
- 📝 HEX/RGB/HSL 多格式支持
- 🌓 深色主题支持
- 📱 响应式设计
- 🎯 50 个预设颜色

## 📄 许可证

MIT License

Copyright (c) 2026 ColorPicker Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📞 联系方式

- GitHub Issues: [提交问题](https://github.com/your-repo/color-picker/issues)
- Email: server@anyline.org
- 官网: https://www.anyline.org

## 🙏 致谢

- 灵感来源于 Chrome 浏览器的原生颜色选择器
- 感谢所有贡献者的支持

---