Buttons

<sf-button> рисует нативную кнопку с оформлением обычной кнопки: вид, цвет, размер, иконки и состояние загрузки задаются атрибутами. Берите его там, где кнопку создаёт шаблон или код, а состояние меняется во время работы; в статической разметке хватает классов sf-button.

Пример

<div class="flex flex-wrap gap-2 items-cross-center">
  <sf-button text="Сохранить"></sf-button>
  <sf-button appearance="tonal" text="Сохранить черновик"></sf-button>
  <sf-button appearance="outline" scheme="on-surface" text="Отмена"></sf-button>
  <sf-button appearance="link" text="Подробнее"></sf-button>
</div>

Применение

Вид и цвет

appearance задаёт вес кнопки: default — залитая основная, tonal — приглушённая заливка, outline — контур, link — текст без рамки, surface — нейтральная кнопка панелей инструментов. ghost — прежнее имя вида link: значение совместимости, которое манифест и журнал изменений объявляют до 2026-12-01; в разметке пишите link. На одном участке экрана оставляйте одну кнопку вида default.

scheme выбирает цветовое семейство: primary, secondary или on-surface. status="error" отмечает действие, которое удаляет данные или необратимо: такая кнопка окрашивается цветом ошибки поверх scheme.

size берёт ступень общей шкалы элементов управления: 1/3, 1/2, 1, 2, 3. spacing меняет внутренние отступы (compact, normal, comfortable, spacious), radius — скругление (default, square, rounded).

Подпись и иконки

Подпись задаёт text или дочерний элемент со slot="text". icon-start и icon-end ставят иконку в начало и в конец строки; icon — короткая запись одной иконки, её сторону выбирает icon-position. Пустой icon-start="" убирает иконку с этой стороны, даже если задан icon. Свою разметку иконки передают слоты icon-start и icon-end.

Состояния

loading показывает загрузку: кнопка недоступна и сообщает aria-busy="true". disabled отключает кнопку.

<div class="flex flex-wrap gap-2 items-cross-center">
  <sf-button icon-start="add" text="Добавить"></sf-button>
  <sf-button appearance="outline" scheme="on-surface" icon-end="arrow_forward" text="Далее"></sf-button>
  <sf-button loading text="Сохраняем"></sf-button>
  <sf-button disabled text="Недоступно"></sf-button>
  <sf-button status="error" icon-start="delete" text="Удалить проект"></sf-button>
</div>

Кнопка в форме и обработчики

native-type задаёт нативный type внутренней кнопки: button по умолчанию, submit или reset для формы. Кнопка рисуется в обычном DOM, поэтому submit отправляет форму, в которой стоит <sf-button>. Остальные атрибуты, которых нет в справочнике (name, value, form, data-*), переходят на внутреннюю кнопку.

Нажатие приходит обычным событием click. onClick(handler), onFocus, onBlur, onMouseEnter и onMouseLeave подписывают обработчик и возвращают сам элемент; setDisabled(true) и setDisabled(false) переключают доступность. Свойство value у <sf-button> возвращает объект с текущими настройками, а не значение для формы.

<form action="/profile" method="post">
  <sf-button native-type="submit" name="intent" value="save" text="Сохранить"></sf-button>
</form>

const button = await SF.createAsync('button', {
  text: 'Экспортировать',
  iconStart: 'download',
  appearance: 'outline',
});
document.querySelector('#toolbar').append(button);

button.onClick(async () => {
  button.setAttribute('loading', '');
  await exportReport();
  button.removeAttribute('loading');
});

Доступность

• Доступное имя кнопки — её подпись. Кнопке только с иконкой задайте aria-label или берите Icon Buttons.
• Фокус получает внутренняя нативная кнопка: Tab останавливается на ней, Enter и Space нажимают её. Иконки декоративны и скрыты от вспомогательных технологий.
• Недоступная кнопка выпадает из порядка Tab. Если пользователю нужно понять, почему действие недоступно, объясните это текстом рядом.
• Цвет ошибки при status="error" не заменяет подпись: из неё должно быть ясно, что действие удаляет данные.

Справочник API

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

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

Атрибуты

• template — string, по умолчанию default. Имя варианта шаблона для внешних шаблонов SfBaseElement.
• size — string, по умолчанию 1, значения: 1/3, 1/2, 1, 2, 3. Токен размера кнопки.
• appearance — string, по умолчанию default, значения: default, tonal, outline, link, surface, ghost. Вид кнопки. surface использует нейтральную шкалу прозрачности: лёгкая заливка и рамка. ghost — прежнее имя вида link, работает до 2026-12-01.
• scheme — string, по умолчанию primary, значения: primary, secondary, on-surface. Цветовое семейство элемента управления. Назначение элемента задаёт ось статуса; заданный там статус имеет приоритет.
• status — string, по умолчанию пусто, значения: пусто, error. Назначение элемента управления в общем словаре статусов. Элемент управления окрашивает только error — деструктивный статус: элемент, который удаляет, отбрасывает или выполняет необратимое действие.
• text-position — string, по умолчанию center.
• text — string, по умолчанию пусто. Видимый текст кнопки, если слот text не передан.
• segment — string, по умолчанию пусто.
• icon — string, по умолчанию пусто, например home, settings, search, edit, check, close. Сокращение для имени одной иконки.
• icon-start — string, по умолчанию пусто, например home, settings, search, edit, check, close. Имя иконки в логическом начале.
• icon-end — string, по умолчанию пусто, например home, settings, search, edit, check, close. Имя иконки в логическом конце.
• icon-position — string, по умолчанию start, значения: start, end. Расположение единственной иконки-ярлыка.
• spacing — string, по умолчанию normal, значения: compact, normal, comfortable, spacious. Семантический профиль внутренних отступов.
• radius — string, по умолчанию пусто, значения: пусто, default, square, rounded. Модификатор скругления углов.
• root-class — string, по умолчанию пусто. Дополнительные классы внутреннего элемента кнопки.
• loading — boolean, по умолчанию false. Флаг состояния загрузки.
• disabled — boolean, по умолчанию false. Флаг отключённого состояния.
• native-type — string, по умолчанию button, значения: button, submit, reset. Нативный атрибут type кнопки.
• aria-label — string, по умолчанию пусто. Доступная подпись для кнопок только с иконкой или пользовательских кнопок.

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

Свойства в документе макета

Узел типа smart.buttons в документе макета (simai.composition.document.v1) принимает:

• свойства: template, size, appearance, spacing, scheme, status, text, icon, icon-position, loading, disabled, native-type, aria-label.

Значения свойств те же, что у одноимённых атрибутов, и того же типа, что в списке атрибутов: строковое значение пишется строкой ("size": "1", а не 1 — число отклоняется с диагностикой schema_enum или schema_type), логическое — true или false.

Методы

• onClick(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик click на хост-элементе. Возвращает элемент.
• onFocus(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик focusin на хост-элементе. Возвращает элемент.
• onBlur(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик focusout на хост-элементе. Возвращает элемент.
• onMouseEnter(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик mouseenter на хост-элементе. Возвращает элемент.
• onMouseLeave(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик mouseleave на хост-элементе. Возвращает элемент.
• setDisabled(nextValue?: boolean) — возвращает object. Устанавливает атрибут disabled, если nextValue истинно, и удаляет его в противном случае. Возвращает элемент.

События

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

Доступность

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

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

<sf-button></sf-button>

Источник

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

См. также

• Icon Buttons — кнопка только с иконкой.
• Button Group — выбор одного варианта из кнопок.