Element Plus ColorPicker 颜色选择器完整指南：多格式色值、Alpha 通道与预定义色板

ColorPicker 是 Element Plus（Vue.js 3 UI Library）中用于颜色选择的表单组件，支持 hex、rgb、hsl、hsv 等十余种颜色格式，并可结合 Alpha 通道、预定义色板和表单校验工作。读完本文，你将掌握 ColorPicker 的完整 API 用法、show-alpha/color-format/predefine 等核心配置项的实战组合，并理解其底层基于 @ctrl/tinycolor 的颜色解析与格式化原理。

基本用法

ColorPicker 需要一个字符串类型的变量绑定到 v-model 上，绑定的字符串即当前选中的颜色值。

<template>
  <div class="demo-color-block">
    <span class="demonstration">With default value</span>
    <el-color-picker v-model="color1" />
  </div>
  <div class="demo-color-block">
    <span class="demonstration">With no default value</span>
    <el-color-picker v-model="color2" />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const color1 = ref('#409EFF')
const color2 = ref()
</script>

完整示例可查看 docs/examples/color-picker/basic.vue。当 v-model 未赋值时，触发按钮内会显示一个空色块占位图标（源码中由 close 图标渲染，见 color-picker.vue）；赋值后显示当前颜色及下拉箭头图标。

点击触发按钮打开下拉面板，面板内包含：

• SV 平面取色板（饱和度/明度）
• 色相（Hue）滑块
• 当前颜色预览与可输入的 Hex / RGB 输入框
• 底部"清除 / 确定"按钮

从源码结构看，这些 UI 分别由 sv-panel.vue、hue-slider.vue、alpha-slider.vue、predefine.vue 实现，均位于 packages/components/color-picker-panel/src/components/。

透明度（Alpha）通道

ColorPicker 支持 Alpha 通道选择。只需添加 show-alpha 属性，即可激活透明度滑块，同时触发按钮色块会呈现半透明效果（色块样式类名带 is-alpha 标记，见 color-picker.vue）。

<template>
  <el-color-picker v-model="color" show-alpha />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const color = ref('rgba(19, 206, 102, 0.8)')
</script>

示例见 docs/examples/color-picker/alpha.vue。

关键行为（结合源码）：开启 show-alpha 后，ColorPicker 的默认输出格式会从 hex 自动切换为 rgb。这一逻辑位于 Color 类的 doOnChange 方法：

let _format = format || (enableAlpha ? 'rgb' : 'hex')
if (format === 'hex' && enableAlpha) {
  _format = 'hex8'
}

即：未指定 color-format 时，enableAlpha 决定默认格式；若显式指定 color-format="hex" 且开启 Alpha，则格式会被自动升级为带透明度的 hex8（如 #c7158577），保证透明度信息不丢失。

预定义颜色

ColorPicker 支持通过 predefine 属性提供一组预定义颜色，用户可在面板顶部的预定义色块中快速选取。

<template>
  <el-color-picker v-model="color" show-alpha :predefine="predefineColors" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const color = ref('rgba(255, 69, 0, 0.68)')
const predefineColors = ref([
  '#ff4500',
  '#ff8c00',
  '#ffd700',
  '#90ee90',
  '#00ced1',
  '#1e90ff',
  '#c71585',
  'rgba(255, 69, 0, 0.68)',
  'rgb(255, 120, 0)',
  'hsv(51, 100, 98)',
  'hsva(120, 40, 94, 0.5)',
  'hsl(181, 100%, 37%)',
  'hsla(209, 100%, 56%, 0.73)',
  '#c7158577',
])
</script>

示例见 docs/examples/color-picker/predefined-color.vue。

可见 predefine 是 string<a href="https://link.gitcode.com/i/17df86e49fc37ad3114d795ef5248a91" target="_blank">] 类型，支持混合传入 hex、rgb、hsv、hsl 等不同格式的颜色字符串——组件内部统一通过 TinyColor 解析。当前值与预定义色相同时，对应色块会高亮显示"已选中"状态（选中态切换逻辑有对应测试覆盖，见 [color-picker.test.tsx）。

尺寸（Sizes）

ColorPicker 支持 large、default、small 三种尺寸，通过 size 属性设置；也可跟随外层 el-form 的 size 上下文自动继承（源码中通过 useFormSize() 获取尺寸，见 color-picker.vue）。

<template>
  <div class="demo-color-sizes">
    <el-color-picker v-model="color" size="large" />
    <el-color-picker v-model="color" />
    <el-color-picker v-model="color" size="small" />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const color = ref('#409EFF')
</script>

示例见 docs/examples/color-picker/sizes.vue。

API

Attributes（属性）

以下属性定义均可在 color-picker.ts 中核对。

名称	说明	类型	默认值
model-value / v-model	绑定值	string	—
disabled	是否禁用 ColorPicker	boolean	false
clearable ^(2.13.1)	是否显示清除按钮	boolean	true
size	尺寸	'large' | 'default' | 'small'	—
show-alpha	是否显示透明度滑块	boolean	false
color-format	v-model 的颜色格式	'rgb' | 'prgb' | 'hex' | 'hex3' | 'hex4' | 'hex6' | 'hex8' | 'name' | 'hsl' | 'hsv'	'hex'（未开启 show-alpha）/ 'rgb'（开启 show-alpha）
popper-class	下拉面板自定义类名	string / object	''
popper-style ^(2.11.4)	下拉面板自定义样式	string / object	—
predefine	预定义颜色选项	string[]	—
validate-event	是否触发表单校验	boolean	true
tabindex	ColorPicker 的 tabindex	string / number	0
aria-label ^(a11y) ^(2.7.2)	ColorPicker 的 aria-label	string	—
empty-values ^(2.10.3)	组件的空值集合，参见 config-provider 的 empty-values 配置	array	—
value-on-clear ^(2.10.3)	清除时的返回值，参见 config-provider 的 empty-values 配置	string / number / boolean / Function	—
id	ColorPicker 的 id	string	—
teleported ^(2.7.2)	下拉面板是否 teleport 到 body	boolean	true
label ^(a11y) ^(deprecated)	ColorPicker 的 aria-label（已废弃，改用 aria-label）	string	—
persistent ^(2.10.5)	面板非激活时是否保留（为 false 时销毁面板 DOM）	boolean	true
append-to ^(2.10.5)	面板挂载到的目标元素	CSSSelector / HTMLElement	-

重点属性解析（结合源码）：

• color-format：直接透传给底层的 Color 类作为输出格式。Color 内部维护 HSVA 四通道状态，fromString 时通过 TinyColor 解析任意合法颜色字符串并归一化为 HSVA（见 color.ts），输出时再按目标格式序列化（doOnChange）。因此你可以随时切换输出格式而无需关心用户当前面板操作的是哪个色彩空间。
• validate-event：默认 true。确认选择（confirmValue）或失焦（afterBlur）时会调用 formItem.validate('change'/'blur')，见 color-picker.vue。若 ColorPicker 置于 el-form-item 内且配置了校验规则，选中颜色即可触发校验。
• value-on-clear / empty-values：点击"清除"按钮时，v-model 会被置为 valueOnClear 的值（默认 undefined/空），而不是简单置空字符串，方便与表单空值体系统一。
• clearable：控制面板底部是否渲染"清除"按钮。测试用例验证了 clearable={false} 时不显示清除按钮（见 color-picker.test.tsx）。
• teleported / append-to / persistent：这三个属性均继承自 Tooltip 的弹层配置（useTooltipContentProps）。teleported 决定面板是否挂到 body（默认 true，可避免被父级 overflow: hidden 裁剪）；append-to 可指定挂载目标；persistent=false 时面板在关闭状态下会被销毁，适合追求极致内存占用的场景。

Events（事件）

事件发射定义见 color-picker.ts。

名称	说明	类型
change	输入值改变时触发（点击"确定"或清除时）	(value: string) => void
active-change	当前激活颜色改变时触发（面板中拖动取色时实时触发）	(value: string) => void
focus ^(2.4.0)	组件获得焦点时触发	(event: FocusEvent) => void
blur ^(2.4.0)	组件失去焦点时触发	(event: FocusEvent) => void
clear ^(2.13.1)	点击清除按钮时触发	() => void

change 与 active-change 的区别：active-change 在用户在面板中拖动 SV 板、滑动色相/透明度滑块时实时触发（由 watch currentColor 驱动，见 color-picker.vue）；而 change 仅在点击"确定"按钮（confirmValue）或"清除"按钮时与 update:modelValue 一同触发，此时 v-model 才真正提交。

Exposes（暴露的方法）

名称	说明	类型
color	当前颜色对象	Color
show ^(2.3.3)	手动打开 ColorPicker	() => void
hide ^(2.3.3)	手动关闭 ColorPicker	() => void
focus ^(2.3.13)	聚焦取色器触发元素	() => void
blur ^(2.3.13)	使取色器触发元素失焦	() => void

通过模板 ref 即可调用：

<script lang="ts" setup>
import { ref } from 'vue'
import type { ColorPickerInstance } from 'element-plus'

const colorPickerRef = ref<ColorPickerInstance>()

function openPicker() {
  colorPickerRef.value?.show()
}
</script>

<template>
  <el-color-picker ref="colorPickerRef" v-model="color" />
  <el-button @click="openPicker">打开取色器</el-button>
</template>

color 对象说明：它对外暴露 Color 类实例（定义于 color.ts），内部维护 _hue、_saturation、_value、_alpha 四个通道，并提供 toRgb()、fromString()、set()、get()、compare() 等方法，可满足编程式读写颜色的需求。

无障碍与键盘操作

• 组件根元素具备 role="button"，支持 Enter、Space 打开面板，Esc 关闭并重置颜色（见 color-picker.vue）；
• 未处于表单上下文时，可通过 aria-label 提供无障碍标签；处于 el-form-item 内时，自动关联表单项的 label（aria-labelledby），见 color-picker.vue；
• 面板本身以 role="dialog" 渲染在 Tooltip 中，配合 loop 键盘循环焦点管理。

底层原理：颜色解析与格式化

ColorPicker 的颜色核心是封装自 @ctrl/tinycolor 的 Color 类，其关键流程为：

1. 解析：fromString(value) 将任意格式颜色字符串交给 TinyColor 校验并转换为 HSVA 归一化状态存储；
2. 序列化：doOnChange() 依据 format 与 enableAlpha 决定输出格式（默认 hex，开启 Alpha 则 rgb/hex8），将 HSVA 状态重新 toString(format) 生成最终 v-model 值；
3. 比较：compare() 基于 HSVA 构造 TinyColor 比较是否等价，用于确认选择后判断是否需要重置面板状态。

这一设计使面板操作与输出格式解耦：无论面板中以何种色彩空间交互，输出格式始终由 color-format 统一控制。

在表单中使用

ColorPicker 遵循 Element Plus 表单体系：外层使用 el-form + el-form-item 包裹后，可通过 rules 配置必填等校验规则，选择或清除颜色时自动触发校验（受 validate-event 控制）。同时尺寸、禁用状态也会自动跟随表单上下文（useFormSize() / useFormDisabled()）。

<el-form :model="form" :rules="rules">
  <el-form-item label="主题色" prop="themeColor">
    <el-color-picker v-model="form.themeColor" />
  </el-form-item>
</el-form>

版本演进提示

• 2.3.3+：新增 show / hide 暴露方法；
• 2.3.13+：新增 focus / blur 暴露方法；
• 2.4.0+：新增 focus / blur 事件；
• 2.7.2+：新增 aria-label 与 teleported；
• 2.10.3+：新增 empty-values 与 value-on-clear；
• 2.10.5+：新增 persistent 与 append-to；
• 2.11.4+：新增 popper-style；
• 2.13.1+：新增 clearable 属性与 clear 事件。

以上能力均以当前仓库代码（含 color-picker.ts、color-picker.vue 及配套测试 color-picker.test.tsx）为准，使用前请确认项目安装的 Element Plus 版本满足对应要求。