概述

CustomSelectControl 是一个 WordPress 组件，允许用户从单选项菜单中选择项目，类似于 SelectControl，但支持为菜单中的每个项目提供自定义样式。由于不使用原生 元素，仅当需要自定义样式时使用。

关键要点

• CustomSelectControl 提供自定义样式能力，每个选项可定义 style 属性。
• 设计指南与 SelectControl 相同，开发时需注意仅在必要时使用。
• 组件支持受控和非受控用法，通过 value 和 onChange 属性管理状态。
• 提供多种 Props，如 label、options、size、__next40pxDefaultSize 等，用于定制组件行为。
• 相关组件包括 SelectControl（原生

）、Radio、CheckboxControl、ToggleControl 和 ComboboxControl，根据场景选择。

代码示例

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

const options = [
    {
        key: 'small',
        name: 'Small',
        style: { fontSize: '50%' },
    },
    {
        key: 'normal',
        name: 'Normal',
        style: { fontSize: '100%' },
    },
    {
        key: 'large',
        name: 'Large',
        style: { fontSize: '200%' },
    },
    {
        key: 'huge',
        name: 'Huge',
        style: { fontSize: '300%' },
    },
];

function MyCustomSelectControl() {
    const [ , setFontSize ] = useState();
    return (
        <CustomSelectControl
            __next40pxDefaultSize
            label="Font Size"
            options={ options }
            onChange={ ( { selectedItem } ) => setFontSize( selectedItem ) }
        />
    );
}

function MyControlledCustomSelectControl() {
    const [ fontSize, setFontSize ] = useState( options[ 0 ] );
    return (
        <CustomSelectControl
            __next40pxDefaultSize
            label="Font Size"
            options={ options }
            onChange={ ( { selectedItem } ) => setFontSize( selectedItem ) }
            value={ options.find( ( option ) => option.key === fontSize.key ) }
        />
    );
}

注意事项

• CustomSelectControl 不使用原生 元素，因此仅在需要自定义样式时使用，否则考虑 SelectControl。
  确保为每个选项提供 key、name 和可选的 style 属性，以支持自定义样式。
  使用 __next40pxDefaultSize 属性可提前适配未来版本的默认高度变化。
  注意 Props 如 label 和 options 是必需的，而其他如 className、hideLabelFromVision 等是可选的。

  ---

  📄 原文内容

  CustomSelectControl allows users to select an item from a single-option menu just like SelectControl, with the addition of being able to provide custom styles for each item in the menu. This means it does not use a native <select>, so should only be used if the custom styling is necessary.

  Design guidelines

  These are the same as the ones for SelectControls.

  Development guidelines

  Usage

  import { useState } from 'react';
  import { CustomSelectControl } from '@wordpress/components';
  
  const options = [
      {
          key: 'small',
          name: 'Small',
          style: { fontSize: '50%' },
      },
      {
          key: 'normal',
          name: 'Normal',
          style: { fontSize: '100%' },
      },
      {
          key: 'large',
          name: 'Large',
          style: { fontSize: '200%' },
      },
      {
          key: 'huge',
          name: 'Huge',
          style: { fontSize: '300%' },
      },
  ];
  
  function MyCustomSelectControl() {
      const [ , setFontSize ] = useState();
      return (
          <CustomSelectControl
              __next40pxDefaultSize
              label="Font Size"
              options={ options }
              onChange={ ( { selectedItem } ) => setFontSize( selectedItem ) }
          />
      );
  }
  
  function MyControlledCustomSelectControl() {
      const [ fontSize, setFontSize ] = useState( options[ 0 ] );
      return (
          <CustomSelectControl
              __next40pxDefaultSize
              label="Font Size"
              options={ options }
              onChange={ ( { selectedItem } ) => setFontSize( selectedItem ) }
              value={ options.find( ( option ) => option.key === fontSize.key ) }
          />
      );
  }
  

  Props

  className: string

  Optional classname for the component.

  • Required: No

  hideLabelFromVision: boolean

  Hide the label visually, while keeping available to assistive technology.

  • Required: No

  describedBy: string

  Description for the select trigger button used by assistive technology. If no value is passed, the text “Currently selected: selectedItem.name” will be used fully translated.

  • Required: No

  label: string

  Label for the control.

  • Required: Yes

  onChange: ( newValue: ChangeObject ) => void

  Function called with the control’s internal state changes. The selectedItem property contains the next selected item.

  • Required: No

  options: Array< Option >

  The list of options that can be chosen from.

  • Required: Yes

  size: 'default' | 'small' | '__unstable-large'

  The size of the control.

  • Default: 'default'
  • Required: No

  showSelectedHint: boolean

  Show the hint of the selected item in the trigger button.

  • Required: No

  value: Option

  Can be used to externally control the value of the control, like in the MyControlledCustomSelectControl example above.

  • Required: No

  onMouseOver: MouseEventHandler< HTMLButtonElement >

  A handler for mouseover events on the trigger button.

  • Required: No

  onMouseOut: MouseEventHandler< HTMLButtonElement >

  A handler for mouseout events on the trigger button.

  • Required: No

  onFocus: FocusEventHandler< HTMLButtonElement >

  A handler for focus events on the trigger button.

  • Required: No

  onBlur: FocusEventHandler< HTMLButtonElement >

  A handler for blur events on the trigger button.

  • Required: No

  __next40pxDefaultSize: boolean

  Start opting into the larger default height that will become the default size in a future version.

  • Required: No
  • Default: false

  Related components

  • Like this component, but implemented using a native <select> for when custom styling is not necessary, the SelectControl component.

  • To select one option from a set, when you want to show all the available options at once, use the Radio component.

  • To select one or more items from a set, use the CheckboxControl component.

  • To toggle a single setting on or off, use the ToggleControl component.

  • If you have a lot of items, ComboboxControl might be a better fit.