Switch

<sf-switch> — переключатель настройки, которая начинает действовать сразу после нажатия. Он собирает разметку переключателя из атрибутов. Если значение уходит с формой только после подтверждения, берите Checkbox.

Пример

<div class="flex flex-col gap-3">
  <sf-switch name="notifications" value="enabled" label="Уведомления" description="Сообщать о завершении фоновых задач" checked></sf-switch>
  <sf-switch name="compact" value="on" label="Компактный режим"></sf-switch>
  <sf-switch name="sync" value="on" label="Синхронизация" description="Недоступна в офлайн-режиме" disabled></sf-switch>
</div>

Применение

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

label называет настройку, description поясняет, что она меняет. Подпись называет состояние или возможность — «Уведомления», «Компактный режим», — а не команду «Включить» или «Выключить»: положение переключателя уже говорит, включена ли настройка. Вместо строк можно передать разметку в слоты label и description. help выводит рядом с подписью значок с указанным именем; экранный диктор его не читает.

Размер и длина дорожки

size выбирает ступень размерной шкалы: 1/2, 1 или 2. Берите ступень полей и кнопок той же формы. Для плотного списка настроек дорожку укорачивает класс sf-switch--short, переданный в root-class.

<div class="flex flex-col gap-3">
  <sf-switch size="1/2" label="Размер 1/2" checked></sf-switch>
  <sf-switch size="1" label="Размер 1" checked></sf-switch>
  <sf-switch size="2" label="Размер 2" checked></sf-switch>
  <sf-switch root-class="sf-switch--short" label="Короткая дорожка" checked></sf-switch>
</div>

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

Внутри <sf-switch> лежит обычный <input type="checkbox" role="switch"> с переданными name и value. Включённый переключатель попадает в FormData и отправку формы, выключенный — нет. Сброс формы возвращает положение, заданное атрибутом checked в разметке.

Применение настройки и событие change

Нажатие отправляет нативное событие change внутреннего input; оно всплывает через <sf-switch>, detail у него нет. Новое положение читайте из event.target.checked и применяйте настройку сразу. Атрибут checked на элементе следует за положением.

setChecked() и setDisabled() меняют положение и доступность из кода, события change при этом нет. Если сохранить настройку не удалось, верните переключатель в прежнее положение.

const compact = document.querySelector('sf-switch[name="compact"]');
compact.addEventListener('change', async (event) => {
  const enabled = event.target.checked;
  try {
    await saveSetting('compact', enabled);
  } catch {
    compact.setChecked(!enabled);
  }
});

Доступность

• Переключателю нужно видимое название в label: отдельного aria-label у компонента нет.
• Внутренний input с role="switch" сообщает экранному диктору, что это переключатель, и его положение — «вкл.» или «выкл.».
• Каждый переключатель — отдельная остановка Tab; Space меняет положение.
• Бегунок скрыт от вспомогательных технологий: положение передаёт input.

Справочник API

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

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

Атрибуты

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

Методы

• getInputElement() — возвращает object | null. Возвращает внутренний нативный input (.sf-switch input[type=“checkbox”]) или null до отрисовки.
• setChecked(nextValue?: boolean) — возвращает object. Устанавливает свойство и состояние checked внутреннего input; не отправляет change.
• setDisabled(nextValue?: boolean) — возвращает object. Устанавливает или снимает disabled на хост-элементе и внутреннем input.
• setState(nextState: object) — возвращает object. Применяет checked и disabled к внутреннему input и отражает их в атрибутах хост-элемента; до отрисовки использует базовый 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 не описан. Изменилось состояние «включено»; нативное событие всплывает от внутреннего флажка, который является его целью.

Доступность

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

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

<sf-switch></sf-switch>

Источник

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