ToggleGroupControl — это экспериментальный React-компонент в WordPress, который предоставляет пользователям интерфейс для выбора одного значения из набора опций, организованных в горизонтальные сегменты. Этот компонент используется, когда требуется выбрать одно значение из нескольких, подобно группе радиокнопок, и может быть полезен для выбора между несколькими состояниями.
Основные возможности ToggleGroupControl
Компонент позволяет настроить различные свойства, такие как метка (label), текст помощи (help), режим отображения (isBlock), адаптивность (isAdaptiveWidth), и другие параметры. Его можно комбинировать с ToggleGroupControlOption для добавления отдельных элементов выбора.
Базовое использование
import {
__experimentalToggleGroupControl as ToggleGroupControl,
__experimentalToggleGroupControlOption as ToggleGroupControlOption,
} from '@wordpress/components';
import { useState } from 'react';
const ExampleToggleGroupControl = () => {
const [layout, setLayout] = useState('vertical');
return (
<ToggleGroupControl
label="Выберите макет"
value={layout}
onChange={(newLayout) => setLayout(newLayout)}
>
<ToggleGroupControlOption value="horizontal" label="Горизонтально" />
<ToggleGroupControlOption value="vertical" label="Вертикально" />
</ToggleGroupControl>
);
};
В этом примере компонент позволяет выбрать один из двух вариантов — «Горизонтально» или «Вертикально». Выбранное значение сохраняется в состоянии layout.
Основные параметры (Props) ToggleGroupControl
1. label
Тип: string
Описание: Определяет метку для компонента ToggleGroupControl, которая будет отображаться рядом с ним. Этот параметр обязателен, так как он помогает пользователю понять назначение выбора.
<ToggleGroupControl
label="Тип отображения"
/>
2. help
Тип: ReactNode
Описание: Добавляет текстовую подсказку под элементом. help может содержать дополнительную информацию о выбранных опциях.
<ToggleGroupControl
label="Режим отображения"
help="Выберите ориентацию макета для оптимального отображения"
/>
3. hideLabelFromVision
Тип: boolean
Описание: Если установлено в true, метка будет доступна только для программ экранного доступа, что полезно для улучшения доступности. Этот параметр актуален, если требуется скрыть метку с экрана, оставляя её только для чтения устройствами помощи.
<ToggleGroupControl
label="Цветовая схема"
hideLabelFromVision={true}
>
<ToggleGroupControlOption value="light" label="Светлая" />
<ToggleGroupControlOption value="dark" label="Тёмная" />
</ToggleGroupControl>
4. isAdaptiveWidth
Тип: boolean
Описание: Определяет, будут ли сегменты адаптироваться по ширине. Если isAdaptiveWidth установлено в true, каждый сегмент будет иметь ширину, соответствующую его содержимому.
<ToggleGroupControl
label="Выберите отображение"
isAdaptiveWidth={true}
>
<ToggleGroupControlOption value="grid" label="Сетка" />
<ToggleGroupControlOption value="list" label="Список" />
</ToggleGroupControl>
5. isDeselectable
Тип: boolean
Описание: Если установлено в true, пользователи могут снять выбор, повторно нажав на выбранный элемент. Это полезно, если состояние выбора должно иметь возможность сбрасываться.
<ToggleGroupControl
label="Вариант выбора"
isDeselectable={true}
>
<ToggleGroupControlOption value="option1" label="Опция 1" />
<ToggleGroupControlOption value="option2" label="Опция 2" />
</ToggleGroupControl>
6. isBlock
Тип: boolean
Описание: Рендерит ToggleGroupControl как блочный элемент CSS, занимая всю доступную ширину. Этот параметр рекомендуется использовать, если опции состоят из текста и не содержат иконок.
<ToggleGroupControl
label="Тип представления"
isBlock={true}
>
<ToggleGroupControlOption value="compact" label="Компактный" />
<ToggleGroupControlOption value="spacious" label="Просторный" />
</ToggleGroupControl>
7. onChange
Тип: (value?: string | number) => void
Описание: Колбэк, который вызывается при выборе опции. Получает текущее значение в качестве аргумента, что позволяет обрабатывать изменения состояния компонента.
import { useState } from 'react';
const ChangeHandlerExample = () => {
const [viewMode, setViewMode] = useState('light');
const handleModeChange = (newMode) => {
setViewMode(newMode);
console.log(`Выбранный режим: ${newMode}`);
};
return (
<ToggleGroupControl
label="Режим просмотра"
value={viewMode}
onChange={handleModeChange}
>
<ToggleGroupControlOption value="light" label="Светлый" />
<ToggleGroupControlOption value="dark" label="Темный" />
</ToggleGroupControl>
);
};
8. value
Тип: string | number
Описание: Устанавливает текущее значение ToggleGroupControl. Этот параметр используется для управления состоянием компонента.
<ToggleGroupControl
label="Выбор темы"
value="modern"
/>
9. __next40pxDefaultSize
Тип: boolean
Описание: Опционально включает более крупный размер по умолчанию, который будет использоваться в будущих версиях WordPress.
<ToggleGroupControl
label="Тип элементов"
__next40pxDefaultSize={true}
>
<ToggleGroupControlOption value="card" label="Карточки" />
<ToggleGroupControlOption value="list" label="Список" />
</ToggleGroupControl>
10. __nextHasNoMarginBottom
Тип: boolean
Описание: Если установлено в true, убирает нижний отступ у компонента. Это свойство используется для новых стилей WordPress и станет стандартом в будущем.
<ToggleGroupControl
label="Тип навигации"
__nextHasNoMarginBottom={true}
>
<ToggleGroupControlOption value="sidebar" label="Боковая панель" />
<ToggleGroupControlOption value="tabs" label="Вкладки" />
</ToggleGroupControl>
Полный пример использования ToggleGroupControl
В этом примере создается интерфейс выбора макета и темы, что позволяет выбрать один из нескольких параметров и сохранять выбранное значение.
import {
__experimentalToggleGroupControl as ToggleGroupControl,
__experimentalToggleGroupControlOption as ToggleGroupControlOption,
} from '@wordpress/components';
import { useState } from 'react';
const FullExampleToggleGroupControl = () => {
const [layoutType, setLayoutType] = useState('grid');
const [colorTheme, setColorTheme] = useState('light');
return (
<div>
<ToggleGroupControl
label="Тип макета"
value={layoutType}
onChange={(newLayout) => setLayoutType(newLayout)}
isBlock
>
<ToggleGroupControlOption value="grid" label="Сетка" />
<ToggleGroupControlOption value="list" label="Список" />
<ToggleGroupControlOption value="table" label="Таблица" />
</ToggleGroupControl>
<ToggleGroupControl
label="Цветовая тема"
value={colorTheme}
onChange={(newTheme) => setColorTheme(newTheme)}
help="Выберите тему для интерфейса"
isDeselectable
>
<ToggleGroupControlOption value="light" label="Светлая" />
<ToggleGroupControlOption value="dark" label="Тёмная" />
</ToggleGroupControl>
</div>
);
};
Заключение
Компонент ToggleGroupControl позволяет создавать удобный интерфейс выбора для различных настроек в WordPress.