ContextQMD
Back to Ant Design

ColorPicker

components/color-picker/index.zh-CN.md

6.3.75.4 KB
Original Source

何时使用 {#when-to-use}

当用户需要自定义颜色选择的时候使用。

代码演示 {#examples}

<!-- prettier-ignore -->

<code src="./demo/base.tsx">基本使用</code> <code src="./demo/size.tsx">触发器尺寸大小</code> <code src="./demo/controlled.tsx">受控模式</code> <code src="./demo/line-gradient.tsx" version="5.20.0">渐变色</code> <code src="./demo/text-render.tsx">渲染触发器文本</code> <code src="./demo/disabled.tsx">禁用</code> <code src="./demo/disabled-alpha.tsx">禁用透明度</code> <code src="./demo/allowClear.tsx">清除颜色</code> <code src="./demo/trigger.tsx">自定义触发器</code> <code src="./demo/trigger-event.tsx">自定义触发事件</code> <code src="./demo/format.tsx">颜色编码</code> <code src="./demo/presets.tsx">预设颜色</code> <code src="./demo/presets-line-gradient.tsx" debug>预设渐变色</code> <code src="./demo/panel-render.tsx">自定义面板</code> <code src="./demo/style-class.tsx" version="6.0.0">自定义语义结构的样式和类</code> <code src="./demo/pure-panel.tsx" debug>Pure Render</code>

API

通用属性参考：通用属性

自 [email protected] 版本开始提供该组件。

<!-- prettier-ignore -->
参数说明类型默认值版本
allowClear允许清除选择的颜色booleanfalse
arrow配置弹出的箭头boolean | { pointAtCenter: boolean }true
children颜色选择器的触发器React.ReactNode-
classNames用于自定义组件内部各语义化结构的 class，支持对象或函数Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string>-
defaultValue颜色默认的值ColorType-
defaultFormat颜色格式默认的值rgb | hex | hsbhex5.9.0
disabled禁用颜色选择器boolean-
disabledAlpha禁用透明度boolean-5.8.0
disabledFormat禁用选择颜色格式boolean-5.22.0
destroyTooltipOnHide关闭后是否销毁弹窗booleanfalse5.7.0
destroyOnHidden关闭后是否销毁弹窗booleanfalse5.25.0
format颜色格式rgb | hex | hsb-
mode选择器模式，用于配置单色与渐变'single' | 'gradient' | ('single' | 'gradient')[]single5.20.0
open是否显示弹出窗口boolean-
presets预设的颜色PresetColorType-
placement弹出窗口的位置同 Tooltips 组件的 placement 参数设计bottomLeft
panelRender自定义渲染面板(panel: React.ReactNode, extra: { components: { Picker: FC; Presets: FC } }) => React.ReactNode-5.7.0
showText显示颜色文本boolean | (color: Color) => React.ReactNode-5.7.0
size设置触发器大小large | medium | smallmedium5.7.0
styles用于自定义组件内部各语义化结构的行内 style，支持对象或函数Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties>-
trigger颜色选择器的触发模式hover | clickclick
value颜色的值ColorType-
onChange颜色变化的回调(value: Color, css: string) => void-
onChangeComplete颜色选择完成的回调，通过 onChangeComplete 对 value 受控时拖拽不会改变展示颜色(value: Color) => void-5.7.0
onFormatChange颜色格式变化的回调(format: 'hex' | 'rgb' | 'hsb') => void-
onOpenChange当 open 被改变时的回调(open: boolean) => void-
onClear清除的回调() => void-5.6.0

ColorType

typescript
type ColorType =
  | string
  | Color
  | {
      color: string;
      percent: number;
    }[];

PresetColorType

typescript
type PresetColorType = {
  label: React.ReactNode;
  defaultOpen?: boolean;
  key?: React.Key;
  colors: ColorType[];
};

Color

<!-- prettier-ignore -->
参数说明类型版本
toCssString转换成 CSS 支持的格式() => string5.20.0
toHex转换成 hex 格式字符，返回格式如：1677ff() => string-
toHexString转换成 hex 格式颜色字符串，返回格式如：#1677ff() => string-
toHsb转换成 hsb 对象() => ({ h: number, s: number, b: number, a: number })-
toHsbString转换成 hsb 格式颜色字符串，返回格式如：hsb(215, 91%, 100%)() => string-
toRgb转换成 rgb 对象() => ({ r: number, g: number, b: number, a: number })-
toRgbString转换成 rgb 格式颜色字符串，返回格式如：rgb(22, 119, 255)() => string-

Semantic DOM

<code src="./demo/_semantic.tsx" simplify="true"></code>

FAQ

关于颜色赋值的问题 {#faq-color-assignment}

颜色选择器的值同时支持字符串色值和选择器生成的 Color 对象，但由于不同格式的颜色字符串互相转换会有精度误差问题，所以受控场景推荐使用选择器生成的 Color 对象来进行赋值操作，这样可以避免精度问题，保证取值是精准的，选择器也可以按照预期工作。