别再手搓调色板了:Vue 3 一个组件搞定纯色、渐变和画布吸管取色

0 阅读8分钟

cover.png

先说个真实场景。

产品经理指着设计稿说:“这里加个颜色设置,要能选纯色、能调渐变、还要能从画布上直接吸颜色。”

你打开项目一看:

  • 原生 input[type=color] 长得丑还改不了;
  • vue-color 只有色板没有吸管;
  • 渐变编辑又是另一个库;
  • 最近使用颜色还得自己拿 localStorage 存一遍……

于是三个库、两套状态、一堆边界 bug,一周就没了。

我干脆把之前做可视化项目时反复打磨的那套取色能力抽出来,做成了一个独立的 Vue 3 组件库,现在开源了,MIT 协议,开箱即用。

下面就用图文的方式,把它能干什么、怎么接、有哪些坑,一次讲清楚。


一、它到底解决了什么问题

这个库对外就三个组件:

组件作用
ColorPicker调色板:纯色 / 线性渐变、最近使用、取色入口
EyeDropper画布取色:截图 + 放大镜,点哪吸哪
SliderColorSetting渐变色标条,支持增删色标、拖拽、角度旋转、色序翻转

再配一组工具函数和组合式 API:颜色解析转换、渐变解析、最近颜色、取色会话。

先看个整体效果:

demo-overview.png

和市面上常见的方案相比,它有几个比较实在的点:

  1. 纯色和渐变在同一个面板里,不用为了渐变再引一个库;
  2. 自带画布取色,不依赖浏览器原生 EyeDropper API,走截图采样,不用等某个内核支持;
  3. 不绑 Pinia、不绑 JWT、不绑你的 store,getUserId 由宿主传进来;
  4. SSR 能渲染,不会因为直接访问 window 在服务端炸掉;
  5. 样式可换肤,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 是必填的,而且要在组件生命周期内保持稳定唯一。它用来做多实例互斥——同一个页面同时只允许打开一个调色板,避免两个浮层叠在一起。


三、纯色面板:比原生颜色选择器多的东西

默认展开是这样:

palette-solid.png

看起来像 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 的其他色彩空间,这些需要宿主先转成标准值再传进来。


四、线性渐变:多色标 + 角度 + 翻转

切到“线性渐变”,面板会多出一条色标编辑区:

palette-gradient.png

能做的事:

  • 在色标条上点击新增色标,拖动改位置;
  • 中间色标右键删除(端点删不掉);
  • 改任意色标的颜色,画布实时更新;
  • 输入角度,或者点按钮顺时针转 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.png

实现上不是调浏览器的 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,矩形边框也跟着变了:

picked-back.png

取色过程中支持 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 格。

两个细节:

  1. 未登录不持久化。getUserId() 返回空串时只在内存里用,不会写本地存储;
  2. 按用户隔离。同一个 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
JS71.81 kB20.92 kB
CSS12.80 kB3.62 kB

对一个带截图取色、渐变编辑、历史记录的组件库来说,这个体积还算克制。注意这是库本身的产物,不含 Element Plus。

测试方面,仓库现在有 15 个测试文件、196 个自动化用例,覆盖颜色解析、坐标映射、SSR、键盘交互、tarball 消费等;pnpm verify 会依次跑测试、类型检查、示例构建和真实 npm 包消费。

但也要把没覆盖到的地方讲清楚,免得你踩坑:

  • 真实浏览器验收目前主要是在 Chrome 上做的,Safari / Firefox、触屏、屏幕阅读器还没系统验证;
  • 颜色解析不支持 var()、calc()、径向渐变和其他 CSS Color 4 色彩空间;
  • 矩形渐变边框只处理横向矩形,不处理圆角、SVG 和 Canvas 宿主边框;
  • snapdom 是截图方案,超大页面或者复杂动效场景需要你自己压测一下。

如果你只是想要一个“能选颜色”的输入框,说实话原生控件就够了。但如果你在做设计器、低代码、大屏可视化、图表配置这类东西,这个库能帮你省掉不少重复劳动。


十、最后

项目地址再放一次:

MIT 协议,随便用。如果它帮你少写了一个调色板,点个 Star 就是最大的支持;遇到问题或者想要新功能,直接提 Issue,我尽量回。

也欢迎在评论区聊聊:你现在项目里的颜色选择器,是怎么解决的?