颜色选择器 - Semi Design Next

代码演示

如何引入

<script setup lang="ts">
    import { ColorPicker } from '@fibrous/semi-ui-vue';
</script>

基本用法

放在弹层

自定义 trigger

代码

<script setup lang="ts">
    import { Button, ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <div>
        <ColorPicker alpha usePopover @change="onChange" />
        <br />
        <div>自定义 trigger</div>
        <ColorPicker alpha usePopover @change="onChange">
            <Button> Trigger </Button>
        </ColorPicker>
    </div>
</template>

正常展示

代码

<script setup lang="ts">
    import { ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <ColorPicker alpha @change="onChange" />
</template>

滴管取色器

滴管功能默认开启，支持从浏览器内或外部软件屏幕取色。传入 :eyeDropper="false" 可关闭。

代码

<script setup lang="ts">
    import { ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <ColorPicker alpha eyeDropper @change="onChange" />
</template>

默认值

在进行各种颜色表示格式之间相互转换时，部分格式之间存在理论误差，因此 change 与 update:modelValue 事件返回给你的值是同时包含了 hsva hex rgba 三种格式的色值的对象。

你传入的 defaultValue(非受控) 和 modelValue(受控) 也应当是同样包含三种格式的对象。

我们在组件上提供了静态工具函数 colorStringToValue，用于将常见颜色字符串转换为该对象，支持 rgb(57,197,187) #39c5bb（也支持 #3cb 这样的简写）hsv(176,71,77) 等字符串直接传入，无法解析的字符串会抛出错误。

代码

<script setup lang="ts">
    import { ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    const defaultValue = ColorPicker.colorStringToValue('rgb(57,197,187)');

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <div>
        <ColorPicker alpha :defaultValue="defaultValue" @change="onChange" />
    </div>
</template>

受控

使用 v-model 绑定 modelValue 来受控使用。色值按不可变对象对待，更新时整体替换，不要原地修改 hsva.h 之类的字段，否则文本框不会同步。

代码

<script setup lang="ts">
    import { shallowRef } from 'vue';
    import { ColorPicker } from '@fibrous/semi-ui-vue';

    const value = shallowRef(ColorPicker.colorStringToValue('#39c5bb'));
</script>

<template>
    <div>
        <ColorPicker v-model="value" alpha />
    </div>
</template>

顶部和底部渲染额外元素

使用 #topSlot 和 #bottomSlot 插槽在顶部和底部渲染额外元素

TopSlot

Bottom Slot

代码

<script setup lang="ts">
    import { ColorPicker, type ColorValue } from '@fibrous/semi-ui-vue';

    function onChange(value: ColorValue) {
        console.log(value);
    }
</script>

<template>
    <ColorPicker alpha @change="onChange">
        <template #topSlot>
            <div>TopSlot</div>
        </template>
        <template #bottomSlot>
            <div>Bottom Slot</div>
        </template>
    </ColorPicker>
</template>

键盘和焦点

使用 usePopover 时，默认触发器是一个带名称的按钮，Enter、空格打开弹层；弹层是 dialog，默认以点击触发，Esc 关闭。弹层的名称默认取内置文案，传入 popoverProps 的 aria-label 或 aria-labelledby（Vue 中为 ariaLabel、ariaLabelledby）优先。
选色区、色相条、透明度条的手柄都可以用键盘操作。选色区有饱和度与明度两个滑块，色相条、透明度条各有一个。
方向键步进 1，PageUp、PageDown 步进 10，Home、End 跳到两端。在选色区内无论聚焦哪个滑块，左右键都改饱和度，上下键与 PageUp、PageDown 都改明度，Home、End 作用于聚焦的那一个。同时按下 Alt、Ctrl、Meta 时不处理，留给浏览器和辅助技术。
聚焦手柄时显示主题焦点环；颜色输入框、透明度输入框和格式选择器都有可访问名称。

API 参考

ColorPicker

Props

属性	说明	类型	默认值
modelValue	受控值，使用 v-model 绑定；形态同 defaultValue。传 undefined 视为非受控，从受控变回 undefined 时显示回到 defaultValue。ColorValue 按不可变值对待，更新时整体替换。	`ColorValue`	`undefined`
defaultValue	非受控的初始值，是同时包含 hsva、hex、rgba 三种格式的对象，默认对应 #39c5bb。	`ColorValue`	`semiDefault("ColorPicker", "defaultValue", DEFAULT_COLOR)`
alpha	是否开启透明度选择。	`boolean`	`semiDefault("ColorPicker", "alpha", true)`
eyeDropper	是否开启滴管拾色器，需要安全 context 与 Chromium 95 以上。	`boolean`	`semiDefault("ColorPicker", "eyeDropper", true)`
defaultFormat	手动输入时默认使用的颜色格式，可选 rgba、hex、hsva。	`ColorFormat`	`semiDefault("ColorPicker", "defaultFormat", "hex")`
width	宽度，单位为像素。	`number`	`semiDefault("ColorPicker", "width", 280)`
height	高度，单位为像素。	`number`	`semiDefault("ColorPicker", "height", 280)`
usePopover	是否放入 Popover 渲染，触发器使用默认插槽。	`boolean`	`semiDefault("ColorPicker", "usePopover", false)`
popoverProps	放入 Popover 时传给 Popover 的属性与监听器（onVisibleChange 等）；class、style 替代 className、style。弹层默认以 click 触发、role 为 dialog，默认名称取语言包，ariaLabel、ariaLabelledby 优先。	`ColorPickerPopoverProps`	`semiGlobalDefault("ColorPicker", "popoverProps")`

Events

事件	说明	回调参数
update:modelValue	用户选中颜色时触发，载荷为 ColorValue，供 v-model 回写。	`[value: ColorValue]`
change	用户选中颜色时触发，载荷为 ColorValue；picker 内部输入框冒泡的原生 change 不会到达该事件。	`[value: ColorValue]`

Slots

插槽	说明	作用域参数
default	usePopover 时的触发器，默认是一个色块按钮；不使用 Popover 时不渲染。	`any`
topSlot	在顶部渲染额外元素。	`any`
bottomSlot	在底部渲染额外元素。	`any`

Exposes

名称	说明	类型
root	picker 根元素；usePopover 时位于弹层内，弹层关闭时为 null。	`HTMLElement \| null`

属性落点

class、style 与其他未声明的属性落在 picker 根元素上；使用 usePopover 时落在弹层内的 picker 元素上，不落在触发器与对话框上。使用方传入 aria-label 或 aria-labelledby 且未传 role 时，picker 根元素加 role="group"。

ColorValue

modelValue、defaultValue 与事件载荷都是同一种对象：

字段	说明	类型
hsva	HSV 色值与透明度，h 为 0-360，s、v 为 0-100，a 为 0-1	`{ h: number; s: number; v: number; a: number }`
rgba	RGB 色值与透明度，r、g、b 为 0-255，a 为 0-1	`{ r: number; g: number; b: number; a: number }`
hex	十六进制色值，`#rrggbb` 或带透明度的 `#rrggbbaa`	`string`