Tags

<sf-tag> показывает одну короткую метку: категорию, выбранное значение, фильтр или статус. Тег может быть статичным, переключаться нажатием и предлагать отдельную кнопку удаления. Элемент строится на классах компонента Теги; для неинтерактивной пометки рядом с объектом проще Badges.

Пример

<div class="flex flex-col gap-3">
  <div class="flex flex-wrap gap-2 items-cross-center">
    <sf-tag text="Дизайн" active></sf-tag>
    <sf-tag text="Разработка"></sf-tag>
    <sf-tag text="Тестирование"></sf-tag>
  </div>
  <div id="tag-values" class="flex flex-wrap gap-2 items-cross-center">
    <sf-tag kind="default" text="Задачи" count="12"></sf-tag>
    <sf-tag kind="default" status="success" text="Готово"></sf-tag>
    <sf-tag kind="icon" icon="location_on" text="Казань" close-label="Удалить: Казань"></sf-tag>
    <sf-tag kind="color" color-class="bg-primary" text="Основной проект" close-label="Удалить: Основной проект"></sf-tag>
  </div>
</div>

// A tag does not remove itself: its cross only sends `close`. The page that
// owns the values takes the tag away and moves focus to a neighbour, so the
// keyboard is not dropped at the top of the page.
const initializeTagRemoval = () => {
  const values = document.getElementById('tag-values');
  if (!values || values.dataset.exampleReady === 'true') return;
  values.dataset.exampleReady = 'true';

  values.addEventListener('close', (event) => {
    const tag = event.detail?.component;
    if (!tag || tag.localName !== 'sf-tag' || !values.contains(tag)) return;

    // The nearest tag that still has a button: the next one, else the
    // previous one. A static tag cannot take focus.
    const tags = [...values.querySelectorAll('sf-tag')];
    const index = tags.indexOf(tag);
    const target = [...tags.slice(index + 1), ...tags.slice(0, index).reverse()]
      .map((item) => item.querySelector('button'))
      .find(Boolean);
    tag.remove();
    target?.focus();
  });
};

initializeTagRemoval();

Применение

Что несёт тег

kind выбирает содержимое и поведение:

• checkbox — переключатель с флажком, вид по умолчанию;
• default — подпись и необязательное число count;
• icon — значок из icon перед подписью;
• color — цветной маркер; цвет задаёт утилита фона в color-class;
• avatar — аватар из avatar-image-url или инициалы из avatar-text.

text — видимая подпись. Слоты leading, text, count, avatar и close заменяют соответствующую часть своей разметкой; декоративная часть при этом не должна попадать в порядок Tab, а слот close содержит ровно одну нативную кнопку с доступным именем.

Статус и вид

status сообщает смысл из общего словаря: info, success, warning, error; без него тег нейтральный. appearance задаёт вид нейтрального тега на незнакомом фоне: default, surface — лёгкая заливка с границей, ghost — фон появляется только при наведении. Статусному тегу вид не нужен: смысл несёт его цвет.

Размер и плотность

size — ступень 1/3, 1/2, 1, 2 или 3, по умолчанию 1/2. spacing (compact, normal, comfortable, spacious) меняет вертикальные отступы, как у кнопок. inline ставит тег на строку другого элемента управления: без вертикальных отступов, с кнопкой удаления высотой в строку. В ячейке таблицы задайте line (1/2, 1, 2): тег станет на ступень меньше и уместится в строку текста этого размера, поэтому строка таблицы не вырастет.

Выбор

Тег kind="checkbox" — кнопка-переключатель. active задаёт выбранное состояние. Нажатие меняет его и отправляет всплывающее событие change; в event.detail.active — новое состояние, в event.detail.component — сам тег. disabled запрещает нажатие и событие.

document.querySelector('.filters').addEventListener('change', (event) => {
  if (event.target.localName !== 'sf-tag') return;
  applyFilter(event.target.getAttribute('text'), event.detail.active);
});

Удаление

closable добавляет отдельную кнопку удаления. У тегов icon, color и avatar она есть по умолчанию — closable="false" её убирает; у checkbox и default она появляется только с closable. Нажатие отправляет всплывающее событие close с тегом в event.detail.component. Сам тег не исчезает: убирает его приложение, когда удаление принято.

tags.addEventListener('close', (event) => {
  removeValue(event.detail.component.getAttribute('text'));
  event.detail.component.remove();
});

Так устроен второй ряд примера: крестик убирает тег, а фокус переходит на ближайший тег с кнопкой.

Методы onToggle() и onClose() выполняют те же действия из скрипта: переключают тег или отправляют close.

Тег, который что-то открывает

interactive (у всех видов, кроме checkbox) делает подпись кнопкой, а кнопка удаления остаётся рядом отдельной. Так устроены чипы фильтра: подпись открывает меню условия, крестик убирает фильтр. Обработчик click на теге получает нажатия по подписи; нажатие на крестик приходит как close.

Доступность

• Статичный тег — текст, он не получает фокус. В порядок Tab входят только нативные кнопки: переключатель, подпись интерактивного тега и кнопка удаления.
• Переключатель передаёт состояние через aria-pressed. Его имя — видимая подпись; aria-label уточняет её, если подпись сокращена.
• Кнопке удаления нужно конкретное имя: «Удалить: Казань», а не просто «Удалить». Передайте его в close-label; по умолчанию кнопка называется «Удалить» на русской странице и «Remove» на остальных.
• Enter и пробел нажимают кнопку в фокусе. Фокус виден при клавиатурной навигации и не меняет размеров тега.
• После удаления тега переведите фокус на соседний тег или на поле, из которого значение было выбрано.

Справочник API

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

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

Атрибуты

• template — string, по умолчанию default. Имя шаблона.
• kind — string, по умолчанию checkbox, значения: checkbox, icon, default, color, avatar. Содержимое тега: флажок, иконка, цвет, аватар или только подпись. Значение совместимости quantity также принимается и означает default.
• status — string, по умолчанию пусто, значения: пусто, info, success, warning, error. О чём сообщает тег, в общем словаре статусов. Оставьте пустым для тега, который ни о чём не сообщает.
• appearance — string, по умолчанию default, значения: default, surface, ghost. Внешний вид на основе нейтральной шкалы прозрачности, независимый от типа: surface сохраняет лёгкую заливку и границу, ghost не имеет ничего до наведения. Применяется только к нейтральным типам, потому что тег статуса передаёт смысл цветом.
• size — string, по умолчанию 1/2, значения: 1/3, 1/2, 1, 2, 3. Токен размера Framework: задаёт текст подписи и отступы по умолчанию.
• line — string, по умолчанию пусто, значения: пусто, 1/2, 1, 2. Занимает строку текста этого размера формы как встроенный тег на размер меньше — для ячейки таблицы, чтобы строка сохраняла высоту элемента управления. Переопределяет size и inline.
• spacing — string, по умолчанию normal, значения: compact, normal, comfortable, spacious. Вертикальные отступы отдельного тега с теми же названиями, что у кнопок.
• inline — boolean, по умолчанию false. Размещается на строке текста другого элемента управления: без вертикальных отступов, с подписью вровень и кнопкой удаления высотой в строку. Хост может задать –sf-tag–line.
• text — string, по умолчанию пусто. Видимая подпись тега.
• count — string, по умолчанию пусто. Необязательный счётчик, отображаемый в теге по умолчанию.
• icon — string, по умолчанию пусто. Имя декоративной иконки Framework.
• color-class — string, по умолчанию пусто. Семантическая утилита фона Framework для цветового маркера.
• avatar-image-url — string, по умолчанию пусто. URL изображения аватара; доступной подписью остаётся видимый текст.
• avatar-text — string, по умолчанию пусто. Инициалы аватара на случай отсутствия изображения.
• root-class — string, по умолчанию пусто. Утилитарные классы Framework для видимого корневого элемента.
• avatar-status — string, по умолчанию пусто. Зарезервированное значение статуса аватара для совместимых шаблонов.
• active — boolean, по умолчанию false. Состояние выбора тега-флажка.
• disabled — boolean, по умолчанию false. Отключает интерактивные действия переключения и закрытия.
• closable — boolean, по умолчанию false. Показывает отдельное действие удаления; у тегов с иконкой, цветом и аватаром оно включено по умолчанию, у тега-флажка — только когда атрибут задан.
• interactive — boolean, по умолчанию false. Отображает подпись как кнопку рядом с действием удаления — для тегов, которые что-то открывают (например, меню фильтра-чипа); для тегов-флажков игнорируется.
• aria-label — string, по умолчанию пусто. Необязательное переопределение доступного имени для выбираемого тега.
• close-label — string, по умолчанию пусто. Доступное имя действия удаления. По умолчанию Remove, на русской странице — Удалить.

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

Методы

• onToggle() — Переключает включённый тег-флажок и отправляет его новое активное состояние.
• onClose() — Отправляет намерение удаления для доступного закрываемого тега.

События

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

• change — detail: { active: boolean, component: object }. Изменилось активное состояние тега-флажка.
• close — detail: { component: object }. Удаление запрошено через отдельно названное действие закрытия.

Доступность

• Доступное имя: обязательно.
• Клавиши: Tab, Enter, Space.
• Фокус: В порядок табуляции входят только нативные действия переключения и закрытия. Фокус видим при работе с клавиатуры, не меняет геометрию и безопасен для режима forced colors.

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

<sf-tag text="Documentation"></sf-tag>

Источник

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

См. также

• Теги — теги на классах.
• Badges — неинтерактивная метка статуса или числа.