自定义下拉选择控件

最后更新：2026-10-17 10:55:29

CustomSelectControl 允许用户从单选项菜单中选择一个项目，就像 SelectControl 一样，并增加了为菜单中的每个项目提供自定义样式的功能。这意味着它不使用原生的 <select>，因此仅在使用自定义样式是必要的情况下才应使用。

设计指南

这些与适用于 SelectControl 的指南相同。

开发指南

用法

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
            label="Font Size"
            options={ options }
            onChange={ ( { selectedItem } ) => setFontSize( selectedItem ) }
        />
    );
}

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

属性

className: string

组件的可选类名。

必需：否

hideLabelFromVision: boolean

在视觉上隐藏标签，同时使其对辅助技术可用。

必需：否

describedBy: string

供辅助技术使用的选择触发按钮的描述。如果未传递值，将使用完全翻译后的文本“当前选择：selectedItem.name”。

必需：否

label: string

控件的标签。

必需：是

onChange: ( newValue: ChangeObject ) => void

当控件的内部状态发生变化时调用的函数。selectedItem 属性包含下一个选定的项目。

必需：否

options: Array< Option >

可供选择的选项列表。

必需：是

size: ‘default’ | ‘small’ | ‘\_\_unstable-large’

控件的大小。

默认值：'default'
必需：否

showSelectedHint: boolean

在触发按钮中显示选定项目的提示。

必需：否

value: Option

可用于外部控制控件的值，如上面的 MyControlledCustomSelectControl 示例所示。

必需：否

onMouseOver: MouseEventHandler< HTMLButtonElement >

触发按钮上 mouseover 事件的处理程序。

必需：否

onMouseOut: MouseEventHandler< HTMLButtonElement >

触发按钮上 mouseout 事件的处理程序。

必需：否

onFocus: FocusEventHandler< HTMLButtonElement >

触发按钮上 focus 事件的处理程序。

必需：否

onBlur: FocusEventHandler< HTMLButtonElement >

触发按钮上 blur 事件的处理程序。

必需：否