颜色输入框

概述

用于编辑完整颜色字符串或单个颜色通道，支持 hex、rgb、hsl 和 oklch 输出格式。SColorField 组合 Aria ColorFieldRoot/ColorFieldInput 基础组件与 colorFieldVariants 样式配方（2 个槽、6 种尺寸）。

颜色输入框适合输入型颜色编辑，或在颜色选择器内以数值方式编辑单个通道（与 color-area/color-slider 配合）。

用法

特性

🧩 Aria/样式分离 — ColorFieldCompact 组合根 + 输入；SColorField 只注入样式并转发 prop/事件
🎨 格式 — 经 format 输出 hex/rgb/hsl/oklch；colorSpace + channel 用于单通道编辑
⌨️ 键盘 — ArrowUp/Down、PageUp/Down、Home/End 按 step 增减聚焦通道
🖱️ 滚轮 — 滚动调整通道，除非 disableWheelChange
🏷️ 占位/禁用/只读 — placeholder、disabled、readonly
📝 表单字段 — 经 name 生成隐藏输入，支持原生表单提交
📐 6 种尺寸 — xs–2xl size；逐槽 ui 覆盖

组件家族

SColorField（样式层）— 入口包装组件；colorFieldVariants 配方配合动态插槽转发
ColorFieldRoot（Aria）— 状态持有者；modelValue/color、format/colorSpace/channel、键盘/滚轮增减辅助
ColorFieldInput（Aria）— 绑定颜色/通道的文本输入
ColorFieldCompact（Aria）— 聚合组件；组合根 + 输入

演示

基础

100%

#0ea5e9

API

Aria 层

ColorField

18 属性2 事件

属性

属性名	类型	默认值	描述
class	ClassValue	—	应用于根元素的额外类名。
size	ThemeSize	—	组件的视觉尺寸。
ui	Partial<ColorFieldUi>	—	该组件的按槽类重写。
inputProps	ColorFieldInputProps	—	转发给输入元素的属性。
modelValue	import("@soybeanjs/colord").AnyColor	—	当前模型值。
defaultValue	import("@soybeanjs/colord").AnyColor	—	默认值。
colorSpace	ColorSpace	—	色彩空间。
channel	ColorChannel	—	频道。
format	ColorFormat	—	格式。
placeholder	string	—	占位符。
disabled	boolean	—	该组件是否已禁用。
readonly	boolean	—	该组件是否为只读。
disableWheelChange	boolean	—	是否禁用轮子变更。
step	number	—	步骤。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:modelValue	string	当模型值发生变化时触发。
update:color	NormalizedColor	当颜色值发生变化时触发。

ColorFieldCompact

15 属性2 事件

属性

属性名	类型	默认值	描述
inputProps	ColorFieldInputProps	—	转发给输入元素的属性。
modelValue	import("@soybeanjs/colord").AnyColor	—	当前模型值。
defaultValue	import("@soybeanjs/colord").AnyColor	—	默认值。
colorSpace	ColorSpace	—	色彩空间。
channel	ColorChannel	—	频道。
format	ColorFormat	—	格式。
placeholder	string	—	占位符。
disabled	boolean	—	该组件是否已禁用。
readonly	boolean	—	该组件是否为只读。
disableWheelChange	boolean	—	是否禁用轮子变更。
step	number	—	步骤。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:modelValue	string	当模型值发生变化时触发。
update:color	NormalizedColor	当颜色值发生变化时触发。

ColorFieldInput

ColorFieldRoot

14 属性2 事件

属性

属性名	类型	默认值	描述
modelValue	import("@soybeanjs/colord").AnyColor	—	当前模型值。
defaultValue	import("@soybeanjs/colord").AnyColor	—	默认值。
colorSpace	ColorSpace	—	色彩空间。
channel	ColorChannel	—	频道。
format	ColorFormat	—	格式。
placeholder	string	—	占位符。
disabled	boolean	—	该组件是否已禁用。
readonly	boolean	—	该组件是否为只读。
disableWheelChange	boolean	—	是否禁用轮子变更。
step	number	—	步骤。
name	string	—	字段的名称。作为名称/值对的一部分，与其所属表单一同提交。
required	boolean	—	当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。
asChild	boolean	—	将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。
as	AsTag \| Component	'div'	该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。

事件

事件名	参数	描述
update:modelValue	string	当模型值发生变化时触发。
update:color	NormalizedColor	当颜色值发生变化时触发。

注意事项

架构与对标差异

ColorFieldCompact 负责根/输入组合，所有基础组件保持零样式，仅由 UI 包装组件注入 colorFieldVariants 类。这与 radix-ui-color/shadcn-ui 的 headless 分离一致。Ant Design、Element Plus、Mantine、Naive UI 提供带 hex 输入的单一样式化颜色选择器；VeanUI 暴露独立的颜色输入框，带完整格式/通道控制、键盘/滚轮编辑与原生表单输入。

能力	VeanUI	shadcn/ui	Ant Design	Element Plus	Mantine	Naive UI
Aria/样式分离	✅	✅	—	—	—	—
多种格式	✅	✅	✅	✅	✅	—
单通道编辑	✅	✅	—	—	—	—
键盘 + 滚轮	✅	✅	—	—	—	—
原生表单输入	✅	✅	—	—	—	—
尺寸（6）	✅	—	—	—	—	—

— = 不支持或采用不同交互模型。

运行时注意

modelValue 接受颜色字符串或 ColorValue；format 控制输出字符串格式。
编辑单通道时设置 channel 并匹配 colorSpace（如 hsl 下的 lightness）；否则编辑完整字符串。
键盘（Arrow/Page/Home/End）与滚轮按 step（默认）改变聚焦通道；设 disableWheelChange 以抑制滚轮编辑。
提供 name 以将颜色作为隐藏表单字段提交。
与 color-area/color-slider 配合构成完整编辑器。

Roadmap

不适用——color-field 对当前对标集已功能完备。

FAQ

如何使用颜色输入框？

绑定 model-value 并选择 format：

<SColorField v-model:model-value="color" format="hex" />

如何编辑单个通道？

设置 channel 并匹配 color-space：

<SColorField v-model:model-value="color" channel="lightness" color-space="hsl" format="hsl" />

如何禁用滚轮编辑？

设置 disable-wheel-change：

<SColorField v-model:model-value="color" format="hex" disable-wheel-change />

快速跳转

同分类组件