Radix Vue ColorField 组件指南构建支持键盘与滚轮交互的颜色值输入字段【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vueColorField 是 Radix Vue现 Reka UI中用于输入与编辑颜色值的表单字段组件支持十六进制颜色整体输入与单通道如色相、明度、RGB 分量编辑两种模式并内置箭头键、PageUp/Down、Home/End、鼠标滚轮等精细调节能力。本文将以 docs/content/docs/components/color-field.md 为主线结合 packages/core/src/ColorField/ColorFieldRoot.vue 等源码实现完整讲解其安装方式、API 配置、表单集成、键盘交互与无障碍细节读完即可在表单场景中直接落地一个专业级颜色输入控件。该组件当前处于Alpha阶段API 仍可能调整。本仓库中组件均从reka-ui包导入。核心能力一览ColorField 围绕“精准、可键盘操作、可表单提交”三个目标设计其功能清单如下支持 Hex 颜色整体输入模式支持单个颜色通道编辑模式Hue、Saturation、Red/Green/Blue、Alpha、Lightness、Brightness方向键ArrowUp / ArrowDown步进增减鼠标滚轮增减数值PageUp / PageDown 大跨度调整Home / End 快速跳转到最小值 / 最大值表单集成自动渲染隐藏 input 参与原生表单提交支持 HSL、HSB、RGB 三种颜色空间。如果你需要完整的颜色选择体验取色区域 滑杆 输入框 色板可以参考仓库中组合了 ColorArea、ColorSlider、ColorField 与 ColorSwatch 的示例 docs/content/examples/color-picker.md。安装在命令行中安装reka-ui即可使用 ColorField该包同时包含本仓库全部组件pnpm add reka-ui # 或 npm install reka-ui组件结构AnatomyColorField 由两个部件组成ColorFieldRoot负责颜色状态管理与上下文ColorFieldInput负责实际的文本输入框。script setup import { ColorFieldInput, ColorFieldRoot, } from reka-ui /script template ColorFieldRoot ColorFieldInput / /ColorFieldRoot /template从源码结构看根组件通过provideColorFieldRootContext向下注入颜色值、通道、步进与增删函数见 ColorFieldRoot.vue输入组件则通过injectColorFieldRootContext消费这些能力因此ColorFieldInput必须嵌套在ColorFieldRoot内部使用。API 参考ColorFieldRoot根组件负责颜色字段的上下文与状态管理默认渲染为div并带有rolegroup。完整 Props 与事件如下同步自 docs/content/meta/ColorFieldRoot.md名称说明类型必填默认值as渲染为的元素或组件可被asChild覆盖AsTag \| Component否divasChild将默认渲染元素替换为子元素合并 props 与行为boolean否-channel要展示的颜色通道不传则展示 Hex 值hue \| saturation \| red \| green \| blue \| alpha \| lightness \| brightness否-colorSpace展示通道时所在的颜色空间hsl \| rgb \| hsb否hsldefaultValue默认颜色值非受控模式string \| Color否#000000disabled为true时禁止用户交互boolean否falsedisableWheelChange为true时禁止滚轮修改值boolean否falselocale数字格式化使用的 localestring否-modelValue颜色值受控模式可为 Hex 字符串或 Color 对象string \| Color否-name字段名随所属表单以 name/value 形式提交string否-placeholder字段为空时的占位文本string否-readonly为true时字段只读boolean否falserequired为true时表示提交前必须填写boolean否-step步进/递减的自定义步长默认取通道步长Hex 模式为 1number否-事件Emits名称类型update:modelValue[value: string]update:color[value: Color]ColorFieldInput负责渲染文本输入框默认渲染为input并继承根组件下发的值、占位符、禁用/只读状态以及全部键盘与滚轮事件处理。其 Props 仅包含组合能力相关的两项名称说明类型默认值as渲染为的元素或组件AsTag \| ComponentinputasChild将默认渲染元素替换为子元素boolean-源码级实现原理阅读根组件实现ColorFieldRoot.vue可以更深入理解组件行为背后的机制颜色归一化modelValue通过normalizeColor归一化为统一的 Color 对象任何写入都会通过colorToString(newColor, hex)转回 Hex 字符串并触发update:modelValue与update:color因此无论受控还是非受控v-model拿到的始终是可序列化的 Hex 值。步长策略getStep优先取用户传入的step通道模式下取getChannelRange(channel).stepHex 模式下以整数空间按 1 步进并在MIN_HEX_INT 0x000000与MAX_HEX_INT 0xFFFFFF之间做钳制对应incrementToMax/decrementToMin中的整数值操作。通道取值范围由 packages/core/src/shared/color/channel.ts 统一定义——Hue 为 0–360Saturation/Lightness/Brightness/Alpha 为 0–100Red/Green/Blue 为 0–255步长均为 1。通道读写getChannelValue与setChannelValue会自动在 RGB/HSL/HSB 之间转换且尽量复用目标颜色空间以避免精度损失setChannelValue内部总是将输入值钳制到通道范围内见 channel.ts。提交commit失焦或按 Enter 时触发。通道模式把输入解析为数字并钳制后写回Hex 模式则用isValidColor校验、parseColor解析非法输入会被丢弃并回显原值。表单集成当isFormControl name时根组件会渲染一个VisuallyHiddenInput视觉隐藏的typetext输入框其值为当前颜色的 Hex 字符串并同步disabled/required状态从而让原生表单正常收集颜色值见 ColorFieldRoot.vue。输入防护输入组件在通道模式下通过beforeinput事件过滤非法字符仅允许数字、小数点与负号并容忍-、.、-.等输入过程中的中间态同时借助useComposing跳过 IME 输入法合成期间的所有步进与提交操作避免中文等输入法候选选字被打断见 ColorFieldInput.vue。实战示例Hex 颜色输入最基础的用法一个可整体输入十六进制颜色值的输入框配合v-model双向绑定。script setup import { ColorFieldInput, ColorFieldRoot, } from reka-ui import { ref } from vue const color ref(#3b82f6) /script template ColorFieldRoot v-modelcolor ColorFieldInput / /ColorFieldRoot /template单通道输入传入channel指定要编辑的通道并用color-space声明该通道所属颜色空间。例如下面的色相输入框值域为 0–360方向键每按一次步进 1。script setup import { ColorFieldInput, ColorFieldRoot, } from reka-ui import { ref } from vue const color ref(#3b82f6) /script template ColorFieldRoot v-modelcolor color-spacehsl channelhue ColorFieldInput / /ColorFieldRoot /template可用的通道组合包括color-spacehsl搭配hue/saturation/lightness/alphacolor-spacergb搭配red/green/blue/alphacolor-spacehsb搭配hue/saturation/brightness/alpha。禁用滚轮修改某些场景如输入框位于可滚动页面内不希望滚轮改变数值设置disable-wheel-change即可此时滚轮只滚动页面script setup import { ColorFieldInput, ColorFieldRoot, } from reka-ui import { ref } from vue const color ref(#3b82f6) /script template ColorFieldRoot v-modelcolor disable-wheel-change ColorFieldInput / /ColorFieldRoot /template只读模式需要展示颜色值但不允许编辑时使用readonly与之相对disabled则完全禁止交互script setup import { ColorFieldInput, ColorFieldRoot, } from reka-ui import { ref } from vue const color ref(#3b82f6) /script template ColorFieldRoot v-modelcolor readonly ColorFieldInput / /ColorFieldRoot /template无障碍与键盘交互组件默认渲染原生input天然具备可聚焦、可读屏等语义根组件还会在disabled/readonly时输出对应的data-disabled/data-readonly属性供样式定制。在 ColorField.test.ts 中组件通过了 vitest-axe 的无障碍扫描且测试覆盖了 Hex 模式渲染、input值更新、disabled 属性、readonly 属性以及通道模式下的通道值渲染等场景。聚焦输入框后即可使用下列键盘交互按键说明ArrowUp值增加一步ArrowDown值减少一步PageUp值增加 10 步PageDown值减少 10 步Home跳转到最小值如通道模式下该通道的 minHex 模式下为#000000End跳转到最大值如 Hex 模式下为#ffffffEnter提交当前输入值其中“10 步”对应源码中PAGE_STEP_MULTIPLIER 10的实现Home/End在通道模式下分别对应通道范围的min/max在 Hex 模式下则对应0x000000/0xFFFFFF见 ColorFieldRoot.vue。所有步进、滚轮与快捷键操作在disabled或readonly状态下都会直接返回不会改变颜色值。小结ColorField 用最少的部件Root Input覆盖了颜色输入的两大典型场景整体 Hex 输入与单通道数值编辑并将步进、大跳、极值跳转、滚轮调节、表单隐藏输入等能力全部内聚到根组件的状态管理中。结合v-model、channel/color-space、step、disable-wheel-change、readonly等配置你可以在几行代码内得到既有完整键盘可达性、又能直接参与原生表单提交的颜色输入控件。需要完整取色能力时可将它与 ColorArea、ColorSlider、ColorSwatch 组合使用参考 color-picker 示例 即可快速上手。【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考