组合框控件

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

ComboboxControl 是 SelectControl 的增强版本，增加了通过搜索输入框查找选项的功能。

设计指南

这些与SelectControl 的设计指南相同，但当项目过多无法一次性滚动浏览或加载时，此组件更适合根据用户输入进行过滤。

开发指南

用法

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

const options = [
    {
        value: 'small',
        label: 'Small',
    },
    {
        value: 'normal',
        label: 'Normal',
    },
    {
        value: 'large',
        label: 'Large',
    },
];

function MyComboboxControl() {
    const [ fontSize, setFontSize ] = useState();
    const [ filteredOptions, setFilteredOptions ] = useState( options );
    return (
        <ComboboxControl
            label="Font Size"
            value={ fontSize }
            onChange={ setFontSize }
            isLoading={ isLoading }
            options={ filteredOptions }
            onFilterValueChange={ ( inputValue ) =>
                setFilteredOptions(
                    options.filter( ( option ) =>
                        option.value === inputValue
                    )
                )
            }
        />
    );
}

属性

label

控件的标签。

类型：String
必填：是

hideLabelFromVision

如果为 true，则标签仅对屏幕阅读器可见。

类型：Boolean
必填：否

help

如果添加了此属性，将使用 help 属性的内容生成帮助文本。

类型：String
必填：否

options

可供选择的选项。

类型：Array<{ value: string, label: string, disabled?: boolean }>
必填：是

onFilterValueChange

当控件的搜索输入值更改时调用的函数。参数包含下一个输入值。

类型：( value: string ) => void
必填：否

onChange

当选中值更改时调用的函数。

类型：( value: string | null ) => void
必填：否

value

控件的当前值。

类型：string | null
必填：否

expandOnFocus

当控件获得焦点时自动展开下拉菜单。
如果单击控件，无论此属性如何，下拉菜单都会展开。

类型：Boolean
必填：否
默认值：true

placeholder

如果传递了此属性，且没有值存在时，组合框输入将显示占位符字符串。

类型：string
必填：否

isLoading

在匹配建议（即 options 属性）的数据加载期间显示旋转图标（并隐藏建议下拉菜单）

类型：Boolean
必填：否

__experimentalRenderItem

为建议列表中的每个选项调用的自定义渲染器。渲染属性接收一个对象作为其参数，该对象在 item 键下包含单个选项的数据（直接来自传递给 options 属性的数据数组）。

类型：( args: { item: object } ) => ReactNode
必填：否