颜色选择器 ColorPicker

基本使用

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

渐变与模式切换

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

预设颜色和历史颜色

通过 recent-colors 和 swatch-colors 控制最近使用颜色与系统色板。最近使用颜色变化时会触发 recent-colors-change。

禁用

设置 disabled 禁用选择器。

颜色格式

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

只使用面板

使用 hide-trigger 可以内联渲染颜色面板。这一能力保留自旧版 API，便于旧场景迁移。

尺寸

颜色选择器优先对齐 TDesign 的 small、medium、large，同时兼容旧版 mini。

自定义触发元素

自定义触发元素。

触发器

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

API

`<color-picker>` Props

参数名	描述	类型	默认值
model-value (v-model)	受控色值	`string`	`-`
value	兼容 TDesign 的受控色值入口	`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	系统色板	`string[] \| null`	内置色板
disabled	禁用	`boolean`	`false`
hide-trigger	兼容旧版，仅渲染内联面板	`boolean`	`false`
history-colors	旧版 recent-colors 别名	`string[]`	`-`
preset-colors	旧版 swatch-colors 别名	`string[]`	`-`
show-history	旧版开关，开启时使用 `history-colors`	`boolean`	`false`
show-preset	旧版开关，开启时使用 `preset-colors`	`boolean`	`false`
disabled-alpha	旧版 `enable-alpha` 反向别名	`boolean`	`false`
show-text	旧版属性，保留兼容但不再建议新增使用	`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

插槽名	描述
default	自定义触发器内容

迁移说明

本次实现以当前组件库的 ColorPicker 和 Trigger 约定为主，同时保留了旧版 @sdata/web-vue color-picker 的兼容桥接。

旧版能力	新版建议
`trigger-props`	直接透传 `TriggerProps`
`history-colors + show-history`	迁移到 `recent-colors`
`preset-colors + show-preset`	迁移到 `swatch-colors`
`disabled-alpha`	迁移到 `enable-alpha`
`show-text`	新版默认采用输入型触发器，一般无需再使用
`hide-trigger`	仍可继续使用，作为内联面板模式

当前版本的迁移结论：

单色与线性渐变都已经按 TDesign 能力接入，新的业务可直接使用 color-modes 与 enable-multiple-gradient。
旧版常用 props 仍保留兼容桥接，但新增代码建议直接采用当前组件库的 trigger-props / TriggerProps 约定。
渐变模式统一输出 CSS linear-gradient(...) 字符串；如果旧业务依赖旧版自定义结构，迁移时应直接改为标准 CSS 字符串。