颜色选择器 ColorPicker - Svelte

代码演示

如何引入

<script lang="ts">
    import { Button, ColorPicker, colorStringToValue } from '@fibrae/semi-ui-svelte';
</script>

基本用法

放在弹层

自定义 trigger

当前颜色：

代码

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

    let hex = $state('');

    const onChange = (value: ColorValue) => {
        hex = value.hex;
    };
</script>

<div>
    <ColorPicker alpha {onChange} usePopover />
    <br />
    <div>自定义 trigger</div>
    <ColorPicker alpha {onChange} usePopover>
        <Button>Trigger</Button>
    </ColorPicker>
    <p>当前颜色：{hex}</p>
</div>

正常展示

当前颜色：

代码

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

    let hex = $state('');

    const onChange = (value: ColorValue) => {
        hex = value.hex;
    };
</script>

<ColorPicker alpha {onChange} />
<p>当前颜色：{hex}</p>

滴管取色器

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

当前颜色：

代码

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

    let hex = $state('');

    const onChange = (value: ColorValue) => {
        hex = value.hex;
    };
</script>

<ColorPicker alpha eyeDropper {onChange} />
<p>当前颜色：{hex}</p>

默认值

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

你传入的 value 也应当是同样包含三种格式的对象。不传 value 时由组件自行管理颜色，单向 value={x} 只作初值。

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

当前颜色：#39c5bb

代码

<script lang="ts">
    import { ColorPicker, colorStringToValue, type ColorValue } from '@fibrae/semi-ui-svelte';

    // a one-way value only seeds the picker, which then manages its own color
    const value = colorStringToValue('rgb(57,197,187)');

    let hex = $state(value.hex);

    const onChange = (next: ColorValue) => {
        hex = next.hex;
    };
</script>

<div>
    <ColorPicker alpha {onChange} {value} />
    <p>当前颜色：{hex}</p>
</div>

受控

使用 bind:value 绑定 value 来受控使用；要完全受控用函数绑定 bind:value={get, set}。色值按不可变对象对待，更新时整体替换（用 $state.raw 声明），不要原地修改 hsva.h 之类的字段，否则文本框不会同步。

代码

<script lang="ts">
    import { ColorPicker, colorStringToValue } from '@fibrae/semi-ui-svelte';

    let value = $state.raw(colorStringToValue('#39c5bb'));
</script>

<div>
    <ColorPicker alpha bind:value />
</div>

顶部和底部渲染额外元素

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

TopSlot

Bottom Slot

当前颜色：

代码

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

    let hex = $state('');

    const onChange = (value: ColorValue) => {
        hex = value.hex;
    };
</script>

<ColorPicker alpha {onChange}>
    {#snippet topSlot()}
        <div>TopSlot</div>
    {/snippet}
    {#snippet bottomSlot()}
        <div>Bottom Slot</div>
    {/snippet}
</ColorPicker>
<p>当前颜色：{hex}</p>

键盘和焦点

使用 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	底部渲染额外元素的 snippet。	`Snippet`	-
children	usePopover 时作为触发器的 snippet，默认是当前颜色的色块；不使用 usePopover 时不渲染。	`Snippet`	-
defaultFormat	手动输入时默认使用的颜色格式，可选 `rgba`、`hex`、`hsva`。	`ColorFormat`	`"hex"`
eyeDropper	是否开启滴管拾色器。	`boolean`	`true`
height	高度，单位为像素，未设置时为 280。	`number`	`280`
onChange	用户选中颜色时的回调，参数为 ColorValue，包含 hsva、hex、rgba 三种格式。	`Type`	-
popoverProps	放入 Popover 时传给 Popover 的属性，如 `trigger`、`aria-label`、`aria-labelledby`。弹层默认以点击触发、role 为 `dialog`，名称默认取语言包；`aria-label` 或 `aria-labelledby` 优先。	`PopoverProps`	-
topSlot	顶部渲染额外元素的 snippet。	`Snippet`	-
usePopover	是否放入 Popover 渲染，触发器使用 `children`，默认 false。	`boolean`	`false`
value	颜色值，可 `bind:value`，是同时包含 hsva、hex、rgba 三种格式的对象。不传时由组件自行管理，初始为 `#39c5bb`；单向 `value={x}` 只作初值，要完全受控用函数绑定 `bind:value={get, set}`；`null` 是受控的空值，显示默认色且只报告变化。ColorValue 按不可变值对待，更新时整体替换。	`ColorValue \| null`	-
width	宽度，单位为像素，未设置时为 280。	`number`	`280`

Methods

方法	说明	类型
getRoot	返回 picker 根元素；usePopover 时位于弹层内，弹层关闭时为 null。	`Type`

属性落点

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

ColorValue

value 与 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`