颜色选择器 ColorPicker

基本使用

默认使用输入型触发器。可以直接通过输入框编辑颜色，也可以展开面板精调。

渐变与模式切换

color-modes 现在完整支持 monochrome 和 linear-gradient。当允许渐变时，面板会提供模式切换、渐变 stop 编辑、角度设置，以及 gradient-only 的内联面板。

预设颜色和历史颜色

通过 recent-colors 和 swatch-colors 控制最近使用颜色与系统色板。系统色板默认读取 ConfigProvider 的 color-picker.swatch-colors，组件显式传入 swatch-colors 时优先使用组件配置；两处均未配置时为空。最近使用颜色变化时会触发 recent-colors-change。

禁用

设置 disabled 禁用选择器。

颜色格式

通过 format 切换输出格式。单色模式覆盖 HEX、HEX8、RGB、RGBA、HSL、HSLA、HSV、HSVA、CMYK、CSS 的字符串输出；渐变模式统一输出 linear-gradient(...) CSS 字符串。

只使用面板

使用 hide-trigger 可以内联渲染颜色面板。

尺寸

颜色选择器支持 small、medium、large 与 mini 四种尺寸。

自定义触发元素

推荐使用 #trigger 插槽自定义触发元素。插槽直接提供 value、规范化后的 displayValue、完整 color 对象、popupVisible、disabled、readonly、 format 和可直接绑定的 previewStyle。为保持兼容，原有默认插槽写法仍然可用。

触发器

可以通过 trigger-props 直接透传 TriggerProps 配置，行为与组件库里的 Trigger 保持一致。

API

<color-picker> Props

参数名	描述	类型	默认值
model-value (v-model)	受控色值	string	-
default-value	非受控默认色值	string	''
color-modes	可用颜色模式	('monochrome' | 'linear-gradient')[]	['monochrome']
enable-multiple-gradient	是否允许新增多个渐变 stop	boolean	true
format	输出格式	'HEX' | 'HEX8' | 'RGB' | 'RGBA' | 'HSL' | 'HSLA' | 'HSV' | 'HSVA' | 'CMYK' | 'CSS'	'RGB'
size	尺寸	'mini' | 'small' | 'medium' | 'large'	'medium'
clearable	是否允许清空	boolean	false
enable-alpha	是否启用透明通道	boolean	false
show-primary-color-preview	是否展示主色预览块	boolean	true
input-props	透传到触发输入框的属性	Record<string, unknown>	-
trigger-props	透传 Trigger 组件的属性	Partial<TriggerProps>	-
recent-colors	最近使用颜色	string[] | boolean | null	[]
default-recent-colors	最近使用颜色的非受控初始值	string[] | boolean | null	[]
swatch-colors	系统色板，优先于 ConfigProvider 配置	string[] | null	[]
disabled	禁用	boolean	false
hide-trigger	仅渲染内联面板	boolean	false

<color-picker> Events

事件名	描述	参数
change	颜色值变化时触发	value: string context: { color, trigger }
clear	点击清空时触发	{ e: MouseEvent }
popup-visible-change	颜色面板展开和收起时触发	visible: boolean value: string
palette-bar-change	色相条或透明度条变化时触发	{ color }
recent-colors-change	最近使用颜色变化时触发	string[]

<color-picker> Slots

插槽名	描述	参数
trigger	自定义触发器内容	ColorPickerTriggerSlotProps
default	自定义触发器内容（兼容写法）	-