云策 WordPress 开发者社区

块编辑器开发文档

ColorPalette

查看官方原文 ↗
💡 云策文档标注

概述

ColorPalette 是一个 WordPress 组件，允许用户从预定义的颜色列表中选择颜色。它支持自定义颜色、透明度控制，并可通过 Props 进行灵活配置。

关键要点

  • ColorPalette 组件用于颜色选择，基于 React 和 @wordpress/components 库。
  • 支持通过 colors 属性传递颜色数组，每个颜色对象包含 name 和 color 字段。
  • 提供 onChange 回调函数处理颜色选择事件，value 属性用于设置当前选中颜色。
  • Props 包括 clearable、disableCustomColors、enableAlpha、headingLevel、asButtons、loop 等，用于控制组件行为。
  • 在编辑器外使用时，可通过 Popover.Slot 和 SlotFillProvider 确保 Tooltip 定位。

代码示例

import { useState } from 'react';
import { ColorPalette } from '@wordpress/components';

const MyColorPalette = () => {
    const [ color, setColor ] = useState ( '#f00' )
    const colors = [
        { name: 'red', color: '#f00' },
        { name: 'white', color: '#fff' },
        { name: 'blue', color: '#00f' },
    ];

    return (
        <ColorPalette
            colors={ colors }
            value={ color }
            onChange={ ( color ) => setColor( color ) }
        />
    );
}

注意事项

  • onChange 是必需属性，用于处理颜色选择事件。
  • 在非编辑器环境中，建议使用 Popover.Slot 和 SlotFillProvider 来优化 Tooltip 显示。
  • asButtons 属性控制组件是否以按钮形式呈现，影响键盘交互行为。
📄 原文内容

ColorPalette allows the user to pick a color from a list of pre-defined color entries.

Usage

import { useState } from 'react';
import { ColorPalette } from '@wordpress/components';

const MyColorPalette = () => {
    const [ color, setColor ] = useState ( '#f00' )
    const colors = [
        { name: 'red', color: '#f00' },
        { name: 'white', color: '#fff' },
        { name: 'blue', color: '#00f' },
    ];

    return (
        <ColorPalette
            colors={ colors }
            value={ color }
            onChange={ ( color ) => setColor( color ) }
        />
    );
} );

If you’re using this component outside the editor, you can
ensure Tooltip positioning
for the ColorPalette‘s color swatches, by rendering your ColorPalette with a
Popover.Slot further up the element tree and within a
SlotFillProvider overall.

Props

The component accepts the following props.

clearable: boolean

Whether the palette should have a clearing button.

  • Required: No
  • Default: true

colors: PaletteObject[] | ColorObject[]

Array with the colors to be shown. When displaying multiple color palettes to choose from, the format of the array changes from an array of colors objects, to an array of color palettes.

  • Required: No
  • Default: []

disableCustomColors: boolean

Whether to allow the user to pick a custom color on top of the predefined
choices (defined via the colors prop).

  • Required: No
  • Default: false

enableAlpha: boolean

This controls whether the alpha channel will be offered when selecting custom
colors.

  • Required: No
  • Default: false

headingLevel: 1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'

The heading level.

  • Required: No
  • Default: 2

value: string

Currently active value.

  • Required: No

onChange: OnColorChange

Callback called when a color is selected.

  • Required: Yes

asButtons: boolean

Whether the control should present as a set of buttons, each with its own tab stop.

  • Required: No
  • Default: false

loop: boolean

Prevents keyboard interaction from wrapping around. Only used when asButtons is not true.

  • Required: No
  • Default: true