ColorPicker 颜色选择器

约 1921 字大约 6 分钟

2025-10-31

颜色选择器，一个功能强大的颜色选择组件，支持多种颜色格式，预设颜色。

基本使用

通过 show 绑定一个布尔值变量，用于控制组件的弹出与收起。
通过 v-model 或 modelValue 绑定颜色值。

<template>
	<view>
		<un-color-picker-view v-model="color" />
		<view class="color-info">
			<text>当前颜色: {{ color }}</text>
		</view>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const color = ref('#1677FF')
</script>

弹出层模式

默认模式为弹出层，通过 show 属性控制显示和隐藏：

<template>
	<view>
		<un-button type="primary" @click="showPicker = true">打开颜色选择器</un-button>
		<un-color-picker 
			:show="showPicker" 
			@confirm="handlerConfirm" 
			@close="showPicker = false"
		></un-color-picker>
		<view class="color-info">
			<text>选择的颜色: {{ selectedColor }}</text>
		</view>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import type { UnColorPickerConfirmEvent } from '@/uni_modules/uview-unix'

const showPicker = ref(false)
const selectedColor = ref('')

const handlerConfirm = (e: UnColorPickerConfirmEvent) => {
	selectedColor.value = e.value
	showPicker.value = false
}
</script>

设置默认值

通过 defaultValue 属性设置默认颜色值。

<template>
	<view>
		<un-color-picker :show="show" :defaultValue="defaultValue" @close="show = false" @confirm="onConfirm" />
		<un-button @click="show = true">打开</un-button>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import type { UnColorPickerConfirmEvent } from '@/uni_modules/uview-unix'

const show = ref(false)
const defaultValue = ref('#FF4D4F') // 默认红色

const onConfirm = (e: UnColorPickerConfirmEvent) => {
	console.log('确认选择:', e.value)
}
</script>

自定义预设颜色

通过 presets 属性可以自定义预设颜色分组：

<template>
	<view>
		<un-color-picker-view 
			v-model="color" 
			:presets="customPresets"
		/>
		<view class="color-info">
			<text>当前颜色: {{ color }}</text>
		</view>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import type { UnColorPickerOptions } from '@/uni_modules/uview-unix'

const color = ref('#1677FF')
const customPresets = ref<UnColorPickerOptions[]>([
	{
		label: '品牌色',
		colors: [
			'#1677FF', '#00B96B', '#FF9C2A', '#FF4D4F'
		]
	},
	{
		label: '中性色',
		colors: [
			'#000000', '#262626', '#595959', '#8C8C8C', '#BFBFBF', '#FFFFFF'
		]
	}
])
</script>

禁用状态

通过 disabled 属性可以禁用颜色选择器：

<template>
	<view>
		<un-color-picker-view v-model="color" :disabled="true" />
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const color = ref('#1677FF')
</script>

隐藏功能模块

通过 showAlphaSlider、showHueSlider 和 showPresets 属性可以隐藏透明度滑块、色相滑块和预设颜色：

<template>
	<view>
		<un-color-picker-view 
			v-model="color" 
			:showAlphaSlider="false"
			:showHueSlider="false"
			:showPresets="false"
		/>
		<view class="color-info">
			<text>当前颜色: {{ color }}</text>
		</view>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const color = ref('#1677FF')
</script>

自定义底部按钮

通过 footer 插槽可以自定义底部按钮区域：

<template>
	<view>
		<un-color-picker :show="showPicker" @close="showPicker = false">
			<template #footer>
				<view class="custom-footer">
					<un-button text="取消" @click="showPicker = false" />
					<un-button type="primary" text="应用" @click="handleApply" />
				</view>
			</template>
		</un-color-picker>
		<un-button @click="showPicker = true">打开颜色选择器</un-button>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const showPicker = ref(false)

const handleApply = () => {
	// 处理应用逻辑
	showPicker.value = false
}
</script>

<style lang="scss" scoped>
.custom-footer {
	display: flex;
	justify-content: space-between;
	padding: 15px;
}
</style>

API

Props

参数	说明	类型	默认值
value \ modelValue	当前选中的颜色值	string	-
show	是否展示颜色选择器弹窗	boolean	false
title	弹出层标题	string	'请选择颜色'
value	颜色值	string	-
defaultValue	默认颜色值	string	-
showAlphaSlider	是否显示透明度滑块	boolean	true
showHueSlider	是否显示色相滑块	boolean	true
disabled	是否禁用颜色选择器	boolean	false
showPresets	是否显示预设颜色	boolean	true
showConfirm	是否显示确认按钮	boolean	true
closeable	是否显示关闭按钮	boolean	true
closeOnClickOverlay	是否允许点击遮罩关闭选择器	boolean	true
round	弹出层圆角值	string \| number	10
zIndex	弹出层层级	number	1000
confirmShape	确认按钮形状	string	'circle'
confirmText	确认按钮文字	string	'确认'
presets	预设的颜色分组	UnColorPickerOptions[]	-
customStyle	自定义样式	object \| string	-

Events

事件名	说明	类型
change	颜色值变化时触发	Function
formatChange	颜色格式变化时触发	Function
confirm	点击确认按钮时触发	Function
close	关闭选择器时触发	Function
open	打开选择器时触发	Function

Slot

名称	说明
footer	自定义底部按钮区域

数据类型


// 颜色选择器预设选项类型定义，用于定义 `presets` 属性的数据结构。
type UnColorPickerOptions = {
    label: string           // 分组标签
    colors: string[]        // 颜色值数组
}

// 颜色选择器变化事件类型定义，在 `@change` 事件中返回。
type UnColorPickerChangeEvent = {
    color: Array<number | string>  // 颜色值数组（根据格式不同）
    format: string                  // 颜色格式（HEX/RGB/HSL）
    value: string                   // 颜色值字符串
}

// 颜色选择器确认事件类型定义，在 `@confirm` 事件中返回。
type UnColorPickerConfirmEvent = {
    color: Array<number | string>  // 颜色值数组（根据格式不同）
    format: string                  // 颜色格式（HEX/RGB/HSL）
    value: string                   // 颜色值字符串
}

Scss 变量

关于组件 SCSS 变量的用法，请参考组件 SCSS 变量用法。

变量名	默认值	说明
$un-color-picker-disabled-opacity	0.6	禁用状态透明度
$un-color-picker-palette-height	230px	调色板高度
$un-color-picker-palette-radius	8px	调色板圆角
$un-color-picker-palette-lightness-gradient	linear-gradient(to top, rgba(0,0,0,1), rgba(0,0,0,0))	调色板明度渐变
$un-color-picker-handle-width	26px	手柄宽度
$un-color-picker-handle-height	26px	手柄高度
$un-color-picker-handle-border	2px solid #ffffff	手柄边框
$un-color-picker-handle-border-radius	100px	手柄圆角
$un-color-picker-handle-box-shadow	inset 0 0 1px 0 rgba(0, 0, 0, 0.25), 0 0 0 1px rgba(0, 0, 0, 0.06)	手柄阴影
$un-color-picker-slider-wrapper-height	28px	滑块容器高度
$un-color-picker-slider-wrapper-radius	100px	滑块容器圆角
$un-color-picker-slider-wrapper-margin-top	15px	滑块容器上外边距
$un-color-picker-slider-margin	0 2px	滑块边距
$un-color-picker-slider-alpha-background-size	8px 8px	透明度滑块背景大小
$un-color-picker-input-area-margin-top	15px	输入区域上外边距
$un-color-picker-format-selector-margin-right	8px	格式选择器右外边距
$un-color-picker-format-selector-height	34px	格式选择器高度
$un-color-picker-format-selector-padding	0 12px	格式选择器内边距
$un-color-picker-format-selector-bg-color	#f5f7fa	格式选择器背景色
$un-color-picker-format-selector-radius	100px	格式选择器圆角
$un-color-picker-format-current-font-size	13px	格式当前值字体大小
$un-color-picker-format-arrow-width	4px	格式箭头宽度
$un-color-picker-format-arrow-height	6px	格式箭头高度
$un-color-picker-format-arrow-color	#606266	格式箭头颜色
$un-color-picker-format-arrow-margin-left	3px	格式箭头左外边距
$un-color-picker-format-list-bottom	30px	格式列表底部位置
$un-color-picker-format-list-bg-color	#f5f7fa	格式列表背景色
$un-color-picker-format-list-radius	6px 6px 0 0	格式列表圆角
$un-color-picker-format-list-padding-top	5px	格式列表顶部内边距
$un-color-picker-format-item-padding	6px 0	格式项内边距
$un-color-picker-format-item-font-size	14px	格式项字体大小
$un-color-picker-format-item-color	#303133	格式项颜色
$un-color-picker-input-wrapper-height	34px	输入容器高度
$un-color-picker-input-wrapper-padding	0 12px	输入容器内边距
$un-color-picker-input-wrapper-bg-color	#f5f7fa	输入容器背景色
$un-color-picker-input-wrapper-radius	6px	输入容器圆角
$un-color-picker-input-prefix-width	20px	输入前缀宽度
$un-color-picker-input-prefix-color	#909399	输入前缀颜色
$un-color-picker-input-font-size	14px	输入字体大小
$un-color-picker-input-color	#303133	输入颜色
$un-color-picker-color-preview-width	34px	颜色预览宽度
$un-color-picker-color-preview-height	34px	颜色预览高度
$un-color-picker-color-preview-radius	6px	颜色预览圆角
$un-color-picker-color-preview-margin-left	10px	颜色预览左外边距
$un-color-picker-presets-margin-top	5px	预设颜色上外边距
$un-color-picker-preset-label-font-size	13px	预设标签字体大小
$un-color-picker-preset-label-color	#606266	预设标签颜色
$un-color-picker-preset-label-margin-top	8px	预设标签上外边距
$un-color-picker-preset-label-margin-bottom	10px	预设标签下外边距
$un-color-picker-preset-color-width	28px	预设颜色宽度
$un-color-picker-preset-color-height	28px	预设颜色高度
$un-color-picker-preset-color-radius	4px	预设颜色圆角
$un-color-picker-preset-color-margin-right	4px	预设颜色右外边距
$un-color-picker-preset-color-margin-bottom	4px	预设颜色下外边距