RadioButton и RadioButtonGroup

RadioButton и RadioButtonGroup представляют собой ключевые компоненты для организации выбора одного варианта из нескольких в интерфейсе, соответствующем принципам IBM Carbon Design System. В Svelte их использование обеспечивает декларативное управление состоянием и тесную интеграцию с реактивностью фреймворка.

Основные свойства RadioButton

RadioButton — это отдельная кнопка выбора, которая должна находиться внутри группы (RadioButtonGroup) для корректного управления состоянием. Основные атрибуты:

  • id — уникальный идентификатор кнопки. Обязателен для связи с label.
  • value — значение, которое передается при выборе данной кнопки.
  • labelText — текст метки, отображаемый рядом с кнопкой.
  • name — имя группы кнопок. Радио-кнопки с одинаковым именем считаются частью одной группы.
  • disabled — логическое свойство, блокирующее возможность выбора.
  • hideLabel — скрывает визуальное отображение текста метки, оставляя доступным для скринридеров.
  • checked — указывает на то, выбрана ли кнопка при инициализации.

Пример простого использования:

<RadioButton
  id="option-1"
  name="example-group"
  value="option1"
  labelText="Первый вариант"
/>
<RadioButton
  id="option-2"
  name="example-group"
  value="option2"
  labelText="Второй вариант"
/>

Свойства RadioButtonGroup

RadioButtonGroup управляет коллекцией RadioButton, обеспечивая согласованное поведение и хранение выбранного значения. Основные атрибуты:

  • legendText — заголовок группы, описывающий смысл выбора.
  • name — имя группы, автоматически передается дочерним RadioButton.
  • valueSelected — реактивное свойство, отражающее текущее выбранное значение.
  • orientation — направление отображения кнопок (horizontal или vertical), по умолчанию вертикальное.
  • disabled — блокировка всей группы, передается всем дочерним кнопкам.
  • on:change — событие, срабатывающее при изменении выбора.

Пример использования:

<script>
  import { RadioButton, RadioButtonGroup } from "carbon-components-svelte";
  let selectedOption = "option1";
</script>

<RadioButtonGroup
  legendText="Выберите вариант"
  valueSelected={selectedOption}
  name="example-group"
  orientation="vertical"
  on:change={(e) => selectedOption = e.detail.value}
>
  <RadioButton
    id="option-1"
    value="option1"
    labelText="Первый вариант"
  />
  <RadioButton
    id="option-2"
    value="option2"
    labelText="Второй вариант"
  />
  <RadioButton
    id="option-3"
    value="option3"
    labelText="Третий вариант"
  />
</RadioButtonGroup>

Реактивное управление выбором

В Svelte компоненты Carbon автоматически интегрируются с реактивными переменными. Значение, выбранное в RadioButtonGroup, можно использовать напрямую в коде:

<p>Выбранный вариант: {selectedOption}</p>

При изменении выбора через интерфейс переменная selectedOption обновляется, обеспечивая синхронизацию состояния интерфейса и данных.

Вертикальная и горизонтальная ориентация

По умолчанию RadioButtonGroup располагает кнопки вертикально. Для горизонтального расположения используется атрибут orientation="horizontal":

<RadioButtonGroup legendText="Выбор цвета" orientation="horizontal" valueSelected={selectedColor} name="colors">
  <RadioButton id="red" value="red" labelText="Красный" />
  <RadioButton id="green" value="green" labelText="Зеленый" />
  <RadioButton id="blue" value="blue" labelText="Синий" />
</RadioButtonGroup>

Вертикальная ориентация подходит для длинных списков вариантов, горизонтальная — для компактных форм или радиокнопок в линию.

Доступность и семантика

RadioButtonGroup использует элемент <fieldset> и <legend>, обеспечивая семантическую структуру и поддержку скринридеров. Атрибут hideLabel позволяет скрыть текст, не нарушая доступность:

<RadioButton labelText="Скрытая метка" hideLabel={true} id="hidden" name="hidden-group" value="hidden" />

Обработка событий и кастомизация

Событие on:change передает объект CustomEvent, в detail которого содержится выбранное значение:

<RadioButtonGroup on:change={(e) => console.log("Выбрано:", e.detail.value)}>
  <RadioButton id="opt1" value="1" labelText="Опция 1" />
  <RadioButton id="opt2" value="2" labelText="Опция 2" />
</RadioButtonGroup>

Для стилизации используются стандартные CSS-классы Carbon. Можно применять модификаторы через class и расширять их с помощью Svelte scoped styles:

<style>
  .custom-radio .bx--radio-label {
    color: #0f62fe;
    font-weight: bold;
  }
</style>

<RadioButtonGroup class="custom-radio" valueSelected={selectedOption} name="styled-group">
  <RadioButton id="a" value="a" labelText="A" />
  <RadioButton id="b" value="b" labelText="B" />
</RadioButtonGroup>

Валидация и состояние ошибки

Для отображения ошибки можно использовать атрибуты invalid и invalidText:

<RadioButtonGroup
  legendText="Выберите вариант"
  valueSelected={selectedOption}
  invalid={true}
  invalidText="Необходимо выбрать один вариант"
  name="validate-group"
>
  <RadioButton id="1" value="1" labelText="Вариант 1" />
  <RadioButton id="2" value="2" labelText="Вариант 2" />
</RadioButtonGroup>

Система автоматически применяет стили для ошибки, выделяя группу визуально и предоставляя текст для скринридеров.

Итоговые рекомендации по использованию

  • Всегда группировать RadioButton внутри RadioButtonGroup для корректной работы состояния.
  • Использовать valueSelected для управления выбранным значением реактивно.
  • Применять orientation для адаптации интерфейса к макету.
  • Использовать legendText для семантики и доступности.
  • Валидация через invalid и invalidText обеспечивает единый UX для ошибок.

RadioButton и RadioButtonGroup в Carbon Components Svelte позволяют создавать доступные, настраиваемые и реактивные формы с минимальными усилиями, сохраняя строгие принципы дизайна IBM Carbon.

Оглавление