ColorPanel 颜色面板
直接嵌入页面的调色面板,支持色板、透明度、预定义颜色、RGB/HSL 数值输入和屏幕取色。需要弹出的颜色选择器时使用 ColorPicker。
引入
import { NsColorPanel } from '@ns/ui'
import type { ColorPanelInputMode, ColorPanelProps } from '@ns/ui'
示例
基础用法
用 v-model 绑定颜色,面板始终显示在页面中。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const color = ref('#409eff')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsColorPanel v-model="color" />
<code>当前颜色:{{ color }}</code>
</NsSpace>
</template>
透明度
show-alpha 同时显示透明度滑条和 A 输入框。十六进制输出在存在透明度时附带两位透明度值。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const opaque = ref('#409eff')
const translucent = ref('#409eff80')
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>showAlpha = false</span>
<NsColorPanel v-model="opaque" />
<code>{{ opaque }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>showAlpha = true</span>
<NsColorPanel v-model="translucent" show-alpha />
<code>{{ translucent }}</code>
</NsSpace>
</NsSpace>
</template>
输出格式
color-format 决定发出的字符串格式。下面对比 hex、rgb、hsl 的不透明和带透明度输出;面板内切换 RGB/HSL 不改变这里的输出格式。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const cases = reactive([
{ label: 'hex', format: 'hex' as const, alpha: false, value: '#409eff' },
{ label: 'hex + alpha', format: 'hex' as const, alpha: true, value: '#409eff80' },
{ label: 'rgb', format: 'rgb' as const, alpha: false, value: 'rgb(64, 158, 255)' },
{ label: 'rgb + alpha', format: 'rgb' as const, alpha: true, value: 'rgba(64, 158, 255, 0.5)' },
{ label: 'hsl', format: 'hsl' as const, alpha: false, value: 'hsl(210, 100%, 63%)' },
{
label: 'hsl + alpha',
format: 'hsl' as const,
alpha: true,
value: 'hsla(210, 100%, 63%, 0.5)'
}
])
</script>
<template>
<NsSpace wrap align="start" :size="24">
<NsSpace v-for="item in cases" :key="item.label" direction="vertical" align="start">
<span>{{ item.label }}</span>
<NsColorPanel v-model="item.value" :color-format="item.format" :show-alpha="item.alpha" />
<code style="max-width: 280px; overflow-wrap: anywhere">{{ item.value }}</code>
</NsSpace>
</NsSpace>
</template>
数值输入模式
input-mode 只决定数值框显示 RGB 还是 HSL。十六进制输入框一直显示,输入模式和 color-format 可以分别设置。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const rgbInputs = ref('hsl(120, 100%, 50%)')
const hslInputs = ref('rgb(0, 255, 0)')
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>inputMode = rgb,输出 hsl</span>
<NsColorPanel v-model="rgbInputs" input-mode="rgb" color-format="hsl" />
<code>{{ rgbInputs }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>inputMode = hsl,输出 rgb</span>
<NsColorPanel v-model="hslInputs" input-mode="hsl" color-format="rgb" />
<code>{{ hslInputs }}</code>
</NsSpace>
</NsSpace>
</template>
保存输入模式
通过 v-model:input-mode 把模式保存在父组件中,面板重新挂载后继续使用该模式。没有传 inputMode 时,colorFormat 为 hsl 则显示 HSL,其余显示 RGB。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace, NsSwitch } from '@ns/ui'
import type { ColorPanelInputMode } from '@ns/ui'
const color = ref('#67c23a')
const mode = ref<ColorPanelInputMode>('rgb')
const visible = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace align="center">
<NsSwitch v-model="visible" aria-label="显示颜色面板" />
<span>显示面板;当前模式:{{ mode }}</span>
</NsSpace>
<NsColorPanel v-if="visible" v-model="color" v-model:input-mode="mode" />
<code>{{ color }}</code>
</NsSpace>
</template>
预定义颜色
传入自定义颜色数组;传 [] 时隐藏整行预定义颜色。预定义颜色使用原生按钮,可以用 Tab 聚焦,再按回车或空格选中。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const brand = ref('#126b52')
const withoutPredefine = ref('#67c23a')
const palette = ['#126b52', '#409eff', '#e6a23c', '#f56c6c', '#909399', '#ffffff']
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>自定义品牌色</span>
<NsColorPanel v-model="brand" :predefine="palette" />
<code>{{ brand }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>predefine = []</span>
<NsColorPanel v-model="withoutPredefine" :predefine="[]" />
<code>{{ withoutPredefine }}</code>
</NsSpace>
</NsSpace>
</template>
屏幕取色
浏览器支持屏幕取色时才显示吸管按钮。取到的颜色保留面板原来的透明度,取消取色时颜色不变。使用 :eye-dropper="false" 关闭吸管。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const enabled = ref('#409eff80')
const disabled = ref('#409eff80')
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>eyeDropper = true</span>
<NsColorPanel v-model="enabled" show-alpha />
<code>{{ enabled }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>eyeDropper = false</span>
<NsColorPanel v-model="disabled" show-alpha :eye-dropper="false" />
<code>{{ disabled }}</code>
</NsSpace>
</NsSpace>
</template>
外框
bordered 默认开启;关闭后保留面板内部布局,适合放入已有容器。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const bordered = ref('#409eff')
const unbordered = ref('#67c23a')
</script>
<template>
<NsSpace wrap align="start">
<NsSpace direction="vertical" align="start">
<span>bordered = true</span>
<NsColorPanel v-model="bordered" />
<code>{{ bordered }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>bordered = false</span>
<NsColorPanel v-model="unbordered" :bordered="false" />
<code>{{ unbordered }}</code>
</NsSpace>
</NsSpace>
</template>
禁用
禁用后,色板、滑条、预定义颜色和输入框均不可操作,也不会发出调色事件。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsColorPanel, NsSpace } from '@ns/ui'
const color = ref('#409eff80')
const disabled = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsCheckbox v-model="disabled">禁用面板</NsCheckbox>
<NsColorPanel v-model="color" show-alpha :disabled="disabled" />
<code>{{ color }}</code>
</NsSpace>
</template>
自定义宽度
默认宽度为 280px,通过 style 调整宽度,色板、滑条和数值框随之伸缩。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const narrow = ref('#409eff80')
const wide = ref('#67c23a80')
</script>
<template>
<NsSpace wrap align="start" :size="24">
<NsSpace direction="vertical" align="start">
<span>240px</span>
<NsColorPanel v-model="narrow" show-alpha style="width: 240px" />
<code>{{ narrow }}</code>
</NsSpace>
<NsSpace direction="vertical" align="start">
<span>360px</span>
<NsColorPanel v-model="wide" show-alpha style="width: 360px" />
<code>{{ wide }}</code>
</NsSpace>
</NsSpace>
</template>
在表单中使用
面板跟随表单的禁用状态。默认在绑定值变化和焦点离开整个面板时触发校验;面板内部移动焦点不触发失焦校验。:validate-event="false" 关闭自动校验,手动调用表单 validate() 仍会检查该字段。
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsColorPanel, NsForm, NsFormItem, NsSpace } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const form = ref<InstanceType<typeof NsForm>>()
const model = reactive({ automatic: '', manual: '' })
const rules: Record<string, FormRule[]> = {
automatic: [{ required: true, message: '请选择主题色', trigger: ['blur', 'change'] }],
manual: [{ required: true, message: '请选择辅助色', trigger: ['blur', 'change'] }]
}
const result = ref('尚未校验')
const validate = async () => {
const checked = await form.value?.validate()
result.value = checked?.valid ? '校验通过' : '请完成必填颜色'
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsForm ref="form" :model="model" :rules="rules" label-position="top">
<NsSpace wrap align="start" :size="24">
<NsFormItem label="主题色:自动校验" prop="automatic">
<NsColorPanel v-model="model.automatic" />
</NsFormItem>
<NsFormItem label="辅助色:仅手动校验" prop="manual">
<NsColorPanel v-model="model.manual" :validate-event="false" />
</NsFormItem>
</NsSpace>
</NsForm>
<NsSpace align="center">
<NsButton type="primary" icon="check" @click="validate">校验表单</NsButton>
<span>{{ result }}</span>
</NsSpace>
</NsSpace>
</template>
事件
拖动时 active-change 连续触发,松开后才发出 update:modelValue 和 change;点预定义颜色、键盘调色或完成输入也会提交颜色。下面在页面上显示预览值,提交时才显示消息。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsMessage, NsSpace } from '@ns/ui'
import type { ColorPanelInputMode } from '@ns/ui'
const color = ref('#409eff')
const mode = ref<ColorPanelInputMode>('rgb')
const active = ref('尚未调色')
const committed = ref('尚未提交')
const updates = ref(0)
const handleUpdate = () => {
updates.value++
}
const handleChange = (value: string) => {
committed.value = value
NsMessage.success(`选定颜色:${value}`)
}
const handleActive = (value: string) => {
active.value = value
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsColorPanel
v-model="color"
v-model:input-mode="mode"
@update:model-value="handleUpdate"
@change="handleChange"
@active-change="handleActive"
/>
<span>update:modelValue:{{ updates }} 次;绑定值:{{ color }}</span>
<span>activeChange:{{ active }}</span>
<span>change:{{ committed }}</span>
<span>update:inputMode:{{ mode }}</span>
</NsSpace>
</template>
空值与无效值
undefined、null、空字符串和无法解析的颜色都只让面板内部从 #409EFF 起步,不自动写回。下例的绑定值在选色前保持原值。
<script setup lang="ts">
import { reactive } from 'vue'
import { NsColorPanel, NsSpace } from '@ns/ui'
const colors = reactive<Record<string, string | null | undefined>>({
undefined: undefined,
null: null,
空字符串: '',
无效颜色: 'not-a-color'
})
const display = (value: string | null | undefined) =>
value === undefined ? 'undefined' : JSON.stringify(value)
</script>
<template>
<NsSpace wrap align="start" :size="24">
<NsSpace v-for="(value, name) in colors" :key="name" direction="vertical" align="start">
<span>{{ name }}</span>
<NsColorPanel v-model="colors[name]" />
<code>绑定值:{{ display(value) }}</code>
</NsSpace>
</NsSpace>
</template>
和 ColorPicker 搭配
面板、弹出的颜色选择器和预览共享同一个绑定值,适合主题设置。
<script setup lang="ts">
import { ref } from 'vue'
import { NsColorPanel, NsColorPicker, NsSpace } from '@ns/ui'
const color = ref('#126b52')
</script>
<template>
<NsSpace wrap align="start" :size="24">
<NsColorPanel v-model="color" />
<NsSpace direction="vertical" align="start">
<NsSpace align="center">
<span>主题颜色</span>
<NsColorPicker v-model="color" />
<code>{{ color }}</code>
</NsSpace>
<article class="color-preview" :style="{ borderTopColor: color }">
<h3>季度项目报告</h3>
<p>研发进度与交付安排</p>
<div class="color-preview__sample" :style="{ backgroundColor: color }"></div>
<span>主题色预览</span>
</article>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.color-preview {
width: 280px;
max-width: 100%;
padding: var(--ns-spacing-4);
border: var(--ns-border-width) var(--ns-border-style) var(--ns-border-color);
border-top-width: 4px;
border-radius: var(--ns-border-radius);
color: var(--ns-text-color);
background: var(--ns-bg-color);
box-sizing: border-box;
}
.color-preview h3 {
margin: 0 0 var(--ns-spacing-2);
font-size: var(--ns-font-size-lg);
}
.color-preview p {
margin: 0 0 var(--ns-spacing-4);
color: var(--ns-text-color-secondary);
}
.color-preview__sample {
height: 12px;
margin-bottom: var(--ns-spacing-2);
border-radius: var(--ns-border-radius-sm);
}
</style>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | null | undefined | undefined | 绑定颜色;空值或无效值时内部从 #409EFF 起步,不自动写回 |
| disabled | boolean | false | 是否禁用,也跟随所在表单 |
| showAlpha | boolean | false | 是否启用透明度滑条、A 输入框及带透明度的颜色输出 |
| colorFormat | 'hex' | 'rgb' | 'hsl' | 'hex' | 发出的颜色字符串格式 |
| predefine | string[] | 内置 20 个颜色 | 预定义颜色;传 [] 隐藏该区域 |
| eyeDropper | boolean | true | 是否启用屏幕取色;浏览器不支持时不显示按钮 |
| inputMode | 'rgb' | 'hsl' | 跟随 colorFormat | 数值输入模式,支持 v-model:input-mode;未传时 colorFormat='hsl' 使用 HSL,其余使用 RGB |
| bordered | boolean | true | 是否显示外框、圆角和背景 |
| validateEvent | boolean | true | 绑定值变化及焦点离开面板时是否触发表单校验 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string) | 选定颜色时触发;拖动在松开后提交 |
| change | (value: string) | 与 update:modelValue 同时触发 |
| activeChange | (value: string) | 调色时触发,拖动过程中连续触发,提交时也触发 |
| update:inputMode | (mode: ColorPanelInputMode) | 点击 RGB/HSL 切换按钮时触发 |
提交颜色时,事件依次为 update:modelValue、change、activeChange。模板中分别使用 @update:model-value、@change、@active-change 和 @update:input-mode。
Slots
没有插槽。
方法
没有对外暴露方法。
类型
import type {
ColorPanelEmits,
ColorPanelInputMode,
ColorPanelProps,
ColorPickerFormat
} from '@ns/ui'
ColorPanelInputMode 为 'rgb' | 'hsl'。ColorPanelProps.colorFormat 使用 ColorPickerFormat。ColorPanelProps 和 ColorPanelEmits 分别是属性与事件的公开类型。
注意事项
- 支持
#rgb、#rgba、#rrggbb、#rrggbbaa、rgb()、rgba()、hsl()、hsla()。不支持颜色名、CSS 变量、HSB 和 OKLCH。 - 初始值或外部新值为空、无法解析时,内部从
#409EFF起步,不报错、不自动写回,也不因挂载或同步外部值发出颜色事件。 - 十六进制输出为小写。HSL 输出的色相、饱和度和亮度取整,转换时可能存在取整误差。
inputMode只影响数值输入框;十六进制框一直显示,发出的格式由colorFormat决定。RGB/HSL 切换本身不提交颜色。- 输入超出通道范围时会被收回;空值或无效数字恢复原值。H 为 360 时按 0 处理。灰色和黑色没有有效色相,调为这些颜色时色相滑块保留当前色相。
- 吸管只在浏览器提供屏幕取色能力时显示。取色保留原透明度;取消取色不改变颜色。取色期间禁用、外部颜色变化或面板卸载后,不会写回旧的异步结果。
- 取色期间再次点击吸管不起作用;按钮变灰,但仍可聚焦。
- 方向键可调整色板、色相和透明度;按住 Shift 使用更大步长。预定义颜色、吸管和输入格式按钮均可用键盘访问。
- 面板默认宽度为 280px,可用
style调整,最大宽度不会超过父容器。需要弹出的触发器和焦点循环时使用 ColorPicker。