element-react ColorPicker 颜色选择器深度解析:基础用法、透明度配置与源码级原理
element-react ColorPicker 颜色选择器深度解析:基础用法、透明度配置与源码级原理
导读
ColorPicker 是 element-react 中用于颜色选择的组件,它支持 hex、rgb、hsl、hsv 等多种颜色格式,并可通过 showAlpha 开关支持带 Alpha 通道(透明度)的颜色选择。本文以官方文档 site/docs/zh-CN/color-picker.md 为核心,完整讲解其基础用法、属性与事件配置,并结合仓库源码深入剖析颜色解析、格式转换与面板交互的底层实现,帮助你既会"用",也懂"理"。
基础用法
ColorPicker 通过 value 属性控制当前显示的颜色,值为字符串类型。有默认值时直接传入颜色字符串;不传值(或传 null)时,组件显示为"空"状态,触发器中会渲染一个关闭图标(el-icon-close)表示未选择任何颜色。
官方文档给出的基础示例:
render() {
const color1 = '#20a0ff';
const color2 = null;
return (
<div>
<div className="block">
<span className="demonstration">有默认值</span>
<ColorPicker value={color1}></ColorPicker>
</div>
<div className="block">
<span className="demonstration">无默认值</span>
<ColorPicker value={color2}></ColorPicker>
</div>
</div>
)
}
在组件挂载阶段(componentDidMount),如果 value 有值,组件会调用 color.fromString(value) 将字符串解析为内部颜色模型,详见下文"源码级原理"一节。值得注意的是 value 支持的不只是 hex,还包括 rgb、hsl、hsv 以及各自的 a(透明度)变体写法,解析逻辑统一封装在 color.js 中。
选择透明度
ColorPicker 除了支持普通颜色,还支持带 Alpha 通道的颜色。通过 showAlpha 属性即可控制是否支持透明度选择:
render() {
const color3 = 'rgba(19, 206, 102, 0.8)';
return (
<div style={{padding: '24px'}}>
<ColorPicker value={color3} showAlpha></ColorPicker>
</div>
)
}
当传入 rgba(19, 206, 102, 0.8) 这样的带透明度颜色并开启 showAlpha 时,面板底部会多出一条 Alpha 滑块(AlphaSlider.jsx),用于调整 0~100 的透明度百分比。同时触发器的色块会以 rgba(...) 形式实时展示当前颜色与透明度的叠加效果。
从源码看,showAlpha 不仅决定滑块是否渲染,还决定了 value 的默认输出格式(见下表)。它同时被传入内部 Color 模型的 enableAlpha 选项,直接影响最终颜色字符串的生成方式(ColorPicker.jsx)。
Attributes 属性
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| showAlpha | 是否支持透明度选择 | boolean | — | false |
| colorFormat | 写入 value 的颜色的格式 | string | hsl / hsv / hex / rgb | hex(showAlpha 为 false)/ rgb(showAlpha 为 true) |
两条属性的行为都可在 ColorPicker.jsx 的 propTypes 中确认:
value: PropTypes.string:当前颜色值,字符串类型;showAlpha: PropTypes.bool:是否启用透明度滑块;colorFormat: PropTypes.string:value 的输出格式;onChange: PropTypes.func:值变化时的回调(默认空函数)。
此外组件还通过 ComponentProps 继承通用属性(如 className、style),在 typings/index.d.ts 的类型定义中可以看到完整的 TypeScript 接口:
interface ColorPickerProps extends ElementReactLibs.ComponentProps<{}> {
value?: string
showAlpha?: boolean
colorFormat?: 'hsl' | 'hsv' | 'hex' | 'rgb'
onChange?(color?: string): void
}
colorFormat 的四种可选值 hsl / hsv / hex / rgb 与 color.js 中 doOnChange() 的四个分支一一对应。注意一个细节:当 showAlpha 为 true 时,即使选择了 hex 或 rgb 格式,输出也会带上透明度,分别变为 rgba、hsla、hsva 形式——这是颜色模型自动处理的结果(详见后文)。
Events 事件
| 事件名称 | 说明 | 回调参数 |
|---|---|---|
| onChange | 当绑定值变化时触发 | 当前值 |
onChange 由 ColorPicker.jsx 中两个关键方法触发:
confirmValue():用户在面板中点击"确定"按钮后,面板关闭,并以当前value回调onChange(value);clearValue():点击"清空"按钮后,value被置为null,回调onChange(null),并调用resetColor()将颜色模型重置。
需要留意的是,onChange 并非每次拖拽滑块都触发,而是通过 getChildContext() 提供的上下文把 handleChange 传给面板内部组件(ColorPicker.jsx)。内部组件拖拽过程中只更新状态与色块预览;只有确认(confirm)或清空(clear)时,父组件才会对外抛出最终值。这种"预览轻量、提交一次性"的设计避免了高频回调带来的性能开销。
源码级原理:从字符串到颜色模型
1. 内部统一用 HSV 表示颜色
打开 color.js,可以看到 Color 类的内部状态统一使用 HSV(色相、饱和度、明度)模型存储:
this._hue = 0;
this._saturation = 100;
this._value = 100;
this._alpha = 100;
构造函数接收 { enableAlpha, format } 选项,分别来自 showAlpha 与 colorFormat(ColorPicker.jsx)。所有外部输入(hex、rgb、hsl、hsv)都会先被解析并统一转换为 HSV,后续面板操作也直接修改这三个通道——这是整个组件的"单一事实来源"。
2. fromString() 的多格式解析
fromString(value)(color.js)根据字符串前缀分流解析:
- 含
hsl:剥离hsla|hsl|(|)后按分隔符切分,若为 4 段则解析第 4 段为_alpha(parseFloat * 100取整),再用hsl2hsv()转换为 HSV; - 含
hsv:同理,解析后直接落入 HSV; - 含
rgb:剥离rgba|rgb|(|)后解析 RGB 分量,再用rgb2hsv()转换; - 含
#:支持 3 位(#abc)与 6 位(#aabbcc)两种 hex 写法,通过parseHexChannel()逐通道还原,最后同样转 HSV。
因此 value 传入 '#20a0ff'、'rgb(32, 160, 255)'、'rgba(19, 206, 102, 0.8)'、'hsl(210, 100%, 56%)' 等任意受支持格式,都能正确初始化。
3. doOnChange():按 format 输出结果
doOnChange()(color.js)在每次 set() 修改内部通道后自动调用,根据 format 与 enableAlpha 生成对外暴露的 value 字符串:
| enableAlpha | format | 输出示例 |
|---|---|---|
| false | hex | #20a0ff |
| false | rgb | rgb(32, 160, 255) |
| false | hsl | hsl(210, 100%, 56%) |
| false | hsv | hsv(210, 100%, 100%) |
| true | 默认(rgb) | rgba(32, 160, 255, 0.8) |
| true | hsl | hsla(210, 100%, 56%, 0.8) |
| true | hsv | hsva(210, 100%, 100%, 0.8) |
这正解释了文档属性表中"默认值为 hex(showAlpha 为 false)/ rgb(showAlpha 为 true)"的深层原因:开启透明度后,hex 无法表达 Alpha 通道,因此即便未显式指定 colorFormat,输出也会落到带 Alpha 的 rgba 分支。相关的换算工具函数(hsv2hsl、rgb2hsv、hsv2rgb、toHex 等)都位于 color.js 文件内,并处理了百分比输入、浮点误差与大小写 hex 等边界情况。
4. 面板交互:三个滑块 + 一个下拉容器
面板由 PickerDropdown.jsx 组装,包含:
- HueSlider(色相滑块):以
vertical竖直形态渲染(HueSlider.jsx),拖动时按位置换算 0~360 的色相值并写入color._hue; - SvPanel(饱和度/明度面板):背景为当前色相的纯色,叠加白色渐变与黑色遮罩,光标位置同时映射
saturation与value两个通道(SvPanel.jsx),saturation = left / width * 100、value = 100 - top / height * 100; - AlphaSlider(透明度滑块):仅在
showAlpha为 true 时渲染,滑块背景是用当前 RGB 生成的渐变(linear-gradient(to right, rgba(r,g,b,0) 0%, rgba(r,g,b,1) 100%)),拖动换算 0~100 的_alpha(AlphaSlider.jsx); - 底部操作区:显示当前颜色值
currentColor、"清空"链接与"确定"按钮,文案通过 Locale.t 国际化(中文环境显示"清空"/"确定")。
所有滑块的拖拽能力来自 draggable.js:在 mousedown 时监听全局 mousemove/mouseup,并临时屏蔽 onselectstart/ondragstart 防止拖拽时选中页面文本,mouseup 后统一移除监听。
5. 外层交互:点击外部关闭与状态重置
ColorPicker.jsx 通过 ClickOutside(ColorPicker) 包装(文件末尾),实现点击组件外部自动收起面板(handleClickOutside())。收起与清空时都会调用 resetColor():若有 value 则重新 fromString(value) 还原颜色模型,保证"取消"或"关闭"后色块不被面板中的临时预览污染。
完整可运行示例
结合 typings/typing-tests/ColorPicker.tsx 与官方文档,一个带透明度、指定输出格式并监听回调的完整示例:
import { ColorPicker } from 'element-react';
class Demo extends React.Component {
constructor(props) {
super(props);
this.state = {
color: 'rgba(19, 206, 102, 0.8)'
};
}
onChange(color) {
this.setState({ color });
console.log('当前颜色值:', color);
}
render() {
return (
<div>
{/* 基础用法:hex 默认值 */}
<ColorPicker value="#20a0ff" />
{/* 无默认值 */}
<ColorPicker value={null} />
{/* 启用透明度,显式指定输出为 rgb 格式 */}
<ColorPicker
value={this.state.color}
showAlpha
colorFormat="rgb"
onChange={this.onChange.bind(this)}
/>
{/* 输出为 hsl 格式 */}
<ColorPicker value="hsl(210, 100%, 56%)" colorFormat="hsl" />
</div>
);
}
}
小结
- 使用层面:
value控制当前颜色,showAlpha开启透明度,colorFormat控制输出格式(hsl / hsv / hex / rgb),onChange在确认/清空时回调当前值; - 原理层面:组件内部以 HSV 为统一颜色模型,
fromString()负责多格式解析,doOnChange()按格式与透明度生成最终字符串,面板由色相滑块、饱和度/明度面板、透明度滑块三层交互组成,并通过上下文单向传递变更、点击外部自动收起; - 类型层面:可在 typings/index.d.ts 找到完整的
ColorPickerProps接口,element-react/next同样导出该组件(见 ColorPicker.tsx)。
理解这些底层机制后,无论是排查"为什么颜色值格式不是我想要的",还是扩展自定义取色交互,都能快速定位到 src/color-picker 目录下对应的实现文件。