ComboboxControl — это расширенная версия компонента SelectControl, которая позволяет не только выбирать варианты из списка, но и фильтровать их по мере ввода текста. Этот компонент особенно полезен, когда количество опций велико и требуется эффективный способ поиска по ним.
Обзор компонента ComboboxControl
ComboboxControl работает аналогично элементу <select>, но с возможностью поиска. Пользователь может вводить текст в строку поиска, а список фильтруется в реальном времени. Компонент идеален для ситуаций, когда список опций длинный и требуется удобный поиск.
Применение ComboboxControl в WordPress
Чтобы использовать компонент ComboboxControl, его необходимо импортировать из @wordpress/components. Затем, вы можете передать ему список опций и функцию для обработки выбранного значения. Кроме того, можно настроить компонент для автоматического отображения списка при фокусе, а также скрыть метку, оставив её доступной только для скринридеров.
import { useState } from 'react';
import { ComboboxControl } from '@wordpress/components';
const fontOptions = [
{ value: 'small', label: 'Small' },
{ value: 'medium', label: 'Medium' },
{ value: 'large', label: 'Large' },
{ value: 'extra-large', label: 'Extra Large' },
];
function FontSizeSelector() {
const [fontSize, setFontSize] = useState();
const [filteredOptions, setFilteredOptions] = useState(fontOptions);
return (
<ComboboxControl
label="Select Font Size"
value={fontSize}
onChange={setFontSize}
options={filteredOptions}
onFilterValueChange={(inputValue) => {
setFilteredOptions(
fontOptions.filter(option =>
option.label.toLowerCase().includes(inputValue.toLowerCase())
)
);
}}
expandOnFocus={true}
placeholder="Type to search font size..."
/>
);
}
Подробное описание свойств (Props)
label
- Описание: Текст, отображаемый в качестве метки для компонента.
- Тип:
string - Обязателен: Да
- Пример:
"Font Size"
hideLabelFromVision
- Описание: Если
true, метка будет видима только для скринридеров. - Тип:
boolean - Обязателен: Нет
- Пример:
hideLabelFromVision={true}
help
- Описание: Текст помощи, отображаемый под компонентом.
- Тип:
string - Обязателен: Нет
- Пример:
"Выберите размер шрифта для текста."
options
- Описание: Массив с доступными опциями для выбора.
- Тип:
Array<{ value: string, label: string, disabled?: boolean }> - Обязателен: Да
- Пример:
const fontOptions = [
{ value: 'small', label: 'Small' },
{ value: 'medium', label: 'Medium' },
{ value: 'large', label: 'Large', disabled: true },
];onFilterValueChange
- Описание: Функция обратного вызова, вызываемая при изменении значения в поисковом поле.
- Тип:
(value: string) => void - Обязателен: Нет
- Пример:
onFilterValueChange={(inputValue) =>
setFilteredOptions(
options.filter(option =>
option.label.toLowerCase().includes(inputValue.toLowerCase())
)
)
}
onChange
- Описание: Функция обратного вызова, вызываемая при выборе значения.
- Тип:
(value: string | null | undefined) => void - Обязателен: Нет
- Пример:
onChange={(selectedValue) => console.log('Выбрано:', selectedValue)}
value
- Описание: Текущее выбранное значение.
- Тип:
string | null - Обязателен: Нет
- Пример:
value="medium"
expandOnFocus
- Описание: Автоматическое раскрытие выпадающего списка при фокусе.
- Тип:
boolean - По умолчанию:
true - Обязателен: Нет
- Пример:
expandOnFocus={false}
placeholder
- Описание: Текст-заполнитель, отображаемый в поле ввода поиска.
- Тип:
string - Обязателен: Нет
- Пример:
placeholder="Начните ввод для поиска"
__experimentalRenderItem
- Описание: Пользовательская функция рендера для каждого элемента в списке.
- Тип:
(args: { item: object }) => ReactNode - Обязателен: Нет
- Пример:
__experimentalRenderItem={({ item }) => (
<span style={{ color: item.value === 'large' ? 'red' : 'black' }}>
{item.label}
</span>
)}Пример 1: Базовый выбор опции с фильтрацией
Этот пример демонстрирует простую настройку ComboboxControl с меткой и списком размеров шрифта, в котором фильтрация происходит при изменении значения в поле поиска.
import { useState } from 'react';
import { ComboboxControl } from '@wordpress/components';
const fontSizes = [
{ value: 'xs', label: 'Extra Small' },
{ value: 's', label: 'Small' },
{ value: 'm', label: 'Medium' },
{ value: 'l', label: 'Large' },
];
function FontSizeSelectorExample() {
const [fontSize, setFontSize] = useState('');
const [filteredFontSizes, setFilteredFontSizes] = useState(fontSizes);
return (
<ComboboxControl
label="Font Size"
value={fontSize}
onChange={setFontSize}
options={filteredFontSizes}
onFilterValueChange={(inputValue) =>
setFilteredFontSizes(
fontSizes.filter(size =>
size.label.toLowerCase().includes(inputValue.toLowerCase())
)
)
}
placeholder="Search font size..."
/>
);
}
Пример 2: С использованием пользовательского рендера для каждого элемента
Этот пример показывает, как настроить отображение элементов, изменяя цвет шрифта каждого элемента списка в зависимости от его значения.
import { useState } from 'react';
import { ComboboxControl } from '@wordpress/components';
const colorOptions = [
{ value: 'red', label: 'Red' },
{ value: 'green', label: 'Green' },
{ value: 'blue', label: 'Blue' },
{ value: 'yellow', label: 'Yellow' },
];
function ColorSelector() {
const [color, setColor] = useState('');
return (
<ComboboxControl
label="Choose a Color"
value={color}
onChange={setColor}
options={colorOptions}
__experimentalRenderItem={({ item }) => (
<span style={{ color: item.value }}>
{item.label}
</span>
)}
placeholder="Search color..."
/>
);
}
Пример 3: Выбор с отключением опций
Этот пример демонстрирует компонент с отключенными опциями и текстом помощи.
import { useState } from 'react';
import { ComboboxControl } from '@wordpress/components';
const statusOptions = [
{ value: 'active', label: 'Active' },
{ value: 'inactive', label: 'Inactive', disabled: true },
{ value: 'archived', label: 'Archived' },
];
function StatusSelector() {
const [status, setStatus] = useState('');
return (
<ComboboxControl
label="User Status"
value={status}
onChange={setStatus}
options={statusOptions}
help="Select the current status of the user."
/>
);
}
Заключение
Компонент ComboboxControl предоставляет функциональность поиска для длинных списков, облегчая пользователю выбор нужной опции. Компонент гибко настраивается, поддерживает пользовательские рендеры и позволяет фильтровать элементы списка по мере ввода.