ColorPicker 颜色选择器

新粗野主义风格的颜色选择器组件，基于 reka-ui Popover 构建。支持 HEX/RGB/HSL 多种颜色格式、透明度通道、预设颜色调色板和本地存储的颜色历史记录。

预览

Preview

基础用法（HEX）

#EF476F

颜色格式

RGB

HSL

透明度通道（showAlpha）

#4A90D9

自定义预设颜色

尺寸

禁用状态

程序化控制（通过 ref 打开面板）

通过 pickerRef.open 可在外部按钮中打开或关闭颜色面板。

颜色选择器提供饱和度/亮度选择区域、色相滑块、透明度滑块、HEX 输入框、预设颜色和历史记录。

安装

pnpm dlx brutx-vue@latest add color-picker

用法

基础用法

<script setup>
import { ref } from 'vue'
import { ColorPicker } from 'brutx-ui-vue'

const color = ref(null)
</script>

<template>
    <ColorPicker v-model="color" placeholder="选择颜色" />
</template>

指定颜色格式

支持 hex（默认）、rgb、hsl 三种格式，modelValue 会以对应格式输出：

<script setup>
import { ref } from 'vue'
import { ColorPicker } from 'brutx-ui-vue'

const color = ref(null)
</script>

<template>
    <ColorPicker v-model="color" format="rgb" />
    <ColorPicker v-model="color" format="hsl" />
</template>

透明度通道

启用 showAlpha 后，面板会显示透明度滑块，输出值含 alpha 通道：

<template>
    <ColorPicker v-model="color" :show-alpha="true" />
</template>

预设颜色

内置 Tailwind CSS 默认调色板，也可自定义预设：

<script setup>
import { ref } from 'vue'
import { ColorPicker } from 'brutx-ui-vue'

const color = ref(null)
const presets = [
    '#FF6B6B',
    '#4ECDC4',
    '#FFE66D',
    '#EF476F',
    '#7FB069',
]
</script>

<template>
    <ColorPicker v-model="color" :presets="presets" :show-presets="true" />
</template>

预设也支持带标签的对象格式（可选 disabled 字段禁用单个色块）：

<script setup>
const presets = [
    { label: '珊瑚红', value: '#FF6B6B' },
    { label: '薄荷青', value: '#4ECDC4' },
    { label: '已废弃', value: '#999999', disabled: true },
]
</script>

颜色历史记录

启用 showHistory 后，用户选择的颜色会自动记录到历史，默认存储在 localStorage：

<template>
    <ColorPicker
        v-model="color"
        :show-history="true"
        :history-max="20"
        history-storage-key="my-app-color-history"
    />
</template>

可清除

<template>
    <ColorPicker v-model="color" :clearable="true" />
</template>

禁用状态

<template>
    <ColorPicker v-model="color" disabled />
</template>

尺寸

尺寸	说明
sm	小尺寸
default	默认尺寸
lg	大尺寸

<template>
    <ColorPicker v-model="color" size="sm" />
    <ColorPicker v-model="color" size="default" />
    <ColorPicker v-model="color" size="lg" />
</template>

数据类型

格式	示例	说明
hex	#FF6B6B / #FF6B6B80	十六进制（含 alpha 时追加两位）
rgb	rgb(255, 107, 107) / rgba(255, 107, 107, 0.5)	RGB 函数表示法
hsl	hsl(0, 100%, 71%) / hsla(0, 100%, 71%, 0.5)	HSL 函数表示法

组合式函数

ColorPicker 组件的弹出面板触发、颜色格式归一化、清除、确认等逻辑已抽取为独立的 useColorPicker 组合式函数，可在需要构建完全自定义触发器或调色面板时单独使用。它负责管理面板开关状态、显示值与 modelValue 的同步、按目标格式归一化展示，并通过传入的 emit 触发 open / close / change / update:modelValue 事件。

import { useColorPicker } from 'brutx-ui-vue'
import type { UseColorPickerOptions } from 'brutx-ui-vue'

const emit = defineEmits<{
    'update:modelValue': [value: string | null]
    'change': [value: string | null]
    'open': []
    'close': []
}>()

const {
    open,                  // 面板是否打开
    displayValue,          // 面板内当前显示的值
    normalizedDisplay,     // 按目标格式归一化后的展示字符串
    swatchStyle,           // 触发器色块的内联样式
    handlePanelUpdate,     // 面板值更新回调
    handlePanelConfirm,    // 面板确认回调
    handlePanelClear,      // 面板清除回调
    handleClearClick,      // 触发器清除按钮点击回调
    handleTriggerKeydown,  // 触发器键盘事件回调
} = useColorPicker({
    modelValue,
    format: 'hex',
    showAlpha: false,
    disabled: false,
    emit,
})

选项

属性	类型	默认值	说明
modelValue	MaybeRefOrGetter<string | null>	null	当前选中颜色（支持 v-model）
format	MaybeRefOrGetter<'hex' | 'rgb' | 'hsl'>	'hex'	颜色格式
showAlpha	MaybeRefOrGetter<boolean>	false	是否支持透明度通道
disabled	MaybeRefOrGetter<boolean>	false	是否禁用
emit	ColorPickerEmit	—	触发事件的函数（必填，类型与组件 emits 一致）

返回值

属性	类型	说明
open	Ref<boolean>	面板是否打开
displayValue	Ref<string | null>	面板内当前显示的值
normalizedDisplay	ComputedRef<string | null>	按 format 归一化后的展示字符串（无法解析时为 null）
swatchStyle	ComputedRef<{ backgroundColor: string }>	触发器色块的内联样式
handlePanelUpdate(value)	(value: string | null) => void	面板值更新时调用，同步 displayValue 并触发 update:modelValue
handlePanelConfirm(value)	(value: string | null) => void	面板确认时调用，触发 update:modelValue / change 并关闭面板
handlePanelClear()	() => void	面板清除时调用，触发 update:modelValue(null) / change(null)
handleClearClick(event)	(event: MouseEvent) => void	触发器清除按钮点击回调，阻止事件冒泡并清除
handleTriggerKeydown(event)	(event: KeyboardEvent) => void	触发器键盘事件回调，Enter / Space 打开面板（禁用时不响应）

提示：emit 必须是符合 ColorPickerEmit 签名的函数（即组件 defineEmits 的返回值）。颜色解析与格式化由 @/lib/color 的 parseColor / formatColor 提供。

程序化控制

ColorPicker 通过 defineExpose 暴露 open 响应式引用，允许父组件程序化打开或关闭颜色面板。open 是与内部 Popover 双向绑定的 Ref<boolean>，可直接读写。

<script setup>
import { ref } from 'vue'
import { ColorPicker } from 'brutx-ui-vue'

const pickerRef = ref()
const color = ref(null)
</script>

<template>
    <ColorPicker ref="pickerRef" v-model="color" />

    <button @click="pickerRef?.open = true">打开面板</button>
    <button @click="pickerRef?.open = false">关闭面板</button>
</template>

API 参考

ColorPicker

ColorPicker — 属性

名称	类型	默认值	说明
open	boolean | undefined	undefined	颜色面板的受控开关状态；与 v-model:open 配合控制面板。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 undefined 来源 ColorPicker.vue:18 packages/ui/src/components/color-picker/ColorPicker.vue
size	"default" | "lg" | "sm" | undefined	"default"	触发按钮及颜色控件的尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 "default" 来源 ColorPicker.vue:19 packages/ui/src/components/color-picker/ColorPicker.vue
modelValue 可空	string | null | undefined	null	当前颜色字符串；null 表示尚未选择颜色，可通过 v-model 双向绑定。
详情 声明类型 string | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 null 来源 types.ts:8 packages/ui/src/components/color-picker/types.ts
format	ColorPickerFormat | undefined	"hex"	颜色值的输入和输出格式：HEX、RGB 或 HSL。
详情 声明类型 ColorPickerFormat | undefined 字面量 "hex" "hsl" "rgb" 默认值详情 声明 'hex' 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 "hex" 来源 types.ts:9 packages/ui/src/components/color-picker/types.ts
showAlpha	boolean | undefined	false	显示透明度滑块，并在输出颜色值中保留 alpha 通道。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 false 来源 types.ts:10 packages/ui/src/components/color-picker/types.ts
presets	string[] | readonly ColorPreset[] | undefined	undefined	可选色板；元素可以是颜色字符串或带标签、禁用状态的 ColorPreset。未提供时面板使用内置预设。
详情 声明类型 string[] | readonly ColorPreset[] | undefined 关联类型 ColorPreset 类型定义 — ColorPreset export interface ColorPreset { readonly label: string readonly value: string readonly disabled?: boolean } 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 undefined 来源 types.ts:11 packages/ui/src/components/color-picker/types.ts
showPresets	boolean | undefined	true	控制面板是否显示预设色板。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 true 来源 types.ts:12 packages/ui/src/components/color-picker/types.ts
presetsLabel	string | undefined	undefined	预设色板区域的可见标题；未提供时使用本地化文案。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 undefined 来源 types.ts:13 packages/ui/src/components/color-picker/types.ts
showHistory	boolean | undefined	true	控制面板是否显示并维护最近选择的颜色历史。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 true 来源 types.ts:14 packages/ui/src/components/color-picker/types.ts
historyMax	number | undefined	8	颜色历史最多保留的条目数。
详情 声明类型 number | undefined 默认值详情 声明 8 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 8 来源 types.ts:15 packages/ui/src/components/color-picker/types.ts
historyStorageKey	string | undefined	"brutx-color-history"	颜色历史写入 localStorage 时使用的键名。
详情 声明类型 string | undefined 默认值详情 声明 'brutx-color-history' 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 "brutx-color-history" 来源 types.ts:16 packages/ui/src/components/color-picker/types.ts
showInput	boolean | undefined	true	在触发按钮中显示颜色文本；关闭后只保留色块和占位文本。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 true 来源 types.ts:17 packages/ui/src/components/color-picker/types.ts
placeholder	string | undefined	undefined	没有有效颜色时显示的占位文本，同时作为无障碍名称的本地化回退来源。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 undefined 来源 types.ts:18 packages/ui/src/components/color-picker/types.ts
disabled	boolean | undefined	false	禁用触发按钮和清除操作，并阻止打开颜色面板。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 false 来源 types.ts:19 packages/ui/src/components/color-picker/types.ts
clearable	boolean | undefined	false	有颜色值且未禁用时显示清除按钮。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 false 来源 types.ts:20 packages/ui/src/components/color-picker/types.ts
name	string | undefined	undefined	表单字段名；设置后渲染隐藏 input 提交当前颜色，禁用时该值不参与表单提交。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 undefined 来源 types.ts:22 packages/ui/src/components/color-picker/types.ts
id	string | undefined	undefined	设置触发按钮的原生 HTML id。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 undefined 来源 types.ts:23 packages/ui/src/components/color-picker/types.ts
ariaLabel	string | undefined	undefined	触发按钮的无障碍名称；未提供时回退到本地化占位文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 undefined 来源 types.ts:24 packages/ui/src/components/color-picker/types.ts
class 可空	ClassValue	undefined	追加到颜色选择器触发按钮的 CSS 类，支持 ClassValue 的数组和对象形式。
详情 声明类型 ClassValue 字面量 false null true 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPicker.vue 解析值 undefined 来源 types.ts:27 packages/ui/src/components/color-picker/types.ts

ColorPicker — 事件

名称	签名或类型	说明
@update:modelValue	[value: string | null]	颜色输入、拖动选择或清除时发出新的格式化颜色值；清除后为 null。
详情 声明类型 [value: string | null] 字面量 null 来源 ColorPicker.vue packages/ui/src/components/color-picker/ColorPicker.vue
@open	[]	面板打开时发出，不带参数。
详情 声明类型 [] 来源 ColorPicker.vue packages/ui/src/components/color-picker/ColorPicker.vue
@close	[]	面板关闭时发出，不带参数。
详情 声明类型 [] 来源 ColorPicker.vue packages/ui/src/components/color-picker/ColorPicker.vue
@update:open	[value: boolean]	面板开关状态变化时发出新布尔值，用于更新受控的 open。
详情 声明类型 [value: boolean] 字面量 false true 来源 ColorPicker.vue packages/ui/src/components/color-picker/ColorPicker.vue
@change	[value: string | null]	用户确认或清除颜色时发出最终值；与拖动过程中的 update:modelValue 区分。
详情 声明类型 [value: string | null] 字面量 null 来源 ColorPicker.vue packages/ui/src/components/color-picker/ColorPicker.vue

ColorPicker — 暴露成员

名称	签名或类型	说明
open	Ref<boolean, boolean>	面板开关状态的 Ref；通过组件实例读取或写入可程序化打开、关闭面板。
详情 声明类型 Ref<boolean, boolean> 字面量 false true 来源 ColorPicker.vue packages/ui/src/components/color-picker/ColorPicker.vue

ColorPickerHistory

ColorPickerHistory — 属性

名称	类型	默认值	说明
history 必填	readonly string[]	—	要展示的历史颜色字符串列表；非法颜色会被过滤。
详情 声明类型 readonly string[] 默认值详情 未声明默认值 — 来源 ColorPickerHistory.vue:9 packages/ui/src/components/color-picker/ColorPickerHistory.vue
modelValue 可空	string | null | undefined	null	当前颜色，用于高亮与历史颜色归一化后相同的色块。
详情 声明类型 string | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/color-picker/ColorPickerHistory.vue 解析值 null 来源 ColorPickerHistory.vue:10 packages/ui/src/components/color-picker/ColorPickerHistory.vue
size	"default" | "lg" | "sm" | undefined	"default"	历史色块的尺寸。
详情 声明类型 "default" | "lg" | "sm" | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/color-picker/ColorPickerHistory.vue 解析值 "default" 来源 ColorPickerHistory.vue:11 packages/ui/src/components/color-picker/ColorPickerHistory.vue
ariaLabel	string | undefined	undefined	历史颜色分组的无障碍名称；未提供时使用本地化标题。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPickerHistory.vue 解析值 undefined 来源 ColorPickerHistory.vue:12 packages/ui/src/components/color-picker/ColorPickerHistory.vue
clearLabel	string | undefined	undefined	清空历史按钮的无障碍名称；未提供时使用本地化文案。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPickerHistory.vue 解析值 undefined 来源 ColorPickerHistory.vue:13 packages/ui/src/components/color-picker/ColorPickerHistory.vue

ColorPickerHistory — 事件

名称	签名或类型	说明
@clear	[]	用户激活清空按钮时发出，不带参数。
详情 声明类型 [] 来源 ColorPickerHistory.vue packages/ui/src/components/color-picker/ColorPickerHistory.vue
@select	[value: string]	用户选择有效历史色块时发出该颜色字符串。
详情 声明类型 [value: string] 来源 ColorPickerHistory.vue packages/ui/src/components/color-picker/ColorPickerHistory.vue

ColorPickerInput

ColorPickerInput — 属性

名称	类型	默认值	说明
modelValue 可空	string | null | undefined	null	当前颜色；有效颜色会按 format 归一化显示，null 时输入框为空。
详情 声明类型 string | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/color-picker/ColorPickerInput.vue 解析值 null 来源 ColorPickerInput.vue:8 packages/ui/src/components/color-picker/ColorPickerInput.vue
format	"hex" | "rgb" | "hsl" | undefined	"hex"	输入框颜色值归一化及输出时使用的格式。
详情 声明类型 "hex" | "rgb" | "hsl" | undefined 字面量 "hex" "hsl" "rgb" 默认值详情 声明 'hex' 来源: packages/ui/src/components/color-picker/ColorPickerInput.vue 解析值 "hex" 来源 ColorPickerInput.vue:9 packages/ui/src/components/color-picker/ColorPickerInput.vue
showAlpha	boolean | undefined	false	格式化颜色值时是否保留透明度通道。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/color-picker/ColorPickerInput.vue 解析值 false 来源 ColorPickerInput.vue:10 packages/ui/src/components/color-picker/ColorPickerInput.vue
disabled	boolean | undefined	false	禁用原生文本输入。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/color-picker/ColorPickerInput.vue 解析值 false 来源 ColorPickerInput.vue:11 packages/ui/src/components/color-picker/ColorPickerInput.vue
ariaLabel	string | undefined	undefined	文本输入框的无障碍名称。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPickerInput.vue 解析值 undefined 来源 ColorPickerInput.vue:12 packages/ui/src/components/color-picker/ColorPickerInput.vue

ColorPickerInput — 事件

名称	签名或类型	说明
@update:modelValue	[value: string | null]	输入值为空或解析为有效颜色时发出；无效文本不会更新颜色值。
详情 声明类型 [value: string | null] 字面量 null 来源 ColorPickerInput.vue packages/ui/src/components/color-picker/ColorPickerInput.vue
@confirm	[value: string | null]	按 Enter 或离开输入框时确认有效颜色或空值；无效文本会恢复为当前 model 值。
详情 声明类型 [value: string | null] 字面量 null 来源 ColorPickerInput.vue packages/ui/src/components/color-picker/ColorPickerInput.vue

ColorPickerPanel

ColorPickerPanel — 属性

名称	类型	默认值	说明
modelValue 可空	string | null | undefined	null	面板当前颜色；null 表示没有已选颜色。
详情 声明类型 string | null | undefined 字面量 null 默认值详情 声明 null 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 null 来源 ColorPickerPanel.vue:27 packages/ui/src/components/color-picker/ColorPickerPanel.vue
format	ColorFormat | undefined	"hex"	面板产生和格式化颜色值时使用的颜色格式。
详情 声明类型 ColorFormat | undefined 字面量 "hex" "hsl" "rgb" 关联类型 ColorFormat 类型定义 — ColorFormat export type ColorFormat = 'hex' | 'rgb' | 'hsl' 默认值详情 声明 'hex' 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 "hex" 来源 ColorPickerPanel.vue:28 packages/ui/src/components/color-picker/ColorPickerPanel.vue
showAlpha	boolean | undefined	false	显示透明度控件并在颜色值中包含 alpha 通道。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 false 来源 ColorPickerPanel.vue:29 packages/ui/src/components/color-picker/ColorPickerPanel.vue
presets	string[] | readonly ColorPreset[] | undefined	按实例调用工厂函数	色板内容，可传字符串或 ColorPreset；未提供时使用内置默认色板。
详情 声明类型 string[] | readonly ColorPreset[] | undefined 关联类型 ColorPreset 类型定义 — ColorPreset export interface ColorPreset { readonly label: string readonly value: string readonly disabled?: boolean } 默认值详情 声明 () => DEFAULT_COLOR_PRESETS 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析表达式 () => DEFAULT_COLOR_PRESETS 来源 ColorPickerPanel.vue:30 packages/ui/src/components/color-picker/ColorPickerPanel.vue
showPresets	boolean | undefined	true	是否渲染预设色板区域。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 true 来源 ColorPickerPanel.vue:31 packages/ui/src/components/color-picker/ColorPickerPanel.vue
presetsLabel	string | undefined	undefined	预设区域标题；未提供时使用本地化文案。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 undefined 来源 ColorPickerPanel.vue:32 packages/ui/src/components/color-picker/ColorPickerPanel.vue
showHistory	boolean | undefined	true	是否显示颜色历史区域。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 true 来源 ColorPickerPanel.vue:33 packages/ui/src/components/color-picker/ColorPickerPanel.vue
historyMax	number | undefined	8	历史记录保留的最大颜色数量。
详情 声明类型 number | undefined 默认值详情 声明 8 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 8 来源 ColorPickerPanel.vue:34 packages/ui/src/components/color-picker/ColorPickerPanel.vue
historyStorageKey	string | undefined	undefined	传给颜色历史存储逻辑的 localStorage 键名。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 undefined 来源 ColorPickerPanel.vue:35 packages/ui/src/components/color-picker/ColorPickerPanel.vue
showInput	boolean | undefined	true	是否显示可编辑的颜色文本输入框。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 true 来源 ColorPickerPanel.vue:36 packages/ui/src/components/color-picker/ColorPickerPanel.vue
clearable	boolean | undefined	true	是否显示清除当前颜色的操作。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 true 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 true 来源 ColorPickerPanel.vue:37 packages/ui/src/components/color-picker/ColorPickerPanel.vue
size	ColorPickerSize | undefined	"default"	面板色块及控件的尺寸。
详情 声明类型 ColorPickerSize | undefined 字面量 "default" "lg" "sm" 关联类型 ColorPickerSize 类型定义 — ColorPickerSize export type ColorPickerSize = 'sm' | 'default' | 'lg' 默认值详情 声明 'default' 来源: packages/ui/src/components/color-picker/ColorPickerPanel.vue 解析值 "default" 来源 ColorPickerPanel.vue:38 packages/ui/src/components/color-picker/ColorPickerPanel.vue

ColorPickerPanel — 事件

名称	签名或类型	说明
@update:modelValue	[value: string | null]	颜色通过面板控件变化时发出新值。
详情 声明类型 [value: string | null] 字面量 null 来源 ColorPickerPanel.vue packages/ui/src/components/color-picker/ColorPickerPanel.vue
@clear	[]	用户清除当前颜色时发出，不带参数。
详情 声明类型 [] 来源 ColorPickerPanel.vue packages/ui/src/components/color-picker/ColorPickerPanel.vue
@confirm	[value: string | null]	用户确认面板颜色时发出最终颜色值。
详情 声明类型 [value: string | null] 字面量 null 来源 ColorPickerPanel.vue packages/ui/src/components/color-picker/ColorPickerPanel.vue

ColorPickerSwatch

ColorPickerSwatch — 属性

名称	类型	默认值	说明
value 必填	string	—	色块表示的颜色字符串；无效颜色禁用该按钮。
详情 声明类型 string 默认值详情 未声明默认值 — 来源 ColorPickerSwatch.vue:11 packages/ui/src/components/color-picker/ColorPickerSwatch.vue
label	string | undefined	undefined	色块提示文本，并作为无障碍名称的回退值。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPickerSwatch.vue 解析值 undefined 来源 ColorPickerSwatch.vue:12 packages/ui/src/components/color-picker/ColorPickerSwatch.vue
selected	boolean | undefined	false	是否将色块标记为选中，并反映到 aria-pressed。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/color-picker/ColorPickerSwatch.vue 解析值 false 来源 ColorPickerSwatch.vue:13 packages/ui/src/components/color-picker/ColorPickerSwatch.vue
disabled	boolean | undefined	false	禁用色块的鼠标和键盘选择。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/color-picker/ColorPickerSwatch.vue 解析值 false 来源 ColorPickerSwatch.vue:14 packages/ui/src/components/color-picker/ColorPickerSwatch.vue
size	"default" | "lg" | "sm" | undefined	"default"	按钮色块的尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/color-picker/ColorPickerSwatch.vue 解析值 "default" 来源 ColorPickerSwatch.vue:15 packages/ui/src/components/color-picker/ColorPickerSwatch.vue
ariaLabel	string | undefined	undefined	显式设置色块按钮的无障碍名称；优先于 label 和颜色值。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/color-picker/ColorPickerSwatch.vue 解析值 undefined 来源 ColorPickerSwatch.vue:16 packages/ui/src/components/color-picker/ColorPickerSwatch.vue

ColorPickerSwatch — 事件

名称	签名或类型	说明
@select	[value: string]	有效且未禁用的色块被激活时发出其颜色字符串。
详情 声明类型 [value: string] 来源 ColorPickerSwatch.vue packages/ui/src/components/color-picker/ColorPickerSwatch.vue

可访问性

触发器

按键	操作
Enter / Space	打开面板（禁用时不响应）
Escape	关闭面板

饱和度/亮度区域

按键	操作
← / →	调整饱和度（步长 1，Shift 步长 10）
↑ / ↓	调整亮度（步长 1，Shift 步长 10）

色相滑块

按键	操作
← / →	调整色相（步长 1，Shift 步长 15）

透明度滑块

按键	操作
← / →	调整透明度（步长 0.01，Shift 步长 0.1）

预设与历史色块

预设与历史色块是原生 <button> 元素（可 Tab 聚焦，Enter/Space 激活），选中态以 aria-pressed 表达，并带有 focus-visible 焦点环。非法色值会被过滤（历史）；预设中的非法值以 opacity-40 弱化显示，并置为原生 disabled（不可聚焦、cursor-not-allowed、键盘无法激活）。

常见问题

Q: 切换 format 后，之前的 modelValue 值格式不匹配怎么办？

A: 组件内部会自动将已有的颜色值归一化为当前 format 对应的格式。例如，从 hex 切换到 rgb 时，之前的 #FF6B6B 会被自动转换为 rgb(255, 107, 107)。无需手动处理格式转换。

Q: 颜色历史记录存储在哪里？如何清除？

A: 颜色历史记录默认存储在浏览器的 localStorage 中，键名由 historyStorageKey 属性控制（默认为 'brutx-color-history'）。可以通过浏览器开发者工具的 Application 面板清除，或在代码中调用 localStorage.removeItem('brutx-color-history') 清除。设置不同的 historyStorageKey 可以为不同的使用场景维护独立的历史记录。

Q: 启用 showAlpha 后输出的值格式有什么变化？

A: 启用透明度通道后，输出值会包含 alpha 信息。hex 格式变为 8 位（如 #FF6B6B80），rgb 格式变为 rgba()，hsl 格式变为 hsla()。关闭 showAlpha 后输出值恢复为不含透明度的标准格式。