Checkbox

<sf-checkbox> — флажок для независимого выбора: каждый вариант отмечают или снимают отдельно от остальных. Он собирает разметку флажка из атрибутов. Для одного варианта из нескольких берите Radio, для настройки, которая действует сразу, — Switch.

Пример

<fieldset class="border-0 p-0 m-0">
  <legend class="m-bottom-2 weight-6">Какие уведомления получать?</legend>
  <div class="flex flex-col gap-2">
    <sf-checkbox name="notifications[]" value="product" label="Новости продукта" checked></sf-checkbox>
    <sf-checkbox name="notifications[]" value="events" label="Приглашения на мероприятия" description="Не чаще раза в месяц"></sf-checkbox>
    <sf-checkbox name="notifications[]" value="research" label="Новые исследования" disabled></sf-checkbox>
  </div>
</fieldset>

Применение

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

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

Группа вариантов

Связанные флажки объединяйте в <fieldset>: общий вопрос пишется в <legend>, а каждый флажок сохраняет своё название. Одинаковое name у флажков группы (notifications[] в примере) собирает отмеченные значения в один список при отправке формы.

Смешанное состояние

indeterminate показывает флажок, который обобщает группу, где отмечена только часть вариантов. Это только вид: значения он не меняет, а щелчок пользователя снимает смешанное состояние. Итоговое состояние такого флажка считает приложение — в примере ниже по изменению любого варианта.

<fieldset id="export-columns" class="border-0 p-0 m-0">
  <legend class="m-bottom-2 weight-6">Столбцы для выгрузки</legend>
  <div class="flex flex-col gap-2">
    <sf-checkbox data-role="all" label="Все столбцы" indeterminate></sf-checkbox>
    <div class="flex flex-col gap-2 p-inline-start-4">
      <sf-checkbox data-role="item" name="columns[]" value="title" label="Название" checked></sf-checkbox>
      <sf-checkbox data-role="item" name="columns[]" value="author" label="Автор"></sf-checkbox>
      <sf-checkbox data-role="item" name="columns[]" value="updated" label="Дата изменения"></sf-checkbox>
    </div>
  </div>
</fieldset>

// The «all» box summarises the boxes below it: checked when every one is,
// mixed when some are, empty when none are. Clicking it sets them all.
const initializeSelectAll = async () => {
  const group = document.getElementById('export-columns');
  if (!group || group.dataset.exampleReady === 'true') return;
  group.dataset.exampleReady = 'true';

  await customElements.whenDefined('sf-checkbox');
  const all = group.querySelector('[data-role="all"]');
  const items = [...group.querySelectorAll('[data-role="item"]')];
  await Promise.all([all, ...items].map((box) => box.whenRendered()));

  const summarise = () => {
    const checked = items.filter((box) => box.isChecked()).length;
    all.setChecked(checked === items.length);
    all.setIndeterminate(checked > 0 && checked < items.length);
  };

  group.addEventListener('change', (event) => {
    if (all.contains(event.target)) {
      const next = all.isChecked();
      items.forEach((box) => box.setChecked(next));
    }
    summarise();
  });
  summarise();
};

initializeSelectAll();

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

size выбирает ступень размерной шкалы: 1/2, 1 или 2. position="end" ставит флажок после текста, в конце строки; по умолчанию он стоит в начале.

Ошибка

error показывает недопустимое состояние и ставит aria-invalid на внутренний флажок. Текст ошибки компонент не выводит: разместите его рядом с группой и свяжите с ней через aria-describedby.

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

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

Состояние из кода и событие change

Отметка пользователем отправляет нативное событие change внутреннего флажка; оно всплывает через <sf-checkbox>, detail у него нет. Состояние читайте из event.target.checked или методом isChecked(). Атрибуты checked и indeterminate на элементе следуют за состоянием флажка.

setChecked(), setIndeterminate() и setDisabled() меняют состояние из кода и события change не отправляют. Элемент, созданный через SF.createAsync, готов к таким вызовам после вставки на страницу и whenRendered().

const terms = await SF.createAsync('checkbox', {
  name: 'terms',
  value: 'accepted',
  label: 'Принимаю условия',
  onChange: (event) => submit.toggleAttribute('disabled', !event.target.checked),
});
form.append(terms);
await terms.whenRendered();
terms.setChecked(false);

Доступность

• Каждому флажку нужно доступное имя: видимый label или, если подписи нет, aria-label — например, у флажка выбора строки в таблице. Имя попадает на внутренний флажок.
• Каждый флажок — отдельная остановка Tab; Space отмечает и снимает его. Фокус виден на самом флажке.
• Общий вопрос группы задаёт <legend>: экранный диктор читает его перед первым вариантом.
• Смешанное состояние экранный диктор объявляет как «частично отмечено».

Справочник API

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

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

Атрибуты

• size — string, по умолчанию 1, значения: 1/2, 1, 2. Токен размера чекбокса.
• label — string, по умолчанию пусто.
• description — string, по умолчанию пусто.
• help — string, по умолчанию пусто.
• position — string, по умолчанию start, значения: start, end. Логическое расположение индикатора относительно текста.
• root-class — string, по умолчанию пусто.
• checked — boolean, по умолчанию false.
• disabled — boolean, по умолчанию false.
• indeterminate — boolean, по умолчанию false. Смешанное визуальное состояние чекбокса, обобщающего связанные варианты.
• name — string, по умолчанию пусто.
• value — string, по умолчанию пусто.
• error — boolean, по умолчанию false. Недопустимое состояние; нативное поле ввода публикует aria-invalid.
• aria-label — string, по умолчанию пусто. Доступное имя чекбокса без видимой подписи.

Методы

• getInputElement() — возвращает object | null. Возвращает внутренний нативный input флажка или null до отрисовки.
• isChecked() — возвращает boolean. Возвращает текущее нативное состояние checked.
• setChecked(nextValue?: boolean|string) — возвращает object. Устанавливает состояние checked в атрибуте хост-элемента и во внутреннем input через setState(). Возвращает элемент.
• setIndeterminate(nextValue?: boolean|string) — возвращает object. Устанавливает состояние indeterminate в атрибуте хост-элемента и во внутреннем input через setState(). Возвращает элемент.
• setDisabled(nextValue?: boolean|string) — возвращает object. Устанавливает состояние disabled в атрибуте хост-элемента и во внутреннем input через setState(). Возвращает элемент.
• setBooleanStateAttribute(name: string, value: boolean) — возвращает null. Добавляет указанный атрибут хост-элемента как пустой атрибут, когда value истинно, и удаляет его в противном случае.
• setState(nextState?: object) — возвращает object. Применяет checked, indeterminate и disabled и к атрибуту хост-элемента, и к внутреннему input; остальные ключи передаются в базовый setState как атрибуты хост-элемента. Возвращает элемент.
• onChange(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик change на хост-элементе. Возвращает элемент.
• onFocus(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик focusin на хост-элементе. Возвращает элемент.
• onBlur(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик focusout на хост-элементе. Возвращает элемент.

События

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

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

Доступность

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

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

<sf-checkbox></sf-checkbox>

Источник

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