选择控件

SelectControl 允许用户从单个或复选菜单中进行选择。它作为浏览器原生 <select> 元素的包装器。

设计规范

用法

何时使用选择控件

在以下情况下使用选择控件：

• 您希望用户从列表中选择一个或多个选项。
• 存在一个强烈的默认选项。
• 可用空间有限。
• 菜单隐藏部分的内容可以从其标签和已选中的项中明显推断出来。例如，如果您有一个标记为“月份：”的选项菜单，并且选中了“一月”，用户可能会合理地推断出该菜单包含一年的 12 个月，而无需查看。

如果您的选项列表较短，请考虑改用 RadioControl。

建议
当有多个选项时使用选择控件。

不建议
对于二元问题使用选择控件。

行为

SelectControl 包含一个双箭头指示器。菜单以分层方式显示在选择控件上方。

打开和关闭

一旦菜单显示在屏幕上，它将保持打开状态，直到用户选择菜单项、点击菜单外部或切换到另一个浏览器标签页。

内容指南

标签

使用句子大小写将 SelectControl 标记为文本标签，放置在控件上方或左侧。点击标签可以让用户直接聚焦于选择控件。

建议
将标签放置在选择控件的上方或左侧。

不建议
将标签居中放置在选择控件上方，或与选择控件侧边右对齐。

菜单项

• 菜单项应简短——最好是单个单词——并使用句子大小写。
• 不要在菜单项中使用完整的句子。
• 确保菜单项的排序方式对用户最有用。首选按字母顺序或最新顺序排列。

建议
使用简短的菜单项。

不建议
在菜单中使用句子。

开发指南

用法

渲染一个用户界面以选择图像的大小。

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

const MySelectControl = () => {
    const [ size, setSize ] = useState( '50%' );

    return (
        <SelectControl
            label="Size"
            value={ size }
            options={ [
                { label: 'Big', value: '100%' },
                { label: 'Medium', value: '50%' },
                { label: 'Small', value: '25%' },
            ] }
            onChange={ ( newSize ) => setSize( newSize ) }
        />
    );
};

渲染一个用户界面以从列表中多选用户。

<SelectControl
    multiple
    label={ __( 'User' ) }
    value={ this.state.users } // e.g: value = [ 'a', 'c' ]
    onChange={ ( users ) => {
        this.setState( { users } );
    } }
    options={ [
        { value: '', label: 'Select a User', disabled: true },
        { value: 'a', label: 'User A' },
        { value: 'b', label: 'User B' },
        { value: 'c', label: 'User c' },
    ] }
/>

渲染一个用户界面以在组内选择项目

const [ item, setItem ] = useState( '' );

// ...

<SelectControl
    label={ __( 'My dinosaur' ) }
    value={ item } // e.g: value = 'a'
    onChange={ ( selection ) => { setItem( selection ) } }
>
    <optgroup label="Theropods">
        <option value="Tyrannosaurus">Tyrannosaurus</option>
        <option value="Velociraptor">Velociraptor</option>
        <option value="Deinonychus">Deinonychus</option>
    </optgroup>
    <optgroup label="Sauropods">
        <option value="Diplodocus">Diplodocus</option>
        <option value="Saltasaurus">Saltasaurus</option>
        <option value="Apatosaurus">Apatosaurus</option>
    </optgroup>
</SelectControl>

属性

• 组件接受的属性集将在下面指定。
• 未包含在此集中的属性将应用于 select 元素。
• 需要参考的一个重要属性是 value。如果 multiple 为 true，value 应该是包含所选选项值的数组。
• 如果 multiple 为 false，value 应等于所选选项的值。

label

如果添加了此属性，将使用 label 属性作为内容生成标签。

• 类型：String
• 必需：否

labelPosition

标签的位置（top、side 或 bottom）。

• 类型：String
• 必需：否

hideLabelFromVision

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

• 类型：Boolean
• 必需：否

help

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

• 类型：String|Element
• 必需：否

multiple

如果添加了此属性，可以选择多个值。传入的 value 应该是一个数组。

在大多数情况下，最好使用 FormTokenField 或 CheckboxControl 组件代替。

• 类型：Boolean
• 必需：否

options

包含以下属性的对象数组，以及任何其他的 option 元素属性：

• label：（字符串）要显示给用户的标签。
• value：（字符串）用于选择选定值的内部值。这也是选中该选项时传递给 onChange 的值。
• disabled：（布尔值）该选项是否应具有 disabled 属性。
• 类型：Array
• 必需：否

children

options 属性的替代方案。
使用 children 属性可以更灵活地控制正在渲染的项目样式，如 optgroups 或 options，并可能避免因 options 属性引用更新而导致的重新渲染。
– 类型：ReactNode
– 必需：否

onChange

接收新选中选项的值作为输入的函数。
如果 multiple 为 true，接收到的值是选中值的数组。
如果 multiple 为 false，接收到的值是包含新选中值的单个值。

• 类型：function
• 必需：是

value

所选选项的值。如果 multiple 为 true，value 应该是包含所选选项值的数组。

• 类型：String|String[]
• 必需：否

variant

控件的样式变体。

• 类型：'default' | 'minimal'
• 必需：否
• 默认值：'default'

相关组件

• 要从一组选项中选择一个选项，并且希望一次性显示所有可用选项，请使用 Radio 组件。
• 要从一组项目中选择一个或多个项目，请使用 CheckboxControl 组件。
• 要切换单个设置的开/关状态，请使用 ToggleControl 组件。