外观
ColorPicker 颜色选择器
约 1108 字大约 4 分钟
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 // 颜色值字符串
}