x-color-picker

组件名称: x-color-picker

Github 仓库: https://github.com/TheXiong/vue3-colorPicker

1. 组件概述

x-color-picker 是一款基于 Vue 3 + TypeScript 开发的高级颜色选择器组件。它不仅支持标准的单色（Solid）选择，还内置了强大的渐变色（Gradient）编辑功能。组件集成了透明度调节、HSV/RGB/HEX 格式切换、系统预设颜色面板以及智能的“最近使用颜色”记录功能。其设计目标是为开发者提供一个开箱即用、交互流畅且高度可配置的色彩解决方案，适用于各类设计工具、后台管理系统及个性化配置场景。

技术依赖:

• Vue: ^3.5.24

效果预览

单色模式	渐变模式

---

2. 能力说明

功能模块	功能点	说明
色彩模式	单色/渐变切换	支持纯色、线性渐变（Linear Gradient）及径向渐变（Radial Gradient）的无缝切换与编辑。
色彩空间	多格式支持	支持 HEX、RGB(A)、CSS 格式输入输出；内部使用 HSV 模型保证色彩计算精度。
透明度	Alpha 通道	提供独立的透明度滑块，支持 0-100% 透明度调节。
交互体验	拖拽操作	饱和度面板、色相带、透明度带及渐变轴均支持流畅的拖拽交互，采用 RAF 优化性能。
预设管理	系统预设	内置 20 种常用标准色，支持通过 Props 自定义。
历史记录	最近使用颜色	自动记录用户最近选择的颜色，支持去重、持久化存储（LocalStorage）、最大数量限制及一键清除。
渐变编辑	多色标支持	支持添加(双击)、删除(右击)、拖拽渐变色标（Stop），可调节渐变角度（仅线性）或切换渐变类型。

性能特征:

• 高性能渲染: 拖拽交互均使用 requestAnimationFrame 进行节流处理，避免高频 DOM 操作导致的卡顿。
• 按需更新: 仅在必要时更新 DOM 和触发计算属性。

限制条件:

• 即使关闭 enableAlpha，内部计算仍保留 Alpha 通道，输出时会根据格式自动截断。
• 径向渐变（Radial Gradient）目前默认使用 circle at center 形状和位置，暂不支持复杂的形状/位置自定义配置（但可正确解析和显示）。

---

3. Props 规范

参数名	类型	必填	默认值	说明
modelValue	string	是	'#000000'	绑定的颜色值，支持 v-model。可以是 HEX、RGBA 或 CSS 渐变字符串。
defaultColor	string	否	'#000000'	当 modelValue 为空时的回退颜色。
enableAlpha	boolean	否	true	是否启用透明度（Alpha）滑块及输出支持。
format	'HEX' | 'RGB'	否	'HEX'	颜色输出格式。⚠️ 注意：渐变模式下始终输出 CSS 渐变字符串。
swatchColors	string[]	否	[...]	系统预设颜色列表。默认包含 20 种常用色。
recentColors	string[]	否	[]	初始最近使用颜色列表。
enableRecentColors	boolean	否	true	是否启用“最近使用颜色”功能。
maxCount	number	否	10	最近使用颜色的最大记录数量（1-20）。
clearable	boolean	否	false	是否显示清除按钮，点击可将颜色值重置为空字符串。
zIndex	number	否	2000	弹出面板的 z-index 层级。
placement	string	否	'bottom-start'	弹出面板位置。可选：bottom-start, bottom-end, top-start, top-end。
threshold	number	否	20	边缘检测阈值（像素），用于自动调整弹出位置。
animationDuration	number	否	200	面板显示/隐藏动画时长（毫秒）。
overlay	boolean	否	false	是否显示全局遮罩层。
showText	boolean	否	true	触发器是否显示颜色文本值。
theme	'dark' | 'light'	否	'dark'	主题设置。
useType	'pure' | 'gradient' | 'both'	否	'both'	模式限制。pure: 仅纯色; gradient: 仅渐变; both: 两者。

复杂 Props 示例

swatchColors:

const mySwatches = [
  '#FF0000', 
  'rgba(0, 255, 0, 0.5)', 
  'linear-gradient(90deg, #000 0%, #fff 100%)' // 支持渐变预设
];

---

4. Emit 事件说明

事件名	回调参数	触发时机
update:modelValue	(value: string)	当颜色发生任何变化时实时触发（拖拽、输入、点击预设）。
change	(value: string)	当颜色选择面板关闭时触发。通常用于提交最终选择结果。
clear	()	点击清除按钮时触发。

---

5. 使用指南

基础使用

<script setup lang="ts">
import { ref } from 'vue';
import { XColorPicker } from 'x-color-picker';
import 'x-color-picker/dist/x-color-picker.css'; // 引入样式

const color = ref('#4096ff');

const handleChange = (val: string) => {
  console.log('最终选择颜色:', val);
};
</script>

<template>
  <XColorPicker 
    v-model="color" 
    @change="handleChange"
  />
</template>

高级配置

启用 RGB 格式输出并自定义最近使用记录数量：

<XColorPicker 
  v-model="color"
  format="RGB"
  :enable-alpha="true"
  :enable-recent-colors="true"
  :max-count="15"
/>

常见问题

Q: 渐变色字符串无法解析？ A: 组件支持标准的 CSS linear-gradient 和 radial-gradient 格式。请确保传入的字符串格式规范，例如 linear-gradient(90deg, ...) 或 radial-gradient(circle at center, ...)。

Q: 如何禁用最近使用颜色？ A: 设置 :enable-recent-colors="false" 即可隐藏该区域并停止记录。

---

扩展接口

组件导出了内部工具函数，可供二次开发使用：

import { 
  rgb2hex, 
  hsv2rgb, 
  parseGradient, 
  formatGradient 
} from 'x-color-picker';