Компонент SelectControl из библиотеки @wordpress/components предназначен для отображения выпадающего списка, который позволяет пользователю выбрать один или несколько вариантов. Этот компонент является оберткой для стандартного элемента <select>, но с улучшениями, сделанными для интеграции с экосистемой WordPress и улучшенной доступности.
Когда использовать SelectControl?
Используйте SelectControl, когда вам нужно предоставить пользователю возможность выбрать один или несколько вариантов из списка, а также в следующих случаях:
- Когда у вас есть несколько вариантов для выбора.
- Когда существует сильный вариант по умолчанию.
- Когда пространство ограничено.
- Когда содержимое скрытого меню очевидно из его метки.
Если список вариантов слишком короткий, можно использовать другие компоненты, такие как 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 ) }
__nextHasNoMarginBottom
/>
);
};
Объяснение кода
- Хук useState
Мы создаем локальное состояниеsize, которое будет хранить текущий размер. Начальное значение —50%. - Компонент
SelectControllabel: метка для выпадающего списка. В нашем примере это «Size».value: текущее значение, которое отображается в выпадающем списке. Здесь оно связано с состояниемsize.options: массив объектов, представляющих варианты для выбора. Каждый объект включает в себяlabel(текст, который видит пользователь) иvalue(внутреннее значение, которое передается при выборе).onChange: функция, которая обновляет значениеsizeпри выборе нового варианта из списка.
__nextHasNoMarginBottom
Этот пропс отключает нижний отступ, чтобы компонент выглядел более компактно.
Описание параметров (Props)
label
Тип:String
Обязательный: Нет
Описание: Метка для выпадающего списка. Это описание будет видимым для пользователей и доступным для экранных читалок.
label="Select a size"labelPosition
Тип:String
Обязательный: Нет
Описание: Определяет положение метки относительно компонента. Возможные значения:top,side, илиbottom.
labelPosition="top"
hideLabelFromVision
Тип:Boolean
Обязательный: Нет
Описание: Если установлено вtrue, метка будет видна только экранным читалкам, но не отображаться визуально.
hideLabelFromVision={ true }
help
Тип:String | Element
Обязательный: Нет
Описание: Дополнительная информация или подсказка, которая отображается под полем выбора. Это помогает пользователю понять, как использовать элемент.
help="Choose a size that suits your design."
multiple
Тип:Boolean
Обязательный: Нет
Описание: Если установлено вtrue, пользователь может выбрать несколько вариантов. В этом случае значениеvalueдолжно быть массивом.
multiple={ true }
options
Тип:Array
Обязательный: Нет
Описание: Массив объектов, представляющих варианты для выбора. Каждый объект должен содержать следующие свойства:label: метка для отображения.value: внутреннее значение, которое передается в функциюonChange.disabled: если установлено вtrue, вариант будет недоступен для выбора
options={ [
{ label: 'Option 1', value: '1' },
{ label: 'Option 2', value: '2' },
] }
children
Тип:ReactNode
Обязательный: Нет
Описание: Альтернативный способ передать элементы вSelectControl, например, группы вариантов (optgroup), что позволяет лучше контролировать стили элементов и их рендеринг.
<SelectControl>
<optgroup label="Group 1">
<option value="1">Option 1</option>
<option value="2">Option 2</option>
</optgroup>
</SelectControl>
onChange
Тип:function
Обязательный: Да
Описание: Функция, которая срабатывает при изменении выбранного значения. Она получает новое выбранное значение, которое может быть строкой или массивом (еслиmultipleустановлено вtrue).
onChange={ ( selectedValue ) => console.log(selectedValue) }
value
Тип:String | String[]
Обязательный: Нет
Описание: Текущее выбранное значение. Еслиmultipleустановлено вtrue, значение должно быть массивом.
value={ selectedValue }
variant
Тип:'default' | 'minimal'
Обязательный: Нет
Описание: Стиль компонента. Если нужно минималистичное отображение, можно выбрать вариант'minimal'.
variant="minimal"
__next40pxDefaultSize
Тип:Boolean
Обязательный: Нет
Значение по умолчанию:false
Описание: Включает более высокие стили для компонента, которые будут использоваться по умолчанию в будущих версиях.
__nextHasNoMarginBottom
Тип:Boolean
Обязательный: Нет
Значение по умолчанию:false
Описание: Отключает нижний отступ у компонента.
Пример использования с несколькими параметрами
import { useState } from 'react';
import { SelectControl } from '@wordpress/components';
const CustomSelectControl = () => {
const [ selectedUsers, setSelectedUsers ] = useState([ 'a', 'c' ]);
return (
<SelectControl
multiple
label="Select Users"
value={ selectedUsers }
onChange={ ( users ) => setSelectedUsers(users) }
options={ [
{ value: '', label: 'Select a User', disabled: true },
{ value: 'a', label: 'User A' },
{ value: 'b', label: 'User B' },
{ value: 'c', label: 'User C' },
] }
__nextHasNoMarginBottom
/>
);
};
Заключение
Компонент SelectControl предоставляет удобный способ отображения выпадающего списка с множеством вариантов. Это идеальный выбор для интерфейсов, где нужно выбрать один или несколько элементов из ограниченного списка. Кастомизация компонента с помощью различных пропсов позволяет вам адаптировать его под потребности вашего проекта, улучшая пользовательский опыт и доступность интерфейса.