FxColorPicker 颜色选择器

点击触发色块，在浮层中选色。基于 FxColorPickerPanel + FxTooltip，支持透明度、预定义色与尺寸。

FxColorPicker 属于 @fx/components。

基础用法

v-model 绑定颜色字符串（hex / rgb / rgba / hsl 等）。

<template>
  <div class="demo-color-block">
    <span class="demonstration">带默认值</span>
    <FxColorPicker v-model="color1" />
  </div>
  <div class="demo-color-block">
    <span class="demonstration">不带默认值</span>
    <FxColorPicker v-model="color2" />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxColorPicker } from "@fx/components"

const color1 = ref("#1E293B")
const color2 = ref()
</script>

<style scoped>
.demo-color-block {
  display: flex;
  align-items: center;
  margin-bottom: 16px;
}
.demo-color-block .demonstration {
  margin-right: 16px;
}
</style>

透明度

show-alpha 开启透明度滑块，支持 rgba / hsla 等带 alpha 通道的格式。

<template>
  <FxColorPicker v-model="color" show-alpha />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxColorPicker } from "@fx/components"

const color = ref("rgba(19, 206, 102, 0.8)")
</script>

预定义颜色

predefine 传入预设色板，用户可快速选择。

<template>
  <FxColorPicker v-model="color" show-alpha :predefine="predefineColors" />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxColorPicker } from "@fx/components"

const color = ref("rgba(255, 69, 0, 0.68)")
const predefineColors = ref([
  "#ff4500",
  "#ff8c00",
  "#ffd700",
  "#90ee90",
  "#00ced1",
  "#1e90ff",
  "#c71585",
  "rgba(255, 69, 0, 0.68)",
  "rgb(255, 120, 0)",
  "hsv(51, 100, 98)",
  "hsva(120, 40, 94, 0.5)",
  "hsl(181, 100%, 37%)",
  "hsla(209, 100%, 56%, 0.73)",
  "#c7158577",
])
</script>

尺寸

size 控制触发色块大小（large / default / small）。

<template>
  <div class="demo-color-sizes">
    <FxColorPicker v-model="color" size="large" />
    <FxColorPicker v-model="color" />
    <FxColorPicker v-model="color" size="small" />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxColorPicker } from "@fx/components"

const color = ref("#1E293B")
</script>

<style scoped>
.demo-color-sizes .fx-color-picker:not(:last-child) {
  margin-right: 16px;
}
</style>

即时模式

immediate 开启后选择即提交 v-model：拖动过程实时同步 update:modelValue / active-change，change 只在离散完成点（色块点击、拖动结束、输入确认）触发；底部「确定」按钮退化为「完成 / 关闭」，关闭面板不回退已选值。

即时模式下可另设 footer=false 隐藏面板底部（输入框与按钮，下例第二个选择器）；确认模式下设置 footer=false 视为无效，底部照常渲染。

<template>
  <div class="flex items-center gap-6">
    <FxColorPicker v-model="color" immediate :predefine="predefineColors" />
    <FxColorPicker
      v-model="colorNoFooter"
      immediate
      :footer="false"
      :predefine="predefineColors"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxColorPicker } from "@fx/components"

const color = ref("#409eff")
const colorNoFooter = ref("#67c23a")
const predefineColors = ref(["#ff4500", "#00ced1", "#1e90ff", "#c71585"])
</script>

历史色与圆形

history 在面板底部上方显示最近选择的颜色（跨实例共享并持久化，上限 8 条）；predefine 与 history 区块各带分组标题（「预设」/「最近使用」）与 small 分割线；round 使触发器与色块呈圆形。

<template>
  <FxColorPicker
    v-model="color"
    history
    round
    show-alpha
    :predefine="predefineColors"
  />
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxColorPicker } from "@fx/components"

const color = ref("rgba(64, 158, 255, 0.8)")
const predefineColors = ref(["#ff4500", "#00ced1", "#1e90ff", "#c71585"])
</script>

局部引入

import { FxColorPicker } from "@fx/components"

API

Attributes

属性	说明	类型	默认值
model-value / v-model	绑定值	string | null	—
show-alpha	是否显示透明度滑块	boolean	false
color-format	v-model 的颜色格式	'rgb' | 'hex' | 'prgb' | 'hsl' | 'hsv' | 'name' | 'hex8'	—
disabled	是否禁用	boolean	false
clearable	是否显示清空按钮	boolean	true
size	尺寸	'large' | 'default' | 'small'	default
predefine	预定义颜色	string[]	—
footer	是否显示面板底部（输入框与清空/确定按钮），仅 immediate 模式下可设为 false	boolean	true
immediate	即时提交（选择即更新 v-model）	boolean	false
history	是否显示上次选择色块	boolean	false
round	触发器与色块是否为圆形	boolean	false
popper-class	浮层自定义类名	string | object | array	—
popper-style	浮层自定义样式	string | CSSProperties	—
teleported	是否 teleport 到 body	boolean	true
append-to	浮层挂载目标	string | HTMLElement	body
persistent	浮层是否持久化	boolean	true
tabindex	tabindex	string | number	0
validate-event	是否触发表单校验	boolean	true
value-on-clear	清空时的返回值	string | null	—
aria-label	无障碍标签	string	颜色选择器

Events

名称	说明
change	值变化（确认 / 清空时触发）
active-change	面板内当前色实时变化
focus	触发元素聚焦
blur	触发元素失焦
clear	清空

Slots

名称	说明
default	触发区（默认渲染色块）
footer	面板底部（默认放清空 / 确认按钮；footer=false 时不渲染）

Exposes

名称	说明
color	当前颜色对象（基于 @ctrl/tinycolor）
show	手动展开
hide	手动收起
focus	聚焦触发元素
blur	失焦触发元素

实现说明

• 浮层引擎基于 FxTooltip（@floating-ui/dom），点击外部 / Esc 关闭
• 颜色核心基于 @ctrl/tinycolor，支持 hex/rgb/hsl/hsv 等格式互转
• 历史色通过 localStorage（key fx-color-picker:history）跨实例共享：新色置顶去重、上限 8 条、空值与清空不入
• 样式走 @fx/styles token，亮暗自动跟随