Quasar QColor 颜色选择器组件完全指南从基础用法到无障碍访问【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar导读QColorq-color是 Quasar 框架内置的颜色输入组件用户可在 Spectrum光谱、Tune调校、Palette调色板三种视图间切换以 HEX/RGB 等格式取色。本文基于 Quasar 官方文档 color-picker.md结合组件源码 QColor.js、API 定义 QColor.json 及测试用例 QColor.test.js系统讲解模型绑定、视图配置、自定义调色板、原生表单提交与无障碍访问帮助你直接落地一个可用、可扩展且对键盘和屏幕阅读器友好的颜色选择器。组件概述QColor为 Vue 组件提供一种输入颜色的方式。它支持四种输出格式#FF00FFHEX、#FF00FFCCHEXA带 Alpha 通道、rgb(0,0,0)与rgba(255,0,255,0.8)模型值既可以是带#前缀的十六进制字符串也可以是rgb()/rgba()函数字符串使用v-model进行双向绑定。[!TIP] 若需要在组件之外处理颜色字符串Quasar 还提供了独立的 Quasar Color Utils内含rgbToHex、rgbToHsv、hexToRgb、textToRgb、hsvToRgb等转换函数以及lighten、luminosity、brightness、blend等处理函数——QColor 内部正是复用了这些工具。组件内部结构上QColor 由三部分构成见 QColor.jsHeader顶部显示当前颜色值与 HEX/RGB或 HEXA/RGBA切换标签页由no-header/no-header-tabs控制三个视图 TabSpectrum光谱面板 色相滑条、Tune数值输入 滑条、Palette色块矩阵由default-view与底部视图切换器控制Footer底部视图切换标签由no-footer控制。基础用法最基本的用法是直接绑定v-modelQColor 会根据初始值自动识别当前格式HEX 还是 RGB并相应地输出同格式的值template div classq-pa-md row items-start q-gutter-md q-color v-modelhex classmy-picker / q-color v-modelhexa classmy-picker / q-color v-modelrgb classmy-picker / q-color v-modelrgba classmy-picker / /div /template script setup import { ref } from vue const hex ref(#FF00FF) const hexa ref(#FF00FFCC) const rgb ref(rgb(0,0,0)) const rgba ref(rgba(255,0,255,0.8)) /script style langsass scoped .my-picker max-width: 250px /style完整示例见 Basic.vue。从源码看组件在parseModelQColor.js中对模型值做了归一化将字符串解析为{ h, s, v, r, g, b, a }的内部模型同时缓存hex与rgb两种字符串表达。输出时通过isOutputHex计算属性决定当前该用哪种格式const isOutputHex computed(() forceHex.value ! null ? forceHex.value : isHex.value )其中isHex判断模型值是否为空或是否以#开头。这意味着初始模型是 HEX 字符串输出就是 HEX初始是rgb()字符串输出就是 RGB——格式会跟随初始值自动保持一致。结合 QInput 使用与校验规则颜色选择器最常见的落地场景之一是配合输入框用户既可以直接打字也可以点击色滴图标弹出选择器。官方示例 Input.vue 展示了用QPopupProxy实现弹出式取色器template div classq-pa-md div classq-gutter-md row items-start q-input filled v-modelcolor classmy-input template #append q-icon namecolorize classcursor-pointer q-popup-proxy cover transition-showscale transition-hidescale q-color v-modelcolor / /q-popup-proxy /q-icon /template /q-input q-input filled v-modelsecondColor :rules[anyColor] hintWith validation classmy-input template #append q-icon namecolorize classcursor-pointer q-popup-proxy cover transition-showscale transition-hidescale q-color v-modelsecondColor / /q-popup-proxy /q-icon /template /q-input /div /div /template script setup import { ref } from vue const color ref(#FF00FF) const secondColor ref(#027be3) /scriptQInput的rules属性有现成的校验辅助规则完整列表定义在 patterns.js与颜色相关的包括规则名匹配内容底层正则节选hexColor#RGB/#RRGGBB/^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/hexaColor#RGBA/#RRGGBBAA/^#[0-9a-fA-F]{4}([0-9a-fA-F]{4})?$/hexOrHexaColor上述两者/^#([0-9a-fA-F]{3}\|{4}\|{6}\|{8})$/rgbColorrgb(r,g,b)0–255 的通道值rgbaColorrgba(r,g,b,a)通道 0–255alpha 0–1rgbOrRgbaColor上述两者组合正则hexOrRgbColorHEX 或 RGB组合正则hexaOrRgbaColorHEXA 或 RGBA组合正则anyColor任意一种颜色格式hexOrHexaRE \|\| rgbRE \|\| rgbaRE用法上既可以直接传字符串规则名如:rules[anyColor]也可以根据你的自定义需求编写自己的校验函数参见 QInput 内部校验。这些正则与 QColor 内部解析逻辑保持一致在parseModel中组件正是用testPattern.anyColor(...)判断模型值是否为合法颜色非法值会退化为黑色。隐藏头部与底部你可以按需隐藏头部no-header、头部内的 HEX/RGB 切换标签no-header-tabs或底部视图切换器no-footer示例见 NoHeaderFooter.vueq-color v-modelhex no-header classmy-picker / q-color v-modelhex no-header-tabs classmy-picker / q-color v-modelhex no-footer classmy-picker / q-color v-modelhex no-header no-footer classmy-picker /API 定义中QColor.json对no-footer的说明是当你只想用default-view固定某一种视图、不希望用户切换时非常有用。自定义默认视图default-view属性可以指定打开时的初始视图取值spectrum默认、tune、palette三者之一源码中的校验器为[spectrum, tune, palette].includes(v)QColor.js。以下示例固定使用palette视图同时隐藏头部和底部最终呈现一个纯色板用户只需点选即可取色CustomDefaultView.vueq-badge colorgrey-3 text-colorblack classq-mb-sm{{ hex }}/q-badge q-color v-modelhex no-header no-footer default-viewpalette classmy-picker /自定义调色板默认调色板是组件内置的一组硬编码颜色约 120 个 RGB 字符串从浅到深共 6 阶定义在 QColor.js 的palette常量中。通过palette属性可以完全替换 Palette 视图中的色块列表示例见 CustomPalette.vueq-color v-modelhex default-viewpalette :palette[ #019A9D, #D9B801, #E8045A, #B2028A, #2A0449, #019A9D ] classmy-picker /palette是字符串数组元素可以是#hex、rgb(r,g,b)等任意合法颜色字符串API 示例[#019A9D, #D9B801, rgb(23,120,0), #B2028A]。点选色块后onPalettePickQColor.js会解析该颜色并同步更新模型——若被选中的颜色不含 Alpha 通道则沿用当前模型的 Alpha 值。Palette 插槽v2.31palette插槽用于完全替换 Palette 视图中的默认色块同时保留 Spectrum、Tune 视图与视图切换器。它的作用域提供三个字段QColor.json 的 slots 定义作用域字段类型说明paletteArray当前调色板颜色列表palette属性传入的数组未设置时为内置列表select(color)Function将模型设为指定颜色组件处于disable或readonly状态时调用无效editableBoolean用户当前能否修改颜色禁用/只读时为false因此你可以完全自行决定色块的布局与标签。官方示例 PaletteSlot.vue 用品牌色 名称文本做了演示q-color v-modelhex default-viewpalette :palettepalleteOptions classmy-picker template #palette{ palette, select, editable } div classrow q-gutter-sm q-pa-md rolegroup aria-labelBrand colors q-btn v-forcolor in palette :keycolor no-caps :outlinehex ! color :unelevatedhex color :disable!editable :aria-pressedhex color clickselect(color) span classswatch q-mr-sm :style{ backgroundColor: color } / {{ swatches[color] }} /q-btn /div /template /q-color注意默认色块本身是键盘和屏幕阅读器可访问的详见下文无障碍章节自定义插槽内容时请尽量保持你的实现同样具备无障碍能力。强制暗色模式dark属性强制 QColor 以暗色主题渲染Dark.vue即使应用当前处于亮色模式。它复用了 Quasar 的useDarkcomposable源码中const isDark useDark(props, $q)见 QColor.jsq-color v-modelhex dark classmy-picker / q-color v-modelhexa dark classmy-picker / q-color v-modelrgb dark classmy-picker / q-color v-modelrgba dark classmy-picker /默认值当模型尚未设置值时可以用default-value属性显示一个默认颜色示例见 DefaultValue.vueq-color v-modelnullModel default-value#285de0 stylemax-width: 250px /从源码看default-value与model-value共同参与内部模型初始化const model ref(parseModel(props.modelValue || props.defaultValue))QColor.js。也就是说模型为空null/undefined/ 空字符串时会回退到default-value的解析结果一旦用户取色update:modelValue事件会携带新值回写父组件。懒更新Lazy Model默认情况下拖动光谱面板或滑条会实时触发update:model-value。若希望用户完成选择后才更新例如用于表单提交、或避免高频渲染开销可以用change事件代替v-model双向绑定示例见 LazyModel.vueq-color :model-valuehex changeval { hex val } stylemax-width: 250px /两个事件的语义在 API 定义中有明确区分QColor.jsonupdate:model-value模型值变化时实时发出change用户完成一次取色操作结束拖动、松开按键、点击色块等后发出是懒模型的入口。源码中updateModel(rgb, change)QColor.js是统一出口始终发出update:modelValue仅当change为真时才追加change事件。Spectrum 面板的键盘操作也遵循这一约定按键期间keydown只更新内部值与update:modelValue松开按键keyup时才发出change避免按键连发刷屏QColor.js。测试用例也验证了两类事件的独立行为QColor.test.js。禁用与只读disable与readonly属性控制交互性DisableReadonly.vueq-color v-modelcolor disable classmy-picker / q-color v-modelcolor readonly classmy-picker /disable完全禁用组件视觉上变灰aria-disabledtrue暴露在根元素上readonly只读不可修改颜色但保留视觉样式两者的共同底层是editable计算属性!props.disable !props.readonly见 QColor.js它同时控制 Palette 插槽作用域中的editable标志无障碍层面只读或禁用时光谱面板与色块会从 Tab 键顺序中移除与其滑条行为一致但光谱面板仍会以aria-readonly/aria-disabled持续播报当前颜色详见下文。原生表单提交当组件处于一个带action和method的原生表单中例如 Quasar 配合 ASP.NET 控制器使用时必须给 QColor 指定name属性否则formData将不会包含该字段。示例见 NativeForm.vueq-form submitonSubmit classq-gutter-md q-color nameaccent_color v-modelcolor stylewidth: 200px; max-width: 100% / div q-btn labelSubmit typesubmit colorprimary / /div /q-form提交后FormData中即可读取到accent_color 当前颜色值。其实现机制是useFormInject组件内部渲染一个typehidden的隐藏输入框值取自model.value[isOutputHex.value ? hex : rgb]QColor.js——即输出格式同样遵循跟随初始值的规则。强制模型输出格式format-model除了跟随初始值自动推断QColor 还提供format-model属性强制模型输出为指定格式值效果auto默认跟随初始值的格式hex强制输出#RRGGBBrgb强制输出rgb(r,g,b)hexa强制输出#RRGGBBAArgba强制输出rgba(r,g,b,a)源码中通过forceHex与forceAlpha两个计算属性实现QColor.jsformatModel含hex则强制十六进制输出含a则强制带 Alpha 通道hasAlpha控制界面中是否显示 Alpha 滑条与 HEXA/RGBA 标签。当强制输出带 Alpha 的格式而模型值本身没有 Alpha 时解析时会自动补上a: 100QColor.js。无障碍访问v2.25Palette 增强 v2.31QColor 的三种视图均支持键盘与屏幕阅读器操作这是其区别于一般取色组件的重要特性相关测试覆盖在 QColor.test.js 的无障碍章节。Spectrum 光谱面板面板本身是一个roleslider的滑条名称来自本地化的colorPicker.spectrum标签由于它同时驱动两个轴其可访问值会同时播报饱和度与亮度例如 Saturation 40%, Brightness 70%本地化键colorPicker.saturation/colorPicker.brightness面板是 Tab 键停靠点键盘行为Left/Right调整饱和度 ±1%按住Shift为 ±10%Up/Down调整亮度 ±1%按住Shift为 ±10%Home/End饱和度跳到 0 / 100PageUp/PageDown亮度 ±10%与旁边的滑条一致松开按键时才发出change事件防止长按连发。这些按键逻辑可在 QColor.js 的onSpectrumKeydown/onSpectrumKeyup中找到左右键的方向还会跟随 RTL 语言方向反转与 QSlider 行为保持一致饱和度/亮度经过between(s, 0, 100)钳制在 0–100。Palette 色块色块是带名称的按钮aria-label即其颜色值包裹在一个携带本地化colorPicker.palette标签的分组rolegroup中与当前模型匹配的色块会暴露为aria-pressedtruePalette 只有一个 Tab 停靠点优先是当前选中的色块否则是第一个采用 roving tabindex 模式源码中focusedSwatch负责记录当前拥有 Tab 停靠点的色块见 QColor.js方向键在色块间移动Up/Down按一行的视觉行距移动通过父容器宽度除以色块宽度实时测量列数即使自定义了色块宽度也能落在正上方/正下方的色块上Home/End跳到第一个/最后一个色块Enter/Space选中当前聚焦色块通过palette插槽渲染的色块其无障碍实现由你自行负责。测试用例验证了上述行为例如色块是带名称的按钮、位于命名分组内、匹配模型的色块拥有 Tab 停靠点且aria-pressed为 trueQColor.test.js。本地化与禁用语义所有对外暴露的内部控件视图标签、头部颜色值输入框、色相/透明度滑条都使用 Quasar Language Pack 中colorPicker.*键的本地化名称这些名称消费者无法从外部覆盖测试用例对此做了断言视图标签依次命名为colorPicker.spectrum/colorPicker.tune/colorPicker.palette头部输入框为colorPicker.value滑条为colorPicker.hue/colorPicker.alphaQColor.test.jsdisable的 QColor 会在根元素上暴露aria-disabledtruereadonly或disable时光谱面板与色块会退出 Tab 键顺序与其滑条一致但光谱面板仍持续以aria-readonly/aria-disabled播报当前颜色。补充说明与样式QColor 还支持square直角、flat扁平无阴影、bordered边框三个视觉属性均继承自 Quasar 通用样式约定组件的 SASS 样式位于 QColor.sass内部类名以q-color-picker__为前缀如q-color-picker__header-content、q-color-picker__palette-rows等可通过深选择器或全局样式进行定制头部文本颜色会自动适配当颜色过亮或 Alpha 过低时内部通过luminosity()计算亮度并切换--light/--dark修饰类QColor.js如果需要在文档/组件库场景中同时覆盖多种交互状态可参考 QColor.hydration.test.js 的测试写法了解组件在服务端渲染与客户端水合时的行为边界。至此从基础绑定、弹出式取色、自定义视图与调色板到懒更新、原生表单、强制格式与无障碍键盘操作q-color的完整能力已覆盖完毕。将上述配置组合使用例如default-viewpalettepalette插槽 format-modelhexa即可快速构建出贴合业务品牌色的专业取色器。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考