ColorPicker 颜色选择器
点色块展开面板选颜色。面板里可以在色板上点或拖动、调色相和透明度、点预定义颜色,也可以直接输入十六进制值或 R、G、B 数值。
引入
import { NsColorPicker } from '@ns/ui'
基础用法
用 v-model 绑定颜色字符串。不传时默认是 #409EFF。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPicker } from '@ns/ui'
const color = ref('#409EFF')
</script>
<template>
<NsColorPicker v-model="color" />
</template>
绑定值可以是下面任意一种写法,选完后发出的格式由 colorFormat 决定(见下文):
| 写法 | 例子 |
|---|---|
| 十六进制 | #f80、#409EFF、#409EFF99(最后两位是透明度) |
| rgb / rgba | rgb(64, 158, 255)、rgba(64, 158, 255, 0.6) |
| hsl / hsla | hsl(210, 100%, 63%)、hsla(210, 100%, 63%, 0.6) |
透明度
show-alpha 打开后,面板里多一条透明度滑条和一个 A 输入框(0 到 100),色块底下垫棋盘格表示有透明度;large 尺寸的色块上还会显示当前的不透明度百分比。
没有打开 show-alpha 时,绑定值里的透明度会被忽略,发出的颜色不带透明度。下面三个绑定的是同一个半透明颜色:第一个没开 show-alpha,色块是不透明的;后两个开了,large 的色块上显示 60%。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPicker, NsSpace } from '@ns/ui'
const plain = ref('rgba(64, 158, 255, 0.6)')
const color = ref('rgba(64, 158, 255, 0.6)')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsColorPicker v-model="plain" color-format="rgb" />
<NsColorPicker v-model="color" show-alpha color-format="rgb" />
<NsColorPicker v-model="color" show-alpha color-format="rgb" size="large" />
</NsSpace>
<span>不开 show-alpha:{{ plain }};开了 show-alpha:{{ color }}</span>
</NsSpace>
</template>
颜色格式
color-format 决定选完后发出的字符串是什么格式。
colorFormat | 没开 showAlpha | 开了 showAlpha |
|---|---|---|
hex(默认) | #409eff | 不透明时 #409eff,有透明度时 #409eff99 |
rgb | rgb(64, 158, 255) | rgba(64, 158, 255, 0.6) |
hsl | hsl(210, 100%, 63%) | hsla(210, 100%, 63%, 0.6) |
每一行是一种格式,左边没开 show-alpha,右边开了。选一个颜色(右边再拖一下透明度),值旁边的文字会变成组件发出的值:
<script setup lang="ts">
import { reactive } from 'vue'
import { NsColorPicker, NsSpace } from '@ns/ui'
const formats = ['hex', 'rgb', 'hsl'] as const
const colors = reactive<Record<string, string>>({
hex: '#409eff',
rgb: 'rgb(64, 158, 255)',
hsl: 'hsl(210, 100%, 63%)',
hexAlpha: '#409eff99',
rgbAlpha: 'rgba(64, 158, 255, 0.6)',
hslAlpha: 'hsla(210, 100%, 63%, 0.6)'
})
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace v-for="format in formats" :key="format" wrap>
<span class="row-label">{{ format }}</span>
<NsColorPicker v-model="colors[format]" :color-format="format" />
<code class="value">{{ colors[format] }}</code>
<NsColorPicker v-model="colors[`${format}Alpha`]" :color-format="format" show-alpha />
<code class="value">{{ colors[`${format}Alpha`] }}</code>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.value {
display: inline-block;
min-width: 200px;
}
</style>
预定义颜色
predefine 是面板里那一排色块,点一下直接选中。不传时用内置的 20 个颜色。预定义颜色可以用任意一种写法,带透明度的颜色在开了 show-alpha 时保留透明度。右边是一组半透明的预定义颜色:
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPicker, NsSpace } from '@ns/ui'
const color = ref('#1890FF')
const predefine = ['#1890FF', '#52C41A', '#FAAD14', '#F5222D', '#722ED1', '#000000', '#FFFFFF']
const alphaColor = ref('rgba(24, 144, 255, 0.5)')
const alphaPredefine = [
'rgba(24, 144, 255, 0.5)',
'rgba(82, 196, 26, 0.5)',
'rgba(250, 173, 20, 0.5)',
'hsla(0, 100%, 50%, 0.3)',
'#00000080'
]
</script>
<template>
<NsSpace wrap>
<NsColorPicker v-model="color" :predefine="predefine" />
<NsColorPicker v-model="alphaColor" :predefine="alphaPredefine" show-alpha color-format="rgb" />
</NsSpace>
</template>
尺寸
size 有 large、default、small 三种,只改触发器,颜色面板不随尺寸变化:
| 尺寸 | 触发器高度 | 圆角 | 色块 | 色块圆角 | 箭头 | 左内边距 / 色块到箭头 / 右内边距 |
|---|---|---|---|---|---|---|
| large | 40px | 8px | 28px | 4px | 18px | 12 / 8 / 8px |
| default | 32px | 6px | 22px | 3px | 16px | 8 / 6 / 6px |
| small | 24px | 4px | 16px | 2px | 14px | 6 / 4 / 4px |
高度、圆角和同尺寸的 Input、Button 一致,箭头和 Select 一样大。不写 size 时依次跟随所在的 NsFormItem、NsForm、NsConfigProvider 的 size,都没有时是 default。
每一行是一种尺寸,依次是不透明的颜色、半透明的颜色(开了 show-alpha)、同尺寸的输入框和按钮:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsColorPicker, NsInput, NsSpace } from '@ns/ui'
const color = ref('#409EFF')
const alphaColor = ref('rgba(64, 158, 255, 0.6)')
const text = ref('')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsColorPicker v-model="color" size="large" />
<NsColorPicker v-model="alphaColor" size="large" show-alpha color-format="rgb" />
<NsInput v-model="text" size="large" placeholder="输入框" style="width: 160px" />
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsColorPicker v-model="color" />
<NsColorPicker v-model="alphaColor" show-alpha color-format="rgb" />
<NsInput v-model="text" placeholder="输入框" style="width: 160px" />
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsColorPicker v-model="color" size="small" />
<NsColorPicker v-model="alphaColor" size="small" show-alpha color-format="rgb" />
<NsInput v-model="text" size="small" placeholder="输入框" style="width: 160px" />
<NsButton size="small">按钮</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
禁用
disabled 后触发器换成禁用底色、色块变淡,不能聚焦、不能打开面板。放在禁用的 NsForm 里时也会被禁用。三种尺寸的禁用状态:
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPicker, NsSpace } from '@ns/ui'
const color = ref('#409EFF')
const alphaColor = ref('rgba(64, 158, 255, 0.6)')
</script>
<template>
<NsSpace wrap>
<NsColorPicker v-model="color" size="large" disabled />
<NsColorPicker v-model="color" disabled />
<NsColorPicker v-model="color" size="small" disabled />
<NsColorPicker v-model="alphaColor" size="large" show-alpha disabled />
</NsSpace>
</template>
事件
- 在色板、滑条上拖动时不断触发
activeChange,松开鼠标(或手指)后才更新v-model并触发change。 - 点预定义颜色、改完输入框(按回车或离开输入框)、在色板和滑条上按方向键时,
v-model、change、activeChange一起触发。颜色没变时(例如 R 已经是 255 又输入 999)不触发。 - 只是打开、关闭面板不触发任何事件。
拖动色板时,下面的色块用 activeChange 实时预览:
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPicker } from '@ns/ui'
const color = ref('#409EFF')
// 拖动过程中实时预览
const preview = ref(color.value)
</script>
<template>
<NsColorPicker v-model="color" @active-change="preview = $event" />
<div :style="{ width: '80px', height: '40px', marginTop: '12px', background: preview }"></div>
</template>
在面板里拖一拖、点一下预定义颜色,对比两个事件触发的次数:
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPicker, NsSpace } from '@ns/ui'
const color = ref('#409EFF')
const changeCount = ref(0)
const activeCount = ref(0)
const lastChange = ref('')
const lastActive = ref('')
const onChange = (value: string) => {
changeCount.value += 1
lastChange.value = value
}
const onActiveChange = (value: string) => {
activeCount.value += 1
lastActive.value = value
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsColorPicker v-model="color" @change="onChange" @active-change="onActiveChange" />
<span>change:{{ changeCount }} 次,最后一次 {{ lastChange || '-' }}</span>
<span>activeChange:{{ activeCount }} 次,最后一次 {{ lastActive || '-' }}</span>
</NsSpace>
</template>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则,关闭面板触发 blur 规则;不写 size、disabled 时跟随表单。切换下面的尺寸和禁用看看:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsCheckbox, NsColorPicker, NsForm, NsFormItem, NsSegmented, NsSpace } from '@ns/ui'
const size = ref<'large' | 'default' | 'small'>('default')
const disabled = ref(false)
const model = reactive({ primary: '#409EFF', background: 'rgba(0, 0, 0, 0.05)' })
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsSegmented v-model="size" :options="['large', 'default', 'small']" />
<NsCheckbox v-model="disabled">禁用表单</NsCheckbox>
</NsSpace>
<NsForm :model="model" :size="size" :disabled="disabled" label-width="80px">
<NsFormItem label="主题色" prop="primary">
<NsColorPicker v-model="model.primary" />
</NsFormItem>
<NsFormItem label="背景色" prop="background">
<NsColorPicker v-model="model.background" show-alpha color-format="rgb" />
</NsFormItem>
</NsForm>
</NsSpace>
</template>
键盘操作
| 按键 | 作用 |
|---|---|
Tab | 聚焦到色块 |
Enter / 空格 | 打开或关闭面板 |
Esc | 关闭面板;焦点在面板的输入框里时也可以 |
面板打开后,用 Tab 可以聚焦到色板、色相条、透明度条上:
| 按键 | 色板 | 色相条、透明度条 |
|---|---|---|
← → | 饱和度减、加 0.01 | 减、加 1 |
↓ ↑ | 亮度减、加 0.01 | 减、加 1 |
加 Shift | 每次 0.1 | 每次 10 |
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | '#409EFF' | 绑定值,支持 v-model。写法见“基础用法”,不认识的写法会被忽略,保持原来的颜色 |
| showAlpha | boolean | false | 是否可以调透明度 |
| colorFormat | 'hex' | 'rgb' | 'hsl' | 'hex' | 发出的颜色格式 |
| predefine | string[] | 内置 20 个颜色 | 预定义颜色 |
| size | 'large' | 'default' | 'small' | 'default' | 尺寸 |
| disabled | boolean | false | 是否禁用 |
| validateEvent | boolean | true | 值变化和关闭面板时是否触发所在表单项的校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string) | 选定颜色后触发:拖动后松开鼠标、点预定义颜色、改完输入框 |
| change | (value: string) | 触发时机和 update:modelValue 相同 |
| activeChange | (value: string) | 面板里的颜色变化时触发,拖动过程中会连续触发 |
模板里监听 activeChange 写成 @active-change。
Slots
没有插槽。
方法
没有对外暴露方法。
类型
type ColorPickerSize = 'large' | 'default' | 'small'
type ColorFormat = 'hex' | 'rgb' | 'hsl'
注意事项
- 发出的十六进制颜色是小写的(
#409eff),和传进来的大小写无关。要比较颜色时先统一大小写。 hsl格式的色相、饱和度、亮度都取整,同一个颜色用hsl表示会有 1 以内的误差;需要精确颜色时用hex或rgb。- 绑定值为空串或不是颜色时,组件不会报错,色块保持上一次的颜色(一开始就是无效值时显示红色)。组件没有“未选择”的状态,也没有清空按钮。
- 只有
large尺寸的色块上显示不透明度百分比,是贴着色块底边、高 12px 的一条;default(22px)、small(16px)的色块放不下,只用棋盘格底纹表示有透明度,具体数值在面板的 A 输入框里看。 - 面板渲染在
body下,会跟着选择器一起滚动;下面放不下时自动向上展开,靠近窗口右边时向左收回。要改面板的样式,直接用.ns-color-picker__dropdown,不要把选择器写在组件的父元素下面。
优化点
[ ] 支持颜色历史记录
[ ] 支持自定义面板
[ ] 支持颜色渐变选择
[ ] 支持清空(没有选择颜色的状态)
[ ] 面板里支持切换输入格式(HEX / RGB / HSL)
[ ] 支持自定义触发器