Button Group

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

Пример

HTML

<div class="flex flex-col gap-2 items-cross-start" data-button-group-demo>
  <sf-button-group aria-label="Вид списка задач" value="list" items='[{"value":"list","label":"Список","icon":"view_list"},{"value":"board","label":"Доска","icon":"view_kanban"},{"value":"calendar","label":"Календарь","icon":"calendar_month"}]'></sf-button-group>
  <p class="m-0" role="status" data-button-group-result>Выбран вид: list</p>
</div>

JavaScript

document.querySelectorAll('[data-button-group-demo]').forEach((demo) => {
  const result = demo.querySelector('[data-button-group-result]');
  demo.addEventListener('change', (event) => {
    if (event.target.localName !== 'sf-button-group') return;
    result.textContent = `Выбран вид: ${event.detail.value}`;
  });
});

Применение

Варианты

Варианты передаются в items массивом JSON с полями value, label, icon, aria-label и disabled; сегментированный вид читает ещё count и icon-only. Короткая запись — строка, где варианты разделены символом |, а части варианта — ::: значение, подпись и флаги через запятую, например day::День|year::Год::disabled. Флаг icon=имя добавляет иконку. Значения в группе не повторяются: вариант с уже занятым значением пропускается.

Выбранный вариант задаёт value. Группа без value ничего не выделяет.

Вид и раскладка

Выбранная кнопка залита цветом из scheme, остальные остаются контурными кнопками нейтрального цвета. size и spacing берут ту же шкалу, что обычные кнопки. orientation="vertical" ставит кнопки столбцом и сообщает ориентацию вспомогательным технологиям; стрелки по обеим осям работают в любой ориентации.

HTML

<div class="flex flex-wrap gap-3 items-cross-start">
  <sf-button-group aria-label="Период отчёта" value="week" items="day::День|week::Неделя|month::Месяц|year::Год::disabled"></sf-button-group>
  <sf-button-group aria-label="Выравнивание текста" orientation="vertical" size="1/2" value="start" items="start::По началу::icon=format_align_left|center::По центру::icon=format_align_center|end::По концу::icon=format_align_right"></sf-button-group>
</div>

disabled на <sf-button-group> отключает всю группу, флаг disabled у варианта — только его.

Сегментированный вид

appearance="segmented" рисует группу как сегментированный переключатель: утопленная дорожка на заливке контейнера, сегменты без рамок и плашка под выбранным. По умолчанию (appearance="default") кнопки собраны в общий контур. Поведение не меняется: это тот же radiogroup с change, select() и clear(), панелей содержимого у него нет.

HTML

<div class="flex flex-col gap-3 items-cross-start">
  <sf-button-group appearance="segmented" aria-label="Тема" value="all" items='[{"value":"all","label":"Все","count":24},{"value":"light","label":"Светлые","count":17},{"value":"dark","label":"Тёмные","count":7}]'></sf-button-group>
  <sf-button-group appearance="segmented" plate="raised" size="1/2" aria-label="Вид списка" value="list" items='[{"value":"list","label":"Список","icon":"list","icon-only":true},{"value":"grid","label":"Сетка","icon":"grid_view","icon-only":true}]'></sf-button-group>
</div>

Атрибут или поле	Работа
`plate`	Плашка выбранного сегмента: `scheme` — заливка цвета из `scheme`, `raised` — приподнятая нейтральная поверхность с тенью
`full-width`	Дорожка занимает ширину контейнера, сегменты делят её поровну
`size`	Та же шкала, что у кнопок: сегмент равен по высоте кнопке того же размера
`count`	Число после подписи варианта; входит в доступное имя
`icon-only`	Вариант показывает только иконку, `label` остаётся его доступным именем; без `icon` флаг не действует

count и icon-only задаются только в записи JSON. В узком контейнере дорожка прокручивается внутри себя и не расширяет страницу.

Оформление настраивается переменными: --sf-button-group-background-color (дорожка), --sf-button-group-padding, --sf-button-group-color (сегмент), --sf-button-group-plate-background-color, --sf-button-group-plate-color и --sf-button-group-count-color.

Значение и событие `change`

Нажатие или стрелка выбирает вариант и отправляет всплывающее событие change. Его event.detail:

Поле	Содержимое
`previous`	значение до изменения; пустая строка, если выбора не было
`value`	новое значение; после `clear()` — пустая строка
`item`	данные выбранного варианта: `value`, `label`, `icon`, `disabled`; после `clear()` — `null`
`component`	элемент `<sf-button-group>`

Группа хранит выбор только в атрибуте value; сохранить его и применить выбранный вид — задача страницы. Методы select(value) и clear() меняют выбор из кода и отправляют то же событие; повторный выбор текущего варианта и выбор недоступного варианта ничего не меняют.

Группу можно создать из кода. items передавайте строкой: массив, переданный в SF.create, превращается в значение через пробел.

JavaScript

const group = await SF.createAsync('button-group', {
  ariaLabel: 'Период отчёта',
  items: 'day::День|week::Неделя|month::Месяц',
  value: 'week',
});
document.querySelector('#report-toolbar').append(group);
await group.whenRendered();

group.addEventListener('change', (event) => {
  loadReport({period: event.detail.value});
});
group.select('month');

Доступность

Группе нужно доступное имя: aria-label на <sf-button-group>. Подписи вариантов его не заменяют.
Группа — один переключатель (radiogroup) с одной остановкой Tab на выбранном варианте. Стрелки и Home, End переходят по доступным вариантам по кругу и сразу выбирают их; недоступные варианты пропускаются.
Вариант только с иконкой получает имя из поля aria-label; подпись label нужна и тогда, когда её не видно.
Выбранный вариант отличается не только цветом: у него есть aria-checked="true".

Справочник API

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

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


Тег	`<sf-button-group>`
Назначение	Управляемая группа одиночного выбора из кнопок Framework.
Контракт	`smart.button-group`, версия `1.0.0`
Поставка	выпуск Framework `ui-106d5901f8c3`
Жизненный цикл	экспериментальный: API может меняться между выпусками
Готовность	работает в сценарии студии, продуктовой приёмки нет
Заготовка до прихода кода	нет: атрибут `data-sf-skeleton` не пишется; своего скелетона при загрузке данных нет (Заготовка до прихода кода)

Атрибуты

template — string, по умолчанию default. Имя варианта шаблона.
items — array из object, по умолчанию [], например [{"value":"list","label":"List","icon":"list"},{"value":"grid","label":"Grid","icon":"grid_view"}], [{"value":"all","label":"Все","count":24},{"value":"light","label":"Светлые","count":17},{"value":"dark","label":"Тёмные","count":7}]. Выбираемые элементы со стабильными полями value, label, icon, count, icon-only и disabled.
value — string, по умолчанию пусто. Значение выбранного элемента.
size — string, по умолчанию 1, значения: 1/3, 1/2, 1, 2, 3. Общий токен размера кнопки.
spacing — string, по умолчанию normal, значения: compact, normal, comfortable, spacious. Общий семантический профиль внутренних отступов.
scheme — string, по умолчанию primary, значения: primary, secondary, on-surface. Цветовая схема выбранной кнопки, а в сегментированном виде — плашки выбранного сегмента.
appearance — string, по умолчанию default, значения: default, segmented. Вид группы. default собирает контурные кнопки в общий контур; segmented рисует утопленную дорожку с сегментами без рамок и плашкой под выбранным. Выбор, клавиатура и события одинаковы в обоих видах.
plate — string, по умолчанию scheme, значения: scheme, raised. Плашка выбранного сегмента в сегментированном виде: заливка цвета схемы или приподнятая нейтральная поверхность с тенью.
full-width — boolean, по умолчанию false. В сегментированном виде дорожка занимает ширину контейнера, а сегменты делят её поровну.
orientation — string, по умолчанию horizontal, значения: horizontal, vertical. Ориентация раскладки и навигации с клавиатуры.
disabled — boolean, по умолчанию false. Отключает всю группу.
aria-label — string, по умолчанию пусто. Доступное имя группы.
root-class — string, по умолчанию пусто. Дополнительные классы корневого элемента группы.

Прежние имена:

Имя	Прежнее имя	Состояние	Убирается после
`spacing`	`tightness`	работает, отмечается в `SF.deprecations`	2026-12-01
`spacing="compact"`	`tightness="low"`	работает, отмечается в `SF.deprecations`	2026-12-01
`spacing="comfortable"`	`tightness="high"`	работает, отмечается в `SF.deprecations`	2026-12-01
`spacing="spacious"`	`tightness="highest"`	работает, отмечается в `SF.deprecations`	2026-12-01

Методы

select(value: string) — возвращает object. Выбирает доступный элемент по значению.
clear() — возвращает object. Сбрасывает текущий выбор.
focus() — возвращает object | null. Переводит фокус на выбранный или первый доступный элемент.

События

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

change — detail: { component: any, previous: string, value: string, item: object|null }. Выбранное значение изменилось через select() или clear(); событие отправляется на хост-элементе, всплывает и с composed: true. Имя для привязки.
sf-button-group-change — устаревший псевдоним события change: приходит с тем же detail, подписывайтесь на change.

Доступность

Роль: группа переключателей (radiogroup).
Доступное имя: обязательно.
Клавиши: Tab, ArrowLeft, ArrowRight, ArrowUp, ArrowDown, Home, End.
Фокус: Используйте перемещаемый tabindex (roving tabindex) и внутренний индикатор focus-visible, который не перекрывает соседние сегменты.

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

HTML

<sf-button-group aria-label="View" items='[{"value":"list","label":"List"},{"value":"grid","label":"Grid"}]' value="list"></sf-button-group>

Источник

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

См. также

Buttons — кнопки, из которых собрана группа.
Smart-вкладки — когда варианты переключают панели содержимого.

Навигация

Главное

Документация

Содержание

Button Group

Пример

Применение

Варианты

Вид и раскладка

Сегментированный вид

Значение и событие `change`

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

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

Источник

См. также

Настройки

Button Group

Пример

Применение

Варианты

Вид и раскладка

Сегментированный вид

Значение и событие change

Доступность

Справочник API

Атрибуты

Методы

События

Доступность

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

Источник

См. также

Поиск по документации

Значение и событие `change`