先说个真实场景。
产品经理指着设计稿说:“这里加个颜色设置,要能选纯色、能调渐变、还要能从画布上直接吸颜色。”
你打开项目一看:
- 原生
input[type=color]长得丑还改不了; vue-color只有色板没有吸管;- 渐变编辑又是另一个库;
- 最近使用颜色还得自己拿 localStorage 存一遍……
于是三个库、两套状态、一堆边界 bug,一周就没了。
我干脆把之前做可视化项目时反复打磨的那套取色能力抽出来,做成了一个独立的 Vue 3 组件库,现在开源了,MIT 协议,开箱即用。
- 在线示例:you-want.github.io/color-picke…
- GitHub:github.com/you-want/co…
- npm:
@you-want/color-picker-lib(当前 0.2.6)
下面就用图文的方式,把它能干什么、怎么接、有哪些坑,一次讲清楚。
一、它到底解决了什么问题
这个库对外就三个组件:
| 组件 | 作用 |
|---|---|
ColorPicker | 调色板:纯色 / 线性渐变、最近使用、取色入口 |
EyeDropper | 画布取色:截图 + 放大镜,点哪吸哪 |
SliderColorSetting | 渐变色标条,支持增删色标、拖拽、角度旋转、色序翻转 |
再配一组工具函数和组合式 API:颜色解析转换、渐变解析、最近颜色、取色会话。
先看个整体效果:
和市面上常见的方案相比,它有几个比较实在的点:
- 纯色和渐变在同一个面板里,不用为了渐变再引一个库;
- 自带画布取色,不依赖浏览器原生 EyeDropper API,走截图采样,不用等某个内核支持;
- 不绑 Pinia、不绑 JWT、不绑你的 store,
getUserId由宿主传进来; - SSR 能渲染,不会因为直接访问
window在服务端炸掉; - 样式可换肤,5 个 CSS 变量覆盖主题。
二、30 秒接进项目
安装:
pnpm add @you-want/color-picker-lib vue element-plus
peer 依赖只有两个:vue ^3.5.0 和 element-plus >=2.6.0。
在入口注册 Element Plus,并显式导入库的样式:
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import '@you-want/color-picker-lib/dist/assets/index.css'
import App from './App.vue'
createApp(App).use(ElementPlus).mount('#app')
这一步容易踩坑:只 import 组件 JS 是不会加载调色板布局样式的,面板会变成一堆裸元素。
最小用法就这么点:
<script setup lang="ts">
import { ref } from 'vue'
import { ColorPicker } from '@you-want/color-picker-lib'
const color = ref('#316BFF')
</script>
<template>
<ColorPicker id="theme-color" v-model="color" />
</template>
注意 id 是必填的,而且要在组件生命周期内保持稳定唯一。它用来做多实例互斥——同一个页面同时只允许打开一个调色板,避免两个浮层叠在一起。
三、纯色面板:比原生颜色选择器多的东西
默认展开是这样:
看起来像 SketchPicker?底层确实用的是 vue-color 的 SketchPicker,但外面补了一圈实际业务里真正会用到的东西:
- 面板内提供 HEX 和 R/G/B/A 输入框,支持带 alpha;解析层覆盖 HEX、RGB(A)、HSL(A)、HSV(A)、CSS 色名等格式;
- 预设色板可替换;
- 最近使用颜色,最多 15 条历史 + 1 格当前色 = 16 格;
- 面板里的吸管按钮,直接进画布取色;
- 键盘可操作:方向键调整、Escape 关闭并把焦点还给触发按钮;
- 触发器支持自定义插槽,
#trigger想放什么放什么。
不支持的也提前说清楚:var()、calc()、像素色标、径向渐变、CSS Color 4 的其他色彩空间,这些需要宿主先转成标准值再传进来。
四、线性渐变:多色标 + 角度 + 翻转
切到“线性渐变”,面板会多出一条色标编辑区:
能做的事:
- 在色标条上点击新增色标,拖动改位置;
- 中间色标右键删除(端点删不掉);
- 改任意色标的颜色,画布实时更新;
- 输入角度,或者点按钮顺时针转 90°;
- 一键翻转渐变色序;
- 只想要首尾两个色标?传
gradient-without-anchors。
对应代码:
<script setup lang="ts">
import { ref } from 'vue'
import { ColorPicker, type ColorStop } from '@you-want/color-picker-lib'
const source = ref('linear-gradient(90deg, #ff0000 0%, #00ff00 35%, #0000ff 100%)')
const opacity = ref(100)
const stops = ref<ColorStop[]>([])
</script>
<template>
<ColorPicker
id="border-color"
v-model="source"
v-model:fill-opacity="opacity"
:slider-buttons="stops"
@change-color-set="stops = $event"
/>
</template>
v-model 拿到的是标准 CSS 字符串,可以直接丢给 background、边框、Canvas 或者 Konva。
这里有个设计上的取舍值得说一下:色标集合永远以新数组回写宿主。因为很多画布库(比如 Konva)是靠数组引用变化来触发重绘的,你如果就地 push/splice 再传回原数组,画布根本不鸟你。这个坑我踩过,所以库内部统一改成新引用。
五、画布取色:截图 + 放大镜,指哪打哪
这是这个库跟普通调色板最大的区别。
点面板里的吸管按钮,整个画布区域进入取色态,鼠标旁边出现一个 200×200 的放大镜:
实现上不是调浏览器的 EyeDropper API,而是用 snapdom 把目标区域截成图,再按屏幕坐标去 Canvas 里采样。好处是:
- 理论上只要 Canvas 可用就能工作,不用等原生 API(当前实测以 Chrome 为主);
- 可以指定
target,只截某块画布,不用截整个页面; - 放大镜固定 13×13 格,每格对应 1 个 CSS 像素,中心高亮格就是实际采样点;
- 支持
[data-eyedropper-exclude]排除不想被截进去的元素。
宿主侧接入分四步,代码不长:
<script setup lang="ts">
import { ref } from 'vue'
import { ColorPicker, EyeDropper, useColorPickerSession } from '@you-want/color-picker-lib'
const color = ref('#316BFF')
const canvasEl = ref<HTMLElement | null>(null)
const pickerRef = ref<InstanceType<typeof ColorPicker> | null>(null)
// 取色会话:pick-request → 挂载 EyeDropper → confirm 回填
const session = useColorPickerSession()
function onPickRequest(req: { pickerId: string; color: string }) {
session.onPickRequest(req)
}
function onPickConfirm(hex: string) {
const pickerId = session.onPickConfirm(hex)
if (pickerId) {
pickerRef.value?.applyPickedColor(hex)
}
}
</script>
<template>
<div ref="canvasEl">
<!-- 你的画布、图表、设计稿,随便什么 DOM -->
</div>
<ColorPicker
id="picker-1"
ref="pickerRef"
v-model="color"
@pick-request="onPickRequest"
/>
<!-- pending 非空时才挂载取色浮层 -->
<EyeDropper
v-if="session.pending.value"
:target="canvasEl!"
@confirm="onPickConfirm"
@close="session.onPickClose"
/>
</template>
吸完确认之后,颜色会回填到当前激活的色标。看下面这张,渐变第一个色标被吸成了画布背景的 #0B1020,矩形边框也跟着变了:
取色过程中支持 Escape、右键、退出按钮、点击画布外四种取消方式;取消不会改色,下次还能继续吸。
还有一个细节:截图不是一次性快照目标矩形,而是每次移动都按最新的 getBoundingClientRect() 换算坐标。所以画布平移、滚动、容器动画之后,取色点也不会飘。
六、绕不开的坑:整体透明度和“有效颜色”
做设计器一定会遇到这个需求:渐变本身有色标 alpha,外面还要再叠一个“整体透明度”。
如果直接把两个 alpha 乘在一起,数据就会污染:用户把整体透明度拉到 0%,再拉回 100%,原来的色标 alpha 全没了。
这个库的做法是把两者分开:
v-model永远保存原始颜色,色标 alpha 不动;fill-opacity单独存整体透明度,0–100;effective-change事件给你最终渲染值。
<ColorPicker
id="border-picker"
v-model="source"
v-model:fill-opacity="opacity"
@effective-change="rendered = $event.color"
/>
这里有一条硬规则:画布渲染只消费 effectiveChange.color,不要再自己乘一次透明度。否则就是经典的“透明度平方”,颜色会越来越淡。
顺带还带了个矩形渐变边框的工具函数:
import { horizontalGradientBorderStyle } from '@you-want/color-picker-lib'
<div :style="horizontalGradientBorderStyle(rendered, 8)">
矩形内容
</div>
它会把多色标按水平方向展开,上下边同向同尺寸,左右边取端点色,四角不会重复叠加 alpha。做低代码画布、大屏边框的时候很省事。
七、最近使用颜色:多用户隔离,别串号
历史颜色默认存 localStorage,键是 recenterlyUseColor:v2,最多 15 条,加上当前色一共 16 格。
两个细节:
- 未登录不持久化。
getUserId()返回空串时只在内存里用,不会写本地存储; - 按用户隔离。同一个
storageKey下不同用户各存各的,不会出现 A 用户看到 B 用户历史的情况。
<ColorPicker
id="theme-color"
v-model="color"
:get-user-id="() => currentUser.id"
storage-key="my-app:recent-colors"
/>
登录态变化时,库会先把旧用户的编辑结清,再关面板、取消取色、刷新历史。不会把 A 的编辑记到 B 头上。
另外 session-commit 只在“关闭面板或卸载且本轮有改动”时触发一次,适合拿来做埋点或者真正提交到后端,不会在你拖动色盘的时候疯狂发请求。
八、几个开发时踩出来的坑,顺手也修了
这部分是给喜欢看实现细节的朋友准备的,也是这个库迭代到 0.2.6 过程中比较有意思的地方。
1. 吸管光标和取样点差了 13 像素
换用一套 14×14 的 SVG 吸管光标时,CSS cursor 的 hotspot 填成了 13 1,也就是吸管尾部。用户看到笔尖在左下角,实际采样点却在右上角,整整偏了 13px。
改成 0 14 之后笔尖才对上。这个问题用脚本合成鼠标事件测不出来,因为合成事件不经过光标渲染层,只有真人拿鼠标吸才发现。
2. 渐变双向不同步
面板里增删色标,画布上的锚点不刷新;画布上拖色标,面板里的数据又是旧的。根因还是数组引用和事件桥接。最后统一成“始终回写新数组 + 补齐画布与面板之间的事件桥”,才算彻底解决。
3. 深色模式下单选按钮“消失”
调色板本身是浅色面板,但 Element Plus 的深色变量把“纯色 / 线性渐变”的文字和圆点也变成了浅色,白底白字,直接看不见。修复方式是把这个区域固定成浅色主题配色,选中态继续用主色。
4. 最新颜色重复出现两格
0.2.6 修的一个小 bug:当前色固定占第一格,历史里如果也有同一个颜色,就会重复渲染。现在按颜色语义去重——纯色比 RGBA,渐变比方向 + 色标,当前色仍然固定第一格。
九、体积、测试和边界,实话实说
当前 0.2.6 的构建产物:
| 产物 | 大小 | gzip |
|---|---|---|
| JS | 71.81 kB | 20.92 kB |
| CSS | 12.80 kB | 3.62 kB |
对一个带截图取色、渐变编辑、历史记录的组件库来说,这个体积还算克制。注意这是库本身的产物,不含 Element Plus。
测试方面,仓库现在有 15 个测试文件、196 个自动化用例,覆盖颜色解析、坐标映射、SSR、键盘交互、tarball 消费等;pnpm verify 会依次跑测试、类型检查、示例构建和真实 npm 包消费。
但也要把没覆盖到的地方讲清楚,免得你踩坑:
- 真实浏览器验收目前主要是在 Chrome 上做的,Safari / Firefox、触屏、屏幕阅读器还没系统验证;
- 颜色解析不支持
var()、calc()、径向渐变和其他 CSS Color 4 色彩空间; - 矩形渐变边框只处理横向矩形,不处理圆角、SVG 和 Canvas 宿主边框;
snapdom是截图方案,超大页面或者复杂动效场景需要你自己压测一下。
如果你只是想要一个“能选颜色”的输入框,说实话原生控件就够了。但如果你在做设计器、低代码、大屏可视化、图表配置这类东西,这个库能帮你省掉不少重复劳动。
十、最后
项目地址再放一次:
- GitHub:github.com/you-want/co…
- 在线体验:you-want.github.io/color-picke…
- 安装:
pnpm add @you-want/color-picker-lib
MIT 协议,随便用。如果它帮你少写了一个调色板,点个 Star 就是最大的支持;遇到问题或者想要新功能,直接提 Issue,我尽量回。
也欢迎在评论区聊聊:你现在项目里的颜色选择器,是怎么解决的?