更新记录

1.0.0（2026-07-17） 下载此版本

首发：色域 / 色相 / 透明度选择

• 支持 HEX / RGB / HSL / HSV 格式切换与手动输入
• 预设色、最近使用（本地 Storage）、复制、清空
• 原色 / 新色对比预览；触发器尺寸；自定义触发插槽；ref.open()
• 自包含颜色换算，不依赖业务工程 libs

平台兼容性

uni-app(3.8.0)

kex-color-picker

跨端颜色选择器（uni-app Vue3 / <script setup>）。
支持色域 / 色相 / 透明度、HEX·RGB·HSL·HSV 可编辑、预设色、最近使用、复制、原色对比。

支持：H5 / App（vue 页）/ 微信小程序 / 支付宝小程序 / 其它小程序 / 鸿蒙。

颜色换算内置于插件 color-utils.js，无需业务侧 libs。
弹层依赖 css 渐变与 position: fixed，请在 vue 页面使用（不支持 nvue）。

目录

1. 功能一览
2. 安装
3. 三种用法怎么选
4. 快速上手
5. 完整示例
6. 输出格式 format
7. Props
8. Events
9. 方法 ref
10. 插槽
11. v-model 说明
12. 多端说明
13. 常见问题
14. 注意事项
15. 版本

功能一览

安装

将插件拷贝到业务项目：

你的项目/uni_modules/kex-color-picker/

uni-app easycom 会自动注册，页面里直接写标签，无需 import 组件。

要求：

• uni-app Vue3（manifest.json → vueVersion: "3"）
• App 请使用 vue 页面（不要用 nvue）

演示页（本示例工程）：首页 → kex-color-picker，或路径 /pages/demos/color-picker/index。

三种用法怎么选

三种方式的 format、presets、realtime 等 Props 都生效。

快速上手

1. 最少代码（推荐先从这个开始）

点击色块 → 选色 → 点「确定」→ color 更新。

<template>
  <view>
    <kex-color-picker v-model="color" @change="onChange" />
    <text>当前颜色：{{ color }}</text>
    <view :style="{ width: '120rpx', height: '120rpx', backgroundColor: color }" />
  </view>
</template>

<script setup>
import { ref } from 'vue'

const color = ref('#0D9488')

const onChange = (val) => {
  console.log('选中颜色', val)
}
</script>

2. 输出 RGBA（带透明度）

<template>
  <kex-color-picker
    v-model="color"
    format="rgba"
    :show-alpha="true"
  />
</template>

<script setup>
import { ref } from 'vue'
const color = ref('rgba(13, 148, 136, 0.8)')
</script>

3. 不要透明度（纯色 HEX）

<kex-color-picker
  v-model="color"
  format="hex"
  :show-alpha="false"
/>

4. 拖动时实时更新页面（如主题色预览）

默认要点「确定」才写入。需要边拖边变，打开 realtime：

<template>
  <view class="page" :style="{ backgroundColor: themeColor }">
    <kex-color-picker
      v-model="themeColor"
      format="hex"
      :realtime="true"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue'
const themeColor = ref('#0D9488')
</script>

5. 自定义预设色

<template>
  <kex-color-picker
    v-model="color"
    :presets="brandColors"
    :show-recent="true"
  />
</template>

<script setup>
import { ref } from 'vue'

const color = ref('#E11D48')
const brandColors = [
  '#E11D48',
  '#EA580C',
  '#CA8A04',
  '#16A34A',
  '#0D9488',
  '#0284C7',
  '#1C1917',
  '#FFFFFF'
]
</script>

6. 自定义触发器（插槽）

<template>
  <kex-color-picker v-model="color">
    <template #trigger="{ color: c, disabled }">
      <view class="my-trigger" :class="{ disabled }" :style="{ backgroundColor: c }">
        <text>主题色 {{ c }}</text>
      </view>
    </template>
  </kex-color-picker>
</template>

<script setup>
import { ref } from 'vue'
const color = ref('#CA8A04')
</script>

<style>
.my-trigger {
  padding: 16rpx 24rpx;
  border-radius: 12rpx;
  color: #fff;
}
.my-trigger.disabled {
  opacity: 0.45;
}
</style>

插槽参数：

7. 隐藏触发器，外部按钮打开

<template>
  <view>
    <kex-color-picker
      ref="pickerRef"
      v-model="color"
      :show-trigger="false"
      @confirm="onConfirm"
    />
    <button type="primary" @click="openPicker">选择颜色</button>
    <text>{{ color }}</text>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const color = ref('#1C1917')
const pickerRef = ref(null)

const openPicker = () => {
  pickerRef.value && pickerRef.value.open()
}

const onConfirm = (payload) => {
  // payload: { value, rgba, hsv, hex }
  console.log(payload)
}
</script>

8. 禁用

<kex-color-picker v-model="color" :disabled="true" />

完整示例

表单场景：主题色 + 确认回调 + 清空。

<template>
  <view class="form">
    <view class="form-item">
      <text class="label">主题色</text>
      <kex-color-picker
        v-model="form.theme"
        format="hex"
        size="medium"
        title="选择主题色"
        confirm-text="应用"
        cancel-text="取消"
        :show-alpha="false"
        :presets="presets"
        @change="onThemeChange"
        @confirm="onThemeConfirm"
        @clear="onThemeClear"
      />
    </view>
    <view class="preview" :style="{ backgroundColor: form.theme || '#eee' }" />
  </view>
</template>

<script setup>
import { reactive } from 'vue'

const form = reactive({
  theme: '#0D9488'
})

const presets = ['#E11D48', '#0D9488', '#0284C7', '#1C1917', '#FFFFFF']

const onThemeChange = (val) => {
  console.log('change', val)
}

const onThemeConfirm = ({ value, rgba, hex }) => {
  console.log('confirm', value, rgba, hex)
}

const onThemeClear = () => {
  console.log('已清空')
}
</script>

输出格式 format

format 决定 确认（或 realtime）后写入 v-model 的字符串形态。
面板顶部的 HEX / RGB / HSL / HSV 切换只影响「编辑输入」，不改变最终输出格式。

回填：v-model 也可传入已有颜色字符串（#RGB / #RRGGBB / #RRGGBBAA、rgb/rgba、hsl/hsla、hsv），组件会解析并定位到色域。

Props

Events

confirm 载荷示例：

{
  value: '#0D9488',           // 按 format 格式化后的值（与 v-model 一致）
  rgba: { r: 13, g: 148, b: 136, a: 1 },
  hsv: { h: 174, s: 91, v: 58 },
  hex: '#0D9488'
}

方法 ref

<template>
  <kex-color-picker ref="pickerRef" v-model="color" :show-trigger="false" />
</template>

<script setup>
import { ref } from 'vue'
const pickerRef = ref(null)
const color = ref('#0D9488')

pickerRef.value.open()   // 打开
pickerRef.value.close()  // 关闭
</script>

插槽

footer 示例：

<kex-color-picker v-model="color">
  <template #footer="{ color: c }">
    <view class="tip">将应用为：{{ c }}</view>
  </template>
</kex-color-picker>

v-model 说明

• 写入：点击「确定」后，按 format 写成字符串赋给 v-model（realtime 时拖动也会写）。
• 清空：点「清空」→ v-model = ''。
• 取消：关闭弹层，不改 v-model（除非开了 realtime 已改过）。
• 最近色：仅在「确定」成功后写入本地；Storage key：kex-color-picker-recent。

多端说明

常见问题

1. 点了颜色，页面上的值怎么没变？

默认要点弹层右上角 「确定」 才写入。若需要边拖边变，加 :realtime="true"。

2. H5 复制提示被挡住 / App 出现两个提示？

当前版本已用 弹层内提示，并设置 setClipboardData({ showToast: false })，避免系统 toast 叠一层。请使用 ≥ 1.0.3。

3. 打开弹层后页面还能滚动？

≥ 1.0.2 会在打开时锁滚动。若仍滚动，确认是否在 vue 页（非 nvue），并重新编译。

4. 修改 pages.json 后找不到演示页？

请 重新编译运行（热更新有时不刷新路由）。

5. 想隐藏「最近」或「预设」？

<kex-color-picker
  v-model="color"
  :show-presets="false"
  :show-recent="false"
/>

6. format="hex" 但带了透明度？

开启 showAlpha 且 alpha < 1 时，hex 可能输出 8 位（#RRGGBBAA）。不需要透明度时设 :show-alpha="false"。

注意事项

1. 仅 Vue3；工程需 vueVersion: "3"。
2. App / 小程序请放在 vue 页面，不要放 nvue。
3. 发布到业务项目时，只需拷贝整个 uni_modules/kex-color-picker 目录。
4. 最近颜色存在本地 Storage，清除缓存会丢失。
5. 本示例工程演示页：pages/demos/color-picker/index。

版本

见同目录 changelog.md。当前文档对应 1.0.3+。