颜色选择器 - Semi Design Next

代码演示

如何引入

import { ColorPicker } from '@fibrous/semi-ui-react';

基本用法

放在弹层

自定义 trigger

代码

import { ColorPicker, Button } from '@fibrous/semi-ui-react';
export default function ColorPickerDemo() {
    return (
        <div>
            <ColorPicker
                alpha
                onChange={(value) => {
                    console.log(value);
                }}
                usePopover
            />
            <br />
            <div>自定义 trigger</div>
            <ColorPicker
                alpha
                onChange={(value) => {
                    console.log(value);
                }}
                usePopover
            >
                <Button> Trigger </Button>
            </ColorPicker>
        </div>
    );
}

正常展示

代码

import { ColorPicker } from '@fibrous/semi-ui-react';
export default function ColorPickerDemo() {
    return (
        <ColorPicker
            alpha
            onChange={(value) => {
                console.log(value);
            }}
        />
    );
}

滴管取色器

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

代码

import { ColorPicker } from '@fibrous/semi-ui-react';
export default function ColorPickerDemo() {
    return (
        <ColorPicker
            alpha
            eyeDropper
            onChange={(value) => {
                console.log(value);
            }}
        />
    );
}

默认值

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

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

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

代码

import { ColorPicker } from '@fibrous/semi-ui-react';

export default function ColorPickerDemo() {
    return (
        <div>
            <ColorPicker
                defaultValue={ColorPicker.colorStringToValue('rgb(57,197,187)')}
                onChange={(value) => {
                    console.log(value);
                }}
                alpha
            />
        </div>
    );
}

受控

通过传入 value 来受控使用

代码

import { useState } from 'react';
import { ColorPicker } from '@fibrous/semi-ui-react';
export default function ColorPickerDemo() {
    const [value, setValue] = useState(ColorPicker.colorStringToValue('#39c5bb'));
    return (
        <div>
            <ColorPicker
                value={value}
                onChange={(value) => {
                    setValue(value);
                }}
                alpha
            />
        </div>
    );
}

顶部和底部渲染额外元素

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

TopSlot

Bottom Slot

代码

import { ColorPicker } from '@fibrous/semi-ui-react';
export default function ColorPickerDemo() {
    return (
        <ColorPicker
            topSlot={<div> TopSlot</div>}
            bottomSlot={<div>Bottom Slot</div>}
            alpha
            onChange={(value) => {
                console.log(value);
            }}
        />
    );
}

键盘和焦点

使用 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

属性	说明	类型	默认值
alpha	是否开启透明度选择。	`boolean`	`true`
bottomSlot	底部渲染额外元素。	`React.ReactNode`	-
children	使用 usePopover 时的触发器，默认是一个显示当前颜色的色块按钮；不使用 usePopover 时不渲染。	`React.ReactNode`	-
className	picker 根元素的类名；使用 usePopover 时位于弹层内。	`string`	-
defaultFormat	手动输入时默认使用的颜色格式，可选 `rgba`、`hex`、`hsva`。	`ColorFormat`	`"hex"`
defaultValue	非受控的初始值，是同时包含 hsva、hex、rgba 三种格式的 ColorValue 对象。	`ColorValue`	`Type`
eyeDropper	是否开启滴管拾色器，需要 HTTPS 或 localhost 等安全 context，且浏览器为 Chromium 95 以上，否则无效果。	`boolean`	`true`
height	高度，单位为像素，未设置时为 280。	`number`	-
onChange	用户选中颜色时的回调，参数为 ColorValue，包含 hsva、hex、rgba 三种格式。	`Type`	-
popoverProps	放入 Popover 时传给 Popover 的属性，如 `trigger`、`aria-label`、`aria-labelledby`。弹层默认以点击触发、role 为 `dialog`，名称默认取语言包；`aria-label` 或 `aria-labelledby` 优先。	`PopoverProps`	-
ref	picker 根元素（`div`）的引用；使用 usePopover 时指向弹层内的 picker 元素。	`Type`	-
style	picker 根元素的样式；使用 usePopover 时位于弹层内。	`React.CSSProperties`	-
topSlot	顶部渲染额外元素。	`React.ReactNode`	-
usePopover	是否放入 Popover 渲染，触发器使用 `children`，默认 `false`。	`boolean`	-
value	受控值，形态同 defaultValue。传 `undefined` 视为非受控，从受控变回 `undefined` 时显示回到 defaultValue；传 `null` 是受控的空值，显示 defaultValue 且只报告变化。ColorValue 按不可变值对待，更新时整体替换。	`ColorValue \| null`	-
width	宽度，单位为像素，未设置时为 280。	`number`	-

属性落点

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

ColorValue

value、defaultValue 与 onChange 的参数都是同一种对象：

字段	说明	类型
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`