ColorPicker 颜色选择器

用于选择颜色值，支持 hex / rgb / hsl 三种格式与透明度。

何时使用

• 需要让用户从任意颜色中挑选一个（品牌色、标签色、图表配色）。
• 需要精确输入颜色值（设计稿给定 hex，或按 rgb/hsl 通道微调）。
• 提供预设色板时，可同时给出 swatches 让用户快速选择。

基础用法

v-model 绑定的是颜色字符串。点击色块展开面板，拖动取色区或色相条调整颜色。

#165dff

<template>
  <x-color-picker v-model="value" />
  <p role="status">{{ value }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref('#165dff');
</script>

受控值与事件

change 在颜色变化时触发，携带当前颜色字符串。

等待操作

<template>
  <x-color-picker v-model="value" @change="handleChange" />
  <p role="status">{{ changeLog }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref('#00b42a');
const changeLog = ref('等待操作');

const handleChange = (value: string) => {
  changeLog.value = `change: ${value}`;
};
</script>

透明度

默认开启透明度（showAlpha），面板会多出透明度条，输出值为 8 位 hex。关闭后会忽略 alpha。

<template>
  <x-color-picker v-model="value" />
  <x-color-picker :default-value="value" :show-alpha="false" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref('#f53f3f80');
</script>

格式切换

modes 决定面板中可切换的输入格式。只给 hex 时面板只显示一个文本输入框。

<template>
  <x-color-picker v-model="value" :modes="['hex']" />
  <x-color-picker v-model="value" :modes="['hex', 'rgb']" />
  <x-color-picker v-model="value" :modes="['hex', 'rgb', 'hsl']" />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref('#ff7d00');
</script>

预设颜色

swatches 提供预设色块，点击后取色区、滑轨与输入框会同步。

#722ed1

<template>
  <x-color-picker v-model="value" :swatches="swatches" />
  <p role="status">{{ value }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref('#722ed1');
const swatches = ['#165dff', '#00b42a', '#ff7d00', '#f53f3f', '#722ed1'];
</script>

尺寸与禁用

size 与表单控件一致；disabled 会禁用触发器与面板内所有交互。

<template>
  <x-color-picker v-model="value" size="small" />
  <x-color-picker v-model="value" size="medium" />
  <x-color-picker v-model="value" size="large" />
  <x-color-picker v-model="value" disabled />
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref('#0fc6c2');
</script>

自定义触发器

trigger 插槽可替换默认色块按钮；default 插槽内容会渲染在色块旁边。

<template>
  <x-color-picker v-model="value">
    <template #trigger="{ value, visible }">
      <button type="button">{{ visible ? '选择中' : value }}</button>
    </template>
  </x-color-picker>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const value = ref('#165dff');
</script>

在 Form 中校验

品牌色

<template>
  <x-form ref="formRef" :model="formModel" :rules="rules" layout="vertical">
    <x-form-item field="brandColor" label="品牌色">
      <x-color-picker v-model="formModel.brandColor" :swatches="swatches" />
    </x-form-item>
  </x-form>
  <x-button type="primary" size="small" @click="handleValidate">校验</x-button>
  <x-button size="small" @click="handleReset">重置</x-button>
  <p role="status">{{ result }}</p>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import type { FormInstance, FieldRule } from 'x-next';

const formRef = ref<FormInstance>();
const formModel = reactive({ brandColor: '#165dff' });
const swatches = ['#165dff', '#00b42a', '#ff7d00'];
const result = ref('');
const rules: Record<string, FieldRule[]> = {
  brandColor: [{ required: true, message: '请选择品牌色' }],
};

const handleValidate = async () => {
  const errors = await formRef.value!.validate();
  result.value = errors ? '校验失败' : '校验通过';
};
const handleReset = () => {
  formRef.value!.resetFields();
  result.value = '已重置';
};
</script>

按需导入

import { ColorPicker } from 'x-next';

样式按需引入（base.css 为共享基础层，多个组件只需引入一次）：

import 'x-next/style/base.css';
import 'x-next/style/color-picker.css';

Props

属性	说明	类型	默认值
modelValue	颜色值，支持 hex / rgb / hsl	string	-
defaultValue	非受控初值	string	品牌蓝
show	面板是否可见（受控）	boolean	-
defaultShow	面板默认是否可见	boolean	false
modes	可选的颜色格式	('hex' | 'rgb' | 'hsl')[]	['hex', 'rgb', 'hsl']
showAlpha	是否启用透明度	boolean	true
swatches	预设色块	string[]	[]
showConfirm	是否展示确认按钮	boolean	true
showClear	是否展示清除按钮	boolean	true
disabled	是否禁用	boolean	false
size	尺寸	'mini' | 'small' | 'medium' | 'large'	跟随全局配置
popupContainer	面板挂载容器	string | HTMLElement	-

Events

事件名	说明	参数
update:modelValue	颜色变化	(value: string)
change	颜色变化	(value: string)
update:show	面板显隐变化	(visible: boolean)
showChange	面板显隐变化	(visible: boolean)
confirm	点击确认按钮	(value: string)
clear	点击清除按钮	-

Slots

插槽名	说明	参数
trigger	自定义触发器	{ value: string; visible: boolean }
default	触发器内的补充内容	-

交互说明

• 值形态：v-model 始终输出 hex 字符串（showAlpha 开启且存在透明度时为 8 位），便于持久化；面板内部允许按 rgb / hsl 输入后再换算。
• 键盘操作：取色区与两条滑轨都可聚焦，方向键微调（按住 Shift 步长更大）；Esc 关闭面板并把焦点还给触发器。
• 颜色解析：支持 #rgb / #rgba / #rrggbb / #rrggbbaa、rgb() / rgba()、hsl() / hsla()，逗号与空格语法均可。传空或非法值时面板回退到兜底色，不会崩溃。
• 受控显隐：传入 show 后组件不再自行改变显隐状态，需监听 showChange 更新。
• 已知限制：拖拽取色依赖鼠标事件，未实现触摸拖拽。