Color Picker 颜色选择器

通过饱和度 / 亮度区域、色相和透明度滑块、带校验的输入框以及预设色板选择颜色。SColorPanel 是内联面板；SColorPicker 由触发器在弹出层中打开它，在紧凑的触屏窗口上改为底部面板。

基础用法

@Local color: string = '#3b82f6';

SColorPanel({ value: this.color!! })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

表单中的选择器

触发器是一个显示颜色块和颜色值的描边按钮；triggerWidth: '100%' 使其占满字段宽度。

SFieldGroup() {
  SField() {
    SFieldLabel({ text: 'Project name' })
    SInput({ placeholder: 'Acme' })
  }
  SField() {
    SFieldLabel({ text: 'Brand color' })
    SColorPicker({ value: this.brand!!, triggerWidth: '100%' })
    SFieldDescription({ text: 'Used for buttons, links and highlights.' })
  }
}

网页近似预览，真机效果以 HarmonyOS 渲染为准。

透明度与格式

alpha 增加不透明度滑块；format 设置值的格式（hex、rgb、hsl、oklch），formatToggle 让输入框可以切换显示这些格式。

// alpha slider over a checkerboard; HEX / RGB / HSL / OKLCH toggle for the input
SColorPanel({ value: this.tint!!, alpha: true, format: 'rgb', formatToggle: true })

// value format of a picker: 'hex' (default) | 'rgb' | 'hsl' | 'oklch'
SColorPicker({ defaultValue: '#8b5cf6', format: 'hsl' })
SColorPicker({ defaultValue: '#8b5cf680', format: 'oklch', alpha: true })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

色板

swatches 替换默认色板（[] 隐藏色板）；recent 列出最近提交的颜色。

// custom presets + recently committed colours (shared by all pickers)
SColorPanel({
  value: this.accent!!,
  swatches: ['#0f172a', '#334155', '#64748b', '#e2e8f0', '#ef4444', '#f59e0b', '#22c55e', '#3b82f6'],
  recent: true
})

// compact: chip-only trigger, no input
SColorPicker({ value: this.accent!!, iconOnly: true, showInput: false, sizing: 'sm' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

受控

onValueChange 在拖动过程中实时触发；onValueCommit 在松手时以及弹出层关闭时触发一次。

@Local value: string = '#f43f5e';
@Local changes: number = 0;
@Local committed: string = '#f43f5e';

SColorPicker({
  value: this.value!!,
  onValueChange: () => this.changes++,          // live while dragging
  onValueCommit: (v: string) => this.committed = v  // on release / close
})
SButton({ text: 'Reset', variant: 'outline', sizing: 'sm' }).onClick(() => this.value = '#f43f5e')

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SColorPanel

内联颜色面板：饱和度 / 亮度区域、色相滑块、可选的透明度滑块（底下是棋盘格）、预览色块、颜色输入框、可选的格式切换、预设色板和最近使用的颜色。 它是 {@link SColorPicker} 弹出层的内容，也可以单独使用。

• value / $value / defaultValue：面板 format 格式的颜色字符串（默认 'hex' → #rrggbb，开启 alpha 且半透明时为 #rrggbbaa；'rgb' | 'hsl' | 'oklch' → CSS 函数）。输入可以是 SparkColor 能解析的任何 CSS 颜色。十六进制为 CSS 顺序：需要 ArkUI 的 #AARRGGBB 颜色时用 SparkColor.parse(v).value（或 sparkColorValueToArgb）。
• onValueChange 在拖动过程中实时触发；onValueCommit 每次交互结束时触发一次（松手、点按、按键、色板、输入框回车 / 失焦）。
• 输入框接受 #RGB / #RRGGBB / #RRGGBBAA（以及其他 CSS 写法）；非法文本显示错误样式，失焦时恢复。formatToggle 增加一个 HEX / RGB / HSL / OKLCH 按钮，只改变输入框显示的格式。
• swatches（默认是一套类似 shadcn 的色板；[] 隐藏），recent（最近提交的颜色，全应用共享，见 SparkColorRecents）。
• 键盘：方向键移动区域上的拖柄（←→ 饱和度，↑↓ 亮度），并步进色相 / 透明度滑块。
• 尾随闭包渲染在面板下方（例如操作按钮）。

属性	类型	默认值	说明
value!!	string | undefined	undefined	受控值（配合 !! 使用）。留空则为非受控。
defaultValue	string	'#000000'	非受控初始值。
format	ColorPickerFormat ColorPickerFormat = 'hex' | 'rgb' | 'hsl' | 'oklch'	'hex'	输出值的格式。
alpha	boolean	false	显示透明度滑块，并在值中保留透明度。
disabled	boolean	false
sizing	InputSize InputSize = 'sm' | 'default' | 'lg'	'default'	颜色输入框 / 格式按钮的尺寸。
showInput	boolean	true	显示颜色输入行。
formatToggle	boolean	false	循环切换输入框显示格式的 HEX / RGB / HSL / OKLCH 按钮。
swatches	string[]	SPARK_DEFAULT_SWATCHES	预设色板（任意 CSS 颜色）；[] 隐藏这一行。
recent	boolean	false	显示最近提交的颜色（所有面板共享）。
panelWidth	Length | undefined	undefined	面板宽度；undefined → --color-picker-width / 240vp。传 '100%' 占满。
label	string | undefined	undefined	面板内各控件无障碍名称的前缀。
tokens	ColorPickerTokens	{}	单实例 Token 覆盖（实例 → 主题 --color-picker-* → 配方），见 {@link ColorPickerTokens}。

事件	类型	默认值	说明
onValueChange	(v: string) => void	() => { }	拖动过程中实时触发。
onValueCommit	(v: string) => void	() => { }	一次交互结束时触发（松手、点按、按键、色板、输入框回车 / 失焦）。

插槽: 子组件（尾随闭包）

SColorPicker

颜色选择器：描边按钮触发器显示颜色块和颜色值（iconOnly 时只显示颜色块），在触发器下方锚定的弹出层中打开 {@link SColorPanel}，在紧凑的触屏窗口上改为底部面板（adaptive: 'auto'）。

值的约定与 {@link SColorPanel} 相同：format 格式的颜色字符串（默认 'hex'），onValueChange 在拖动时实时触发，onValueCommit 在交互结束时触发；关闭时如果最后的值尚未提交，再触发一次。尾随闭包渲染在面板底部。tokens 定制面板（--color-picker-*）；surfaceTokens 定制弹出层表面（--popover-*）。

属性	类型	默认值	说明
value!!	string | undefined	undefined	受控值（配合 !! 使用）。留空则为非受控。
defaultValue	string	'#000000'
format	ColorPickerFormat ColorPickerFormat = 'hex' | 'rgb' | 'hsl' | 'oklch'	'hex'	输出值以及触发器文本的格式。
alpha	boolean	false
disabled	boolean	false
sizing	InputSize InputSize = 'sm' | 'default' | 'lg'	'default'	触发器（及面板输入框）的尺寸。
iconOnly	boolean	false	只显示颜色块的方形触发器。
triggerWidth	Length | undefined	undefined	触发器宽度；undefined → 适应内容。
formatToggle	boolean	false
showInput	boolean	true
swatches	string[]	SPARK_DEFAULT_SWATCHES
recent	boolean	false
label	string | undefined	undefined	触发器的无障碍名称（默认"选择颜色"）。
adaptive	SparkAdaptive SparkAdaptive = 'auto' | 'pointer' | 'touch'	'auto'
tokens	ColorPickerTokens	{}	面板 Token（实例 → --color-picker-* → 配方）。
surfaceTokens	SparkSurfaceTokens	{}	弹出层表面 Token（实例 → --popover-* → 配方）。

事件	类型	默认值	说明
onValueChange	(v: string) => void	() => { }
onValueCommit	(v: string) => void	() => { }
onOpenChange	(open: boolean) => void	() => { }

插槽: 子组件（尾随闭包）