@aurouscia/au-color-picker

au-color-picker

vue3颜色选择控件，支持鼠标/手指的点击和拖动

用法

npm i @aurouscia/au-color-picker

//main.ts（必须导入样式）
import '@aurouscia/au-color-picker/style.css'

//xxx.vue
import { AuColorPicker } from '@aurouscia/au-color-picker';
import { AuColorPickerPresetsNested } from '@aurouscia/au-color-picker';

仅自定义

<AuColorPicker
    v-model="'绑定颜色值'"
    :initial="'初始值（优先级低于v-model）'"
    @done="'面板关闭回调'"
    ></AuColorPicker>

输入模式持久化

AuColorPicker 支持通过 localStorage 记住用户上次选择的输入模式（HEX / RGB / HSV）。

• 默认行为：未指定 color-mode-storage-key 时，不启用持久化，每次打开默认 HEX 模式（向后兼容）。
• 启用持久化：传入字符串指定 localStorage 键名，例如 "acp-color-mode"。
• 自定义键名：适用于同一页面使用多个选择器时避免冲突。
• 禁用持久化：传入 false 或空字符串可显式禁用（与不传效果相同）。
• 默认模式：通过 color-mode 属性指定默认输入模式（'rgb' | 'hsv' | 'hex'）。当启用持久化且 localStorage 中已有值时，优先使用存储值；否则回退到 color-mode；未指定 color-mode 时回退到 'hex'。

<!-- 默认：不启用持久化，默认 HEX -->
<AuColorPicker v-model="color" />

<!-- 不启用持久化，但默认 RGB -->
<AuColorPicker v-model="color" color-mode="rgb" />

<!-- 启用持久化（使用推荐键名） -->
<AuColorPicker v-model="color" color-mode-storage-key="acp-color-mode" />

<!-- 启用持久化 + 指定默认模式 -->
<AuColorPicker v-model="color" color-mode-storage-key="acp-color-mode" color-mode="hsv" />

<!-- 自定义键名 -->
<AuColorPicker v-model="color" color-mode-storage-key="my-app-color-mode" />

<!-- 显式禁用持久化（与不传效果相同） -->
<AuColorPicker v-model="color" :color-mode-storage-key="false" />

预设+自定义

⚠️注意：“选中的预设”是与“自定义颜色”独立的两个状态
这使得模型的颜色可以依赖于系统全局配置（预设的颜色）

const presets:NamedPreset[] = [
  {
    name: '水系', //名称不可重复
    colorHex: '#c3e5eb'
  },
  {
    name: '绿地',
    colorHex: '#ceeda4'
  },
]

<AuColorPickerPresetsNested 
    :presets="'预设列表'"
    v-model="'绑定颜色值'"
    :initial="'初始值（优先级低于v-model）'"
    v-model:model-value-selected-preset="'绑定预设name'"
    :initial-selected-preset="'初始选择预设（优先级低于v-model）'"
    @done="'面板关闭回调'"
    ></AuColorPickerPresetsNested>

覆盖当前值（旧版，新版直接赋值v-model）

const picker = ref<InstanceType<typeof AuColorPicker>>()
const pickerNested = ref<InstanceType<typeof AuColorPickerPresetsNested>>()
function enforceToDemo(){
  picker.value?.enforceTo('#ff00ff')
  pickerNested.value?.enforceCustomValueTo('#ff00ff')
  pickerNested.value?.enforcePresetTo('水系')
}

组件属性定义

//位置描述
type Pos = 'left'|'right'|number

//AuColorPicker的属性
export interface PickerProps{
    initial?: string //初始值
    entryStyles?: CSSProperties //入口按钮的样式
    entryActiveStyles?: CSSProperties //入口按钮的样式（当面板展开）
    entryClassName?: string //入口按钮的类名
    pos?: Pos //面板位置描述
    panelBaseZIndex?:number //面板的zIndex基础值
    entryRespondDelay?:number //入口按钮点击后，面板展开的延迟（ms）
    panelClickStopPropagation?:boolean //面板点击是否阻止冒泡
    showPackageName?:boolean //是否显示包名
    colorModeStorageKey?: string | false //输入模式持久化的 localStorage 键名，传 false 或空字符串可禁用
    colorMode?: 'rgb' | 'hsv' | 'hex' //输入模式的默认值，storage 中无值时回退到此，默认 'hex'
}

//AuColorPickerPresetsNested的属性
export interface PickerWithPresetsProps extends PickerProps{
    initialSelectedPreset?:string //初始选择预设名称（undefined即为自定义）
    presets?: NamedPreset[] //预设列表
    posInternal?: Pos //使用自定义时，自定义颜色选择器面板的位置描述
}

//预设列表项描述
export interface NamedPreset{
    colorHex:string,
    name:string
}

更新记录

2.2.0

新增 Tab 键输入框循环聚焦功能。面板打开时按 Tab 键可在输入框间循环切换，并自动选中已有值。

2.1.0

新增 color-mode-storage-key 和 color-mode 属性，支持通过 localStorage 持久化用户选择的输入模式（HEX / RGB / HSV）。默认不启用持久化，向后兼容。

2.0.0

将 vue 改为 peerDependency（正确做法）

1.1.0

修复了旧浏览器上失效的问题（消除过新的context.reset函数）

许可证

MIT