简单易用
简洁的 v-model API，UI 圆角和过渡动画都已就位
vColorPickerVue 3 颜色选择器
轻量、可访问的 Vue 3 颜色选择器组件
选中的颜色: #ff0000
英文文案: #3b82f6
日文文案: #10b981
<template>
<colorPicker
v-model="color"
locale="en-US"
:messages="{ moreColors: '自定义文案...' }"
/>
</template>默认按视口剩余空间自动选位，也可以通过 placement 锁定到任意一侧。
固定到 top-end: #f59e0b
<colorPicker v-model="color" placement="top-end" />
<colorPicker v-model="color" placement="bottom" /> <!-- 锁定向下，水平自动 -->npm install vcolorpicker -S在 main.js 中引入插件并注册：
import { createApp } from 'vue'
import vcolorpicker from 'vcolorpicker'
import App from './App.vue'
const app = createApp(App)
app.use(vcolorpicker)
app.mount('#app')在组件中使用：
<template>
<colorPicker v-model="color" />
</template>
<script setup>
import { ref } from 'vue'
const color = ref('#ff0000')
</script>| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
v-model / modelValue | string | — | 当前颜色值 |
defaultColor | string | #000000 | 「默认颜色」按钮重置使用的颜色 |
disabled | boolean | false | 禁用状态 |
locale | 'zh-CN' | 'en-US' | 'ja-JP' | 自动检测 | 面板内置文案语言；不传时跟随 <html lang> / navigator.language |
messages | Partial<ColorPickerMessages> | — | 用自定义文案覆盖内置语言包 |
placement | ColorPickerPlacement | 'auto' | 面板位置：'auto' / 'top' / 'bottom' / 'top-start' / 'top-end' / 'bottom-start' / 'bottom-end'。'auto' 根据视口剩余空间自动决定；带方向时锁定对应轴 |
| 事件名 | 参数 | 说明 |
|---|---|---|
change | (color: string) | 颜色值改变时触发 |
update:modelValue | (color: string) | v-model 同步事件 |
open | — | 面板打开时触发 |
close | — | 面板关闭时触发（点击外部 / Esc / 选色后自动关闭） |
hover | (color: string) | 鼠标移到色块时触发；离开时携带空字符串 |
<colorPicker v-model="color" @change="onColorChange" />通过模板 ref 暴露的方法可命令式控制组件：
<script setup lang="ts">
import { ref } from 'vue'
import type { ColorPickerInstance } from 'vcolorpicker'
const pickerRef = ref<ColorPickerInstance>()
const color = ref('#ff0000')
const openProgrammatically = () => pickerRef.value?.open()
</script>
<template>
<colorPicker ref="pickerRef" v-model="color" />
<button @click="openProgrammatically">打开面板</button>
</template>| 方法 | 说明 |
|---|---|
open() | 打开面板（disabled 时无效） |
close() | 关闭面板 |
focus() | 把焦点移回触发按钮 |
Tab 聚焦Enter / Space 激活；触发按钮聚焦时按 ↑ / ↓ 也可打开面板Esc 关闭并把焦点送回触发按钮role="button" + aria-haspopup="dialog" + aria-expanded；面板带 role="dialog"；每个色块带 aria-label="#RRGGBB":focus-visible，鼠标用户不会被打扰document / navigator 时，初始 locale 固定为 zh-CN（或显式 locale prop），保证服务端和客户端首屏一致，无 hydration mismatchonMounted 后才执行。如果要避免挂载后从中文跳变到其他语言的闪动，建议在 SSR 场景显式传 locale prop<html lang> 变化的 MutationObserver 是模块级单例，多实例只占一份资源无需穿透选择器，覆盖以下变量即可：
.m-colorPicker {
--vcp-swatch-size: 15px;
--vcp-panel-width: 190px;
--vcp-panel-bg: #fff;
--vcp-panel-border: 1px solid #ddd;
--vcp-panel-radius: 2px;
--vcp-panel-shadow: 0 8px 24px rgba(0, 0, 0, .18);
--vcp-panel-padding: 10px;
--vcp-text-color: #333;
--vcp-focus-color: #4e81bb;
--vcp-transition: .3s ease;
--vcp-z-index: 10000;
}例：暗色主题
.dark .m-colorPicker {
--vcp-panel-bg: #1f1f1f;
--vcp-panel-border: 1px solid #333;
--vcp-text-color: #eee;
}包内导出的类型：
import type {
ColorPickerProps,
ColorPickerEmits,
ColorPickerExposed,
ColorPickerInstance,
ColorPickerLocale,
ColorPickerMessages,
ColorPickerPlacement
} from 'vcolorpicker'支持。这个组件面向 Vue 3 项目设计，接入方式就是标准的 v-model。
可以。通过 locale="zh-CN"、locale="en-US" 或 locale="ja-JP" 使用内置文案，也可以通过 messages 自定义覆盖面板文字。
支持。当前包提供完整的类型声明：props、emits、实例方法和辅助类型都有导出。
支持。点击 更多颜色... 后，会在兼容浏览器中调用 HTML5 原生取色器。
可以。Tab 聚焦、Enter / Space 激活、Esc 关闭，ARIA 角色和标签都已配置完整。