云策 WordPress 开发者社区

块编辑器开发文档

GradientPicker

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

概述

GradientPicker 是一个 React 组件，用于渲染颜色渐变选择器，支持定义多步渐变，包括线性或径向类型。它提供丰富的属性配置，适用于 WordPress 开发中的自定义界面。

关键要点

  • GradientPicker 是 @wordpress/components 包中的 React 组件，用于选择渐变颜色。
  • 支持线性或径向渐变类型，可通过 gradients 属性预定义渐变选项。
  • 组件包含多个可配置属性，如 onChange、value、clearable、disableCustomGradients 等，以控制行为和样式。
  • 可用于 WordPress 编辑器或自定义界面，通过 props 调整如侧边栏渲染、按钮形式、可访问性标签等。

代码示例

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

const MyGradientPicker = () => {
  const [ gradient, setGradient ] = useState( null );

  return (
    <GradientPicker
      value={ gradient }
      onChange={ ( currentGradient ) => setGradient( currentGradient ) }
      gradients={ [
        {
          name: 'JShine',
          gradient:
            'linear-gradient(135deg,#12c2e9 0%,#c471ed 50%,#f64f59 100%)',
          slug: 'jshine',
        },
        {
          name: 'Moonlit Asteroid',
          gradient:
            'linear-gradient(135deg,#0F2027 0%, #203A43 0%, #2c5364 100%)',
          slug: 'moonlit-asteroid',
        },
        {
          name: 'Rastafarie',
          gradient:
            'linear-gradient(135deg,#1E9600 0%, #FFF200 0%, #FF0000 100%)',
          slug: 'rastafari',
        },
      ] }
    />
  );
};

注意事项

  • onChange 属性是必需的，用于处理渐变值变化；value 属性可选，默认提供示例渐变字符串。
  • 当 gradients 属性包含多个起源时，headingLevel 属性用于设置标题级别。
  • asButtons 属性控制是否以按钮形式呈现，影响键盘交互行为（如 loop 属性）。
  • 确保正确导入 @wordpress/components 包，并遵循 React 状态管理最佳实践。
📄 原文内容

See the WordPress Storybook for more detailed, interactive documentation.

GradientPicker is a React component that renders a color gradient picker to
define a multi step gradient. There’s either a linear or a radial type
available.

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

const MyGradientPicker = () => {
  const [ gradient, setGradient ] = useState( null );

  return (
    <GradientPicker
      value={ gradient }
      onChange={ ( currentGradient ) => setGradient( currentGradient ) }
      gradients={ [
        {
          name: 'JShine',
          gradient:
            'linear-gradient(135deg,#12c2e9 0%,#c471ed 50%,#f64f59 100%)',
          slug: 'jshine',
        },
        {
          name: 'Moonlit Asteroid',
          gradient:
            'linear-gradient(135deg,#0F2027 0%, #203A43 0%, #2c5364 100%)',
          slug: 'moonlit-asteroid',
        },
        {
          name: 'Rastafarie',
          gradient:
            'linear-gradient(135deg,#1E9600 0%, #FFF200 0%, #FF0000 100%)',
          slug: 'rastafari',
        },
      ] }
    />
  );
};

Props

__experimentalIsRenderedInSidebar

  • Type: boolean
  • Required: No
  • Default: false

Whether this is rendered in the sidebar.

asButtons

  • Type: boolean
  • Required: No
  • Default: false

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

aria-label

  • Type: string
  • Required: No

A label to identify the purpose of the control.

aria-labelledby

  • Type: string
  • Required: No

An ID of an element to provide a label for the control.

className

  • Type: string
  • Required: No

The class name added to the wrapper.

clearable

  • Type: boolean
  • Required: No
  • Default: true

Whether the palette should have a clearing button or not.

disableCustomGradients

  • Type: boolean
  • Required: No
  • Default: false

If true, the gradient picker will not be displayed and only defined
gradients from gradients will be shown.

enableAlpha

  • Type: boolean
  • Required: No
  • Default: true

Whether to enable alpha transparency options in the picker.

gradients

  • Type: GradientsProp
  • Required: No
  • Default: []

An array of objects as predefined gradients displayed above the gradient
selector. Alternatively, if there are multiple sets (or ‘origins’) of
gradients, you can pass an array of objects each with a name and a
gradients array which will in turn contain the predefined gradient objects.

headingLevel

  • Type: 1 | 2 | 3 | 4 | 5 | 6 | "1" | "2" | "3" | "4" | ...
  • Required: No
  • Default: 2

The heading level. Only applies in cases where gradients are provided
from multiple origins (i.e. when the array passed as the gradients prop
contains two or more items).

loop

  • Type: boolean
  • Required: No
  • Default: true

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

onChange

  • Type: (currentGradient: string | undefined) => void
  • Required: Yes

The function called when a new gradient has been defined. It is passed to
the currentGradient as an argument.

value

  • Type: string | null
  • Required: No
  • Default: 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'

The current value of the gradient. Pass a css gradient string (See default value for example).
Optionally pass in a null value to specify no gradient is currently selected.