ColorPicker 颜色选择器

选择颜色，为内容和品牌增添个性。

选择颜色

点击色块、颜色文字或整行空白区域即可打开选择浮层。

当前颜色：#20834a

basic.tsx

import { ColorPicker, Space, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function ColorPickerBasic() {
  const [color, setColor] = useState('#20834a');
  return (
    <Space direction="vertical" align="start">
      <ColorPicker value={color} onChange={setColor} showText aria-label="品牌颜色" />
      <Text tone="muted">当前颜色：{color}</Text>
    </Space>
  );
}

颜色格式与透明度

HEX

RGB · 半透明

HSL · 不透明

formats.tsx

import { ColorPicker, Flex, Text } from '@ifhover/leaf-ui';

export function ColorPickerFormats() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>HEX</Text>
        <ColorPicker defaultValue="#1677ff" showText />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>RGB · 半透明</Text>
        <ColorPicker defaultValue="rgba(118, 84, 198, 0.6)" defaultFormat="rgb" showText />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>HSL · 不透明</Text>
        <ColorPicker defaultValue="hsl(35, 91%, 55%)" defaultFormat="hsl" disableAlpha showText />
      </Flex>
    </Flex>
  );
}

预设与状态

自定义预设 · 可清除

禁用

presets.tsx

import type { ColorPreset } from '@ifhover/leaf-ui';

import { ColorPicker, Flex, Text } from '@ifhover/leaf-ui';

const presets: readonly ColorPreset[] = [
  { label: '品牌颜色', colors: ['#20834a', '#1677ff', '#7654c6', '#f49b23'] },
  { label: '中性色', colors: ['#203329', '#6c7c71', '#dce5de', '#ffffff'] },
];

export function ColorPickerPresets() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>自定义预设 · 可清除</Text>
        <ColorPicker presets={presets} allowClear showText />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>禁用</Text>
        <ColorPicker disabled defaultValue="#1677ff" showText />
      </Flex>
    </Flex>
  );
}

渐变色

纯色

渐变：选择、添加或移除色标

capabilities.tsx

import { ColorPicker, Flex, Space, Text } from '@ifhover/leaf-ui';

export function Capabilities() {
  return (
    <Space>
      <Flex direction="column" gap="sm" align="center">
        <Text>{'纯色'}</Text>
        <ColorPicker showText />
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        <Text>
          {'渐变：选择、添加或移除色标'}
        </Text>
        <ColorPicker
          mode="gradient"
          showText
          defaultValue="linear-gradient(90deg, #20834a 0%, #83cf9e 100%)"
        />
      </Flex>
    </Space>
  );
}

ColorPicker API

属性	类型	默认值	说明
`popupPlacement`	`'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'`	—	浮层相对触发控件的位置。
`popupClassName`	`string`	—	浮层的自定义类名。
`popupStyle`	`CSSProperties`	—	浮层的自定义样式。
`popupRender`	`(content: ReactNode) => ReactNode`	—	包装或补充面板内容，保留传入的内容以维持交互。
`getPopupContainer`	`() => Element \| DocumentFragment`	—	返回浮层的挂载容器，也可返回 ShadowRoot。
`value`	`string`	`'#20834a'`	受控颜色 / 初始颜色，可使用 HEX、RGB、HSL 或 CSS 命名颜色
`defaultValue`	`string`	`'#20834a'`	受控颜色 / 初始颜色，可使用 HEX、RGB、HSL 或 CSS 命名颜色
`onChange`	`(color: string) => void`	—	实时变化 / 一次调色操作结束；清除时返回空字符串
`onChangeComplete`	`(color: string) => void`	—	实时变化 / 一次调色操作结束；清除时返回空字符串
`format`	`'hex' \| 'rgb' \| 'hsl'`	`'hex'`	颜色文字格式；渐变模式应用于每个色标。
`defaultFormat`	`'hex' \| 'rgb' \| 'hsl'`	`'hex'`	初始颜色文字格式。
`onFormatChange`	`(format: 'hex' \| 'rgb' \| 'hsl') => void`	—	颜色文字格式变化时调用。
`disableAlpha`	`boolean`	`false`	隐藏透明度并输出不透明颜色
`showText`	`boolean \| ((color: string) => ReactNode)`	`false`	展示颜色文字或自定义文字
`allowClear`	`boolean`	`false`	允许清除颜色
`presets`	`readonly ColorPreset[]`	内置颜色	预设的颜色分组。
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	触发控件尺寸
`status`	`'error' \| 'warning'`	—	校验反馈
`required`	`boolean`	`false`	要求整体值非空，复合控件只校验一次。
`readOnly`	`boolean`	—	锁定业务值，禁止输入、选择、清除和删除。
`popupWidth`	`number \| string`	`280`	浮层宽度
`onOpenChange`	`(open: boolean) => void`	—	展开状态变化
`gradient`	`boolean`	`false`	启用渐变颜色选择。
`mode`	`'solid' \| 'gradient'`	—	选择展示或编辑模式。
`open`	`boolean`	—	控制面板是否展开。
`defaultOpen`	`boolean`	—	面板初始展开状态。
`disabled`	`boolean`	`false`	禁用交互。
`name`	`string`	—	原生 FormData 中的字段名。
`form`	`string`	—	关联的原生表单 ID。

ColorPreset

属性	类型	默认值	说明
`label`	`ReactNode`	—	必需。分组标题
`colors`	`readonly string[]`	—	必需。该组的颜色值

类型

可导入以下类型定义属性、组装数据或处理回调。

import type { ColorPickerProps, ColorPreset } from '@ifhover/leaf-ui';

使用说明

颜色值以字符串传递，开启透明度时 HEX 可能为 8 位。格式切换不会修改已提交值，下一次调色按所选格式输出。拖动时触发 onChange，释放指针、键盘调整、输入提交或选择预设时触发 onChangeComplete。

调色区域支持方向键，按住 Shift 加大调整幅度；左右调整饱和度，上下调整亮度。颜色输入通过 Enter 或移走焦点提交，无效输入保留错误提示。支持 FormData、必填校验与非受控表单 reset；受控字段需同步重置自己的值。

ColorGradient

属性	类型	默认值	说明
`angle`	`number`	—	必需。渐变角度，单位为度。
`stops`	`readonly ColorGradientStop[]`	—	必需。渐变中的色标。

ColorGradientStop

属性	类型	默认值	说明
`key`	`string`	—	稳定且唯一的标识。
`color`	`string`	—	必需。颜色或语义色。
`offset`	`number`	—	必需。偏移量；色标为 0–100 的百分比。

#ColorPicker 颜色选择器

#选择颜色

#颜色格式与透明度

#预设与状态

#渐变色

#ColorPicker API

#ColorPreset

#类型

#使用说明

#ColorGradient

#ColorGradientStop