查看 WordPress Storybook 以获取更详细、交互式的文档。

GradientPicker 是一个 React 组件，用于渲染颜色渐变选择器
以定义多步渐变。支持 线性（linear） 或 径向（radial） 类型。

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

是否将其渲染在侧边栏中。

aria-label

  • Type: string
  • Required: No

用于标识控件用途的标签。

aria-labelledby

  • Type: string
  • Required: No

用于为控件提供标签的元素 ID。

className

  • Type: string
  • Required: No

添加到包装器上的类名。

clearable

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

调色板是否应包含清除按钮。

disableCustomGradients

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

如果为 true，则不会显示渐变选择器，仅显示来自 gradients 的定义渐变。

enableAlpha

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

是否在选择器中启用 Alpha 透明度选项。

gradients

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

一个对象数组，作为预定义的渐变显示在渐变选择器上方。或者，如果有多个组（或“来源”）的渐变，您可以传递一个对象数组，每个对象包含一个 name 和一个 gradients 数组，后者将包含预定义的对象渐变。

headingLevel

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

标题级别。仅在从多个来源提供渐变时适用（即当作为 gradients prop 传入的数组包含两个或更多项时）。

loop

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

防止键盘交互循环回绕。
仅与 listbox 呈现方式一起使用。

onChange

  • Type: (currentGradient: string | undefined, index?: number | undefined, slug?: string | undefined) => void
  • Required: Yes

定义新渐变时调用的函数。它接收 currentGradient 作为参数。当选择预定义渐变时，第二个参数是其索引（对于多来源渐变，则是来源索引），第三个参数是其 slug。

presentation

  • Type: "listbox" | "toggle-buttons" | "command-buttons"
  • Required: No
  • Default: 'listbox'

预定义渐变色块的行为及其对辅助技术的暴露方式。

  • listbox 使用一个制表符停止和箭头键导航，并通过 aria-selected 暴露选择状态。
  • toggle-buttons 为每个色块提供一个制表符停止，并通过 aria-pressed 暴露选择状态。
  • command-buttons 为每个色块提供一个制表符停止，且不暴露选择状态。value 和 selectedSlug 不会将预定义色块标记为选中，激活色块始终使用该色块调用 onChange。value 仍然控制自定义渐变选择器。

selectedSlug

  • Type: string
  • Required: No

当前选中的预定义渐变的 slug。

当设置为非空字符串时，选择由 slug 而非渐变值决定，这正确处理了共享相同渐变的调色板条目。在此模式下，slug 不匹配的条目即使其渐变值与 value 匹配也不会显示为选中状态。

空字符串被视为与 undefined 相同：选择回退到通过渐变值进行匹配。

value

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

当前的渐变值。传递一个 CSS 渐变字符串（参见默认值示例）。
可选地传递 null 值以指定当前未选择任何渐变。