xtf-color-picker

组件说明

xtf-color-picker 是颜色选择器组件，用于选取颜色值。支持色相/饱和度/明度面板拖拽、透明度调节、HEX/Alpha 输入、预设色板、弹出/内联模式和取色器，适用于主题配置、表单颜色字段和设计工具等场景。

---

基础用法

1. 最简示例

通过 v-model 绑定颜色值，并设置 show-trigger 显示点击触发器：

<template>
  <xtf-color-picker v-model="color" show-trigger />
</template>

<script>
export default {
  data() {
    return {
      color: '#3B82F6'
    }
  }
}
</script>

2. 透明度与输入

通过 showAlpha 启用透明度滑块，通过 showInputs 显示 HEX 输入框：

<template>
  <xtf-color-picker v-model="color" title="选择颜色" show-alpha show-inputs show-preview />
</template>

<script>
export default {
  data() {
    return {
      color: 'rgba(59, 130, 246, 0.8)'
    }
  }
}
</script>

3. 预设色板

通过 presets 设置预设颜色列表：

<template>
  <xtf-color-picker v-model="color" title="主题色" show-presets :presets="presetColors" />
</template>

<script>
export default {
  data() {
    return {
      color: '#3B82F6',
      presetColors: ['#3B82F6', '#10B981', '#F59E0B', '#EF4444', '#0EA5E9', '#8B5CF6', '#EC4899']
    }
  }
}
</script>

4. 内联模式

通过 inline 将选择器直接嵌入页面：

<template>
  <xtf-color-picker
    v-model="color"
    title="选择颜色"
    display="inline"
    show-preview
    show-presets
    :presets="presetColors"
  />
</template>

<script>
export default {
  data() {
    return {
      color: '#10B981',
      presetColors: ['#3B82F6', '#10B981', '#EF4444']
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
modelValue	String	''	颜色值（HEX 或 RGBA）	双向绑定
title	String	'选择颜色'	选择器标题	标题
value	String	''	兼容绑定值，modelValue 优先	双向绑定
show / display	Boolean / String	false / 'popup'	弹层显示和模式（popup / inline）	展示
format	String	'hex'	输出格式：'hex' / 'hexa' / 'rgba'，非法值按 'hex' 处理	输出值
showAlpha	Boolean	false	是否显示透明度滑块	透明度
showPreview	Boolean	true	是否显示预览区	颜色预览
showInputs	Boolean	true	是否显示输入框	输入框
showHexInput	Boolean	true	是否显示 HEX 输入	HEX 输入
showAlphaInput	Boolean	true	是否显示 Alpha 输入	Alpha 输入
showPresets	Boolean	true	是否显示预设色板	预设色板
showActions	Boolean	true	是否显示操作按钮	操作按钮
showHeader	Boolean	true	是否显示头部	头部显示
presets	Array	[]	预设颜色字符串列表；空数组时使用组件内置色板	预设颜色
showTrigger	Boolean	false	是否显示弹出模式的默认触发器；内联模式不显示	触发器
triggerLabel	String	''	触发器标签文字	触发器标签
triggerPlaceholder	String	'点击选择颜色'	触发器占位文字	占位提示
triggerDisabled	Boolean	false	触发器是否禁用	禁用触发器
triggerStyle	String | Object	''	默认触发器的自定义样式	触发器样式
confirmText / cancelText	String	'确认' / '取消'	确认、取消按钮文字	操作按钮
disabled	Boolean	false	是否全局禁用	禁用
closeOnClickOverlay	Boolean	true	点击遮罩是否关闭	关闭行为
overlay	Boolean	true	是否显示遮罩	遮罩
safeAreaInsetBottom	Boolean	true	是否适配底部安全区	安全区
enableEyeDropper	Boolean	false	是否启用取色器	取色器
popupMaxHeight	String | Number	''	弹出内容最大高度	控制高度
stickyActions	Boolean | String	弹出模式 true；内联模式 false	操作按钮是否吸底；未传入时按展示模式决定	吸底操作
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
update:modelValue	颜色值变更时触发	(value: String)	新的颜色值
change	确认选择时触发	(value: String)	确认的颜色值
confirm	点击确认按钮时触发	(value: String)	确认的颜色值
cancel	点击取消按钮时触发	-	-
input / update:value	提交颜色值时	(value)	新颜色值
update:show / open / close / trigger-click	弹层或触发器状态变化	Boolean / 无参数	生命周期

插槽

仅 trigger 插槽，作用域为 value、color、openPicker。

<template>
  <xtf-color-picker v-model="color" show-trigger @confirm="onConfirm">
    <template #trigger="{ color, openPicker }">
      <xtf-button :label="color" @click="openPicker"
    /></template>
  </xtf-color-picker>
</template>
<script>
export default {
  data() {
    return { color: '#3B82F6' }
  },
  methods: {
    onConfirm(value) {
      this.color = value
    }
  }
}
</script>

---

主题说明

• 弹出层使用 xtf-popup 组件的底部弹出样式
• 输入框使用 xtf-input 组件
• 按钮使用 xtf-button 组件
• 色相滑块使用原生 slider 组件
• 颜色面板使用 movable-area / movable-view 实现拖拽

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。