Radio

<sf-radio> — радиокнопка: один вариант из группы взаимоисключающих, где все варианты видны сразу. Она собирает разметку радиокнопки из атрибутов. Для независимых вариантов берите Checkbox, для длинного списка — Dropdown.

Пример

<fieldset class="border-0 p-0 m-0">
  <legend class="m-bottom-2 weight-6">Когда опубликовать?</legend>
  <div class="flex flex-col gap-2">
    <sf-radio name="publish" value="now" label="Сейчас" checked></sf-radio>
    <sf-radio name="publish" value="later" label="По расписанию" description="Дату и время выберете на следующем шаге"></sf-radio>
    <sf-radio name="publish" value="draft" label="Сохранить черновик"></sf-radio>
  </div>
</fieldset>

Применение

Группа и значение

Радиокнопки с одинаковым name в одной форме составляют группу: отметка одной снимает отметку с остальных. value — машинное значение варианта; при отправке формы приходит значение отмеченного. Общее имя дайте всем вариантам одного вопроса и не давайте вариантам разных вопросов.

Группу размещайте в <fieldset>: общий вопрос пишется в <legend>, а не повторяется в названии каждого варианта. Один вариант отмечайте заранее атрибутом checked, если у вопроса есть разумный ответ по умолчанию.

Подпись и пояснение

label — видимое название варианта, description — пояснение под ним; щелчок по тексту тоже выбирает вариант. Вместо строк можно передать разметку в слоты label и description. help выводит рядом с названием значок с указанным именем; экранный диктор его не читает.

Размер, недоступность и ошибка

size выбирает ступень размерной шкалы: 1/2, 1 или 2. disabled выключает вариант. error показывает недопустимое состояние только цветом: текст ошибки разместите у группы.

Значение в форме

Внутри <sf-radio> лежит обычный <input type="radio">, поэтому отмеченный вариант попадает в FormData и отправку формы. Сброс формы возвращает отметку, заданную в разметке.

Выбор из кода и событие change

Выбор пользователем отправляет нативное событие change внутренней радиокнопки; оно всплывает через <sf-radio>, detail у него нет. Слушайте его на <fieldset> или форме и читайте event.target.value. Атрибут checked следует за выбором у всех радиокнопок группы.

setChecked(true) отмечает вариант из кода, setDisabled() выключает его; событие change при этом не отправляется.

const publish = document.querySelector('fieldset');
publish.addEventListener('change', (event) => {
  showSchedule(event.target.value === 'later');
});
document.querySelector('sf-radio[value="draft"]').setChecked(true);

Доступность

• Каждой радиокнопке нужно видимое название в label: отдельного aria-label у компонента нет.
• Группе нужно общее имя — <legend> внутри <fieldset>.
• Группа — одна остановка Tab: фокус приходит на отмеченный вариант или, если отмеченного нет, на первый. Стрелки переходят между вариантами и сразу выбирают их, Space отмечает вариант в фокусе.
• Ошибка показывается только цветом; текст ошибки свяжите с группой через aria-describedby.

Справочник API

Раздел собран из манифеста компонента выпуска ui-106d5901f8c3 и обновляется вместе с выпуском. Чтобы исправить описание, исправьте манифест.

Каждому атрибуту соответствует свойство элемента с тем же именем в camelCase: search-placeholder — searchPlaceholder. Свойство атрибута template называется templateName.

Атрибуты

• size — string, по умолчанию 1, значения: 1/2, 1, 2. Токен размера переключателя (radio).
• label — string, по умолчанию пусто.
• description — string, по умолчанию пусто.
• help — string, по умолчанию пусто.
• checked — boolean, по умолчанию false.
• disabled — boolean, по умолчанию false.
• name — string, по умолчанию пусто.
• value — string, по умолчанию пусто.
• error — boolean, по умолчанию false.

Методы

• getInputElement() — возвращает object | null. Возвращает внутренний нативный input (.sf-radio-button input[type=“radio”]) или null до отрисовки.
• setChecked(nextValue?: boolean) — возвращает object. Устанавливает свойство и состояние checked внутреннего input; не отправляет change.
• setDisabled(nextValue?: boolean) — возвращает object. Устанавливает или снимает disabled на хост-элементе и внутреннем input.
• setState(nextState: object) — возвращает object. Применяет checked и disabled к внутреннему input (установка checked также обновляет остальную именованную группу) и отражает их в атрибутах хост-элемента; до отрисовки использует базовый setState.
• onChange(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик нативного события change, которое всплывает от внутреннего input.
• onFocus(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик focusin на хост-элементе.
• onBlur(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик focusout на хост-элементе.

События

Все события приходят на сам элемент и всплывают. Общие события базового элемента перечислены в главе Жизненный цикл → Этапы.

• change — detail не описан. Выбор изменился; нативное событие всплывает от внутренней радиокнопки, которая является его целью. Имя для привязки.

Доступность

• Роль: радиокнопка (radio).
• Доступное имя: обязательно.
• Клавиши: Tab, стрелки, Space.
• Фокус: Сохраняет видимый фокус на активном элементе управления.

Минимальная разметка

<sf-radio></sf-radio>

Источник

• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/smart/radio
• simai/ui@106d5901f8c3b4f23131ce0e7ede5dbd8abfe4f4:distr/rule/rule.json#name=cl-radio