安裝
Terminal
pnpm dlx shadcn-vue add @admin/color-pickerimport type { ColorPickerSwatch } from '@/components/admin/color-picker'import { AdminColorPicker, AdminColorPickerContent, AdminColorPickerTrigger,} from '@/components/admin/color-picker'用法
<script setup lang="ts">import type { ColorPickerSwatch } from '@/components/admin/color-picker'import { ref } from 'vue'import { AdminColorPicker, AdminColorPickerContent, AdminColorPickerTrigger} from '@/components/admin/color-picker'const swatches = [ { value: 'red', color: '#e1615e' }, { value: 'orange', color: '#ff7a00' }, { value: 'green', color: '#7abe53' }, { value: 'blue', color: '#4567f3' }, { value: 'violet', color: '#694cfe' }] as const satisfies readonly ColorPickerSwatch[]const value = ref<(typeof swatches)[number]['value']>()</script><template> <admin-color-picker v-model="value" :swatches="swatches"> <admin-color-picker-trigger /> <admin-color-picker-content /> </admin-color-picker></template>場景
停用狀態
<script setup lang="ts">import type { ColorPickerSwatch } from '@/components/admin/color-picker'import { ref } from 'vue'import { AdminColorPicker, AdminColorPickerContent, AdminColorPickerTrigger} from '@/components/admin/color-picker'const swatches = [ { value: 'red', color: '#e1615e' }, { value: 'orange', color: '#ff7a00' }, { value: 'green', color: '#7abe53' }, { value: 'blue', color: '#4567f3' }, { value: 'violet', color: '#694cfe' }] as const satisfies readonly ColorPickerSwatch[]const value = ref<(typeof swatches)[number]['value'] | undefined>('blue')</script><template> <admin-color-picker v-model="value" disabled :swatches="swatches"> <admin-color-picker-trigger /> <admin-color-picker-content /> </admin-color-picker></template>自訂 trigger
當預設 trigger 樣式不符需求，透過 AdminColorPickerTrigger 的 default slot 自行渲染觸發器；slot 內第一個元素會直接成為觸發 DOM。
<script setup lang="ts">import type { ColorPickerSwatch } from '@/components/admin/color-picker'import { ref } from 'vue'import { cn } from '@/lib/utils'import { AdminColorPicker, AdminColorPickerContent, AdminColorPickerTrigger} from '@/components/admin/color-picker'const swatches = [ { value: 'red', color: '#e1615e', label: '紅' }, { value: 'orange', color: '#ff7a00', label: '橘' }, { value: 'green', color: '#7abe53', label: '綠' }, { value: 'blue', color: '#4567f3', label: '藍' }, { value: 'violet', color: '#694cfe', label: '紫' }] as const satisfies readonly ColorPickerSwatch[]const value = ref<(typeof swatches)[number]['value']>()</script><template> <admin-color-picker v-model="value" :swatches="swatches"> <admin-color-picker-trigger v-slot="{ swatch, open, disabled }"> <button type="button" :class=" cn(` flex items-center gap-1 rounded-full border border-text-30 bg-bg-90 px-3 py-1 text-text-90 outline-hidden hover:border-text-50 focus-visible:ring-2 focus-visible:ring-info-40 data-[state=open]:border-info-40 `) " :disabled="disabled" > <span class="size-3 rounded-full" :style="{ backgroundColor: swatch?.color ?? 'transparent' }" ></span> <span class="text-sm">{{ swatch?.label ?? swatch?.value ?? '未選擇' }}</span> <span class="text-xs text-text-50">{{ open ? '收合' : '展開' }}</span> </button> </admin-color-picker-trigger> <admin-color-picker-content /> </admin-color-picker></template>API 參考
swatches 中每個 value 須唯一，且 v-model 綁定值須為其中某個 value；若綁定值不在清單內，trigger 會顯示為未選狀態。
以 as const satisfies readonly ColorPickerSwatch[] 宣告 swatches，modelValue 會收斂成各 value 的 literal union，綁定清單外的字串即觸發 TypeScript 型別錯誤；未加 as const 時 modelValue 退回 string，維持向後相容。
組成
<script setup lang="ts">import type { ColorPickerSwatch } from '@/components/admin/color-picker'const swatches = [ { value: 'red', color: '#e1615e' }, { value: 'blue', color: '#4567f3' },] as const satisfies readonly ColorPickerSwatch[]const value = ref<(typeof swatches)[number]['value']>()</script><template> <admin-color-picker v-model="value" :swatches="swatches"> <admin-color-picker-trigger /> <admin-color-picker-content /> </admin-color-picker></template>需要自訂 trigger 時放入 slot 內容：
<template> <admin-color-picker v-model="value" :swatches="swatches"> <admin-color-picker-trigger v-slot="{ swatch, disabled }"> <button :disabled="disabled"> <span v-if="swatch" :style="{ background: swatch.color }"></span> <span v-else>選擇顏色</span> </button> </admin-color-picker-trigger> <admin-color-picker-content /> </admin-color-picker></template>admin-color-picker
Props
| 名稱 | 型別 | 預設值 | 說明 |
|---|---|---|---|
class | unknown | — | — |
modelValue | TValue | undefined | — | 受控值，以 `v-model` 綁定；須為 `swatches` 中某個 `value`，否則 trigger 視為未選 |
swatches* | readonly ColorPickerSwatch<TValue>[] | — | 可選顏色清單（必填）；每個 `value` 須唯一。以 `as const satisfies readonly ColorPickerSwatch[]` 宣告時，`modelValue` 會收斂成各 `value` 的 literal union |
disabled | boolean | undefined | false | 設為 `true` 時禁用 picker |
* 代表必填
Events
| 名稱 | Payload | 說明 |
|---|---|---|
update:modelValue | TValue | undefined | modelValue 更新時觸發；未選 / 取消選擇時為 `undefined` |
Slots
| 名稱 | Bindings | 說明 |
|---|---|---|
default | {} | — |
admin-color-picker-content
Props
| 名稱 | 型別 | 預設值 | 說明 |
|---|---|---|---|
align | "start" | "end" | "center" | undefined | "center" | 對齊 trigger 之位置 |
sideOffset | number | undefined | 4 | content 與 trigger 之間的距離 |
class | ClassValue | — | 根元素之自訂 class |
admin-color-picker-trigger
Props
| 名稱 | 型別 | 預設值 | 說明 |
|---|---|---|---|
class | unknown | — | — |
Slots
| 名稱 | Bindings | 說明 |
|---|---|---|
default | { value: string | undefined; swatch: ColorPickerSwatch<string> | undefined; open: boolean; disabled: boolean; } | 預設 slot；若提供則以自訂內容取代預設 trigger，並傳遞當前值、選中之 swatch、open 與 disabled 狀態 |
更新紀錄
- revert: 還原清除色票外框與勾勾顏色修正d36c714
- fix: 修正清除色票在浮層中看不見a177831
- fix: 補上 Vue 核心 API 的顯式 import3c2c030
- feat: modelValue 支援收斂為 swatch value 的 literal union0238cc9
- fix: 修正停用狀態行為並補 swatch 群組 a11yc5ae5c1
- refactor: cn import 路徑統一為 @/lib/utils1c379e6
- chore: 啟用 vue/no-useless-v-bind 與 vue/prefer-separate-static-class16c34a8