List Item

<sf-list-item> описывает один вариант Dropdown: машинное значение, подпись и вид строки — текст, иконка, флажок, аватар или цветовой маркер. Сам по себе элемент ничего не выбирает: список, фокус, выбор и значение формы принадлежат родительскому Dropdown.

Пример

<div class="grid grid-col-1 md:grid-col-2 gap-3">
  <sf-dropdown name="place" label="Место" placeholder="Выберите место" search-placeholder="Найти">
    <sf-list-item value="office" type="icon" icon="apartment" text="Офис"></sf-list-item>
    <sf-list-item value="home" type="icon" icon="home" text="Дом"></sf-list-item>
    <sf-list-item value="travel" type="icon" icon="flight" text="Командировка" disabled></sf-list-item>
  </sf-dropdown>
  <sf-dropdown name="labels" label="Метки" placeholder="Выберите метки" search-placeholder="Найти" multiple>
    <sf-list-item value="bug" type="color" color-class="bg-error" text="Ошибка"></sf-list-item>
    <sf-list-item value="feature" type="color" color-class="bg-primary" text="Доработка" selected></sf-list-item>
    <sf-list-item value="docs" type="color" color-class="bg-tertiary" text="Документация"></sf-list-item>
  </sf-dropdown>
</div>

Применение

Место в разметке

Ставьте <sf-list-item> прямым потомком <sf-dropdown>. Dropdown читает атрибуты пунктов до первой отрисовки и строит из них список. Пункт вне Dropdown показывается статичной строкой: без роли, фокуса и реакции на нажатие. Его нельзя использовать как кнопку, ссылку или отдельный флажок.

Значение и подпись

value — машинное значение, которое уходит в форму и в событие change Dropdown; без value значением становится text. text — видимая подпись, она же доступное имя варианта. selected отмечает вариант выбранным при загрузке, disabled запрещает его выбор. group объединяет идущие подряд пункты под одним заголовком.

Вид строки

Вид строки задаёт атрибут type:

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

Манифест называет эту ось kind, а type — прежним именем. Dropdown читает у дочерних пунктов только type, поэтому внутри Dropdown вид строки задавайте им.

size — ступень 1/3, 1/2, 1, 2 или 3. Без него пункт берёт размер своего Dropdown.

<sf-dropdown name="owner" label="Ответственный" placeholder="Выберите ответственного">
  <sf-list-item value="anna" type="avatar" text="Анна Белова" avatar-image-url="/team/anna.jpg"></sf-list-item>
  <sf-list-item value="ivan" type="avatar" text="Иван Петров" avatar-image-url="/team/ivan.jpg"></sf-list-item>
</sf-dropdown>

Доступность

• В Dropdown каждый пункт получает role="option", aria-selected и aria-disabled. Имя варианта — text; aria-label заменяет его, если подпись сокращена или неоднозначна.
• Клавиши принадлежат Dropdown: стрелки перемещают по вариантам, Home и End — к первому и последнему, Enter и пробел выбирают, Escape закрывает список.
• Иконка, аватар, цветовой маркер и флажок декоративны и не создают отдельных остановок Tab. Не кладите в пункт ссылки, кнопки и поля: у варианта списка может быть только одно действие — выбор.
• Цвет маркера не должен быть единственным различием между вариантами: подпись называет вариант словами.

Справочник API

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

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

Атрибуты

• template — string, по умолчанию default.
• value — string, по умолчанию пусто.
• kind — string, по умолчанию text, значения: text, icon, checkbox, avatar, color. Содержимое элемента списка: простой текст, иконка, флажок, аватар или цвет.
• size — string, по умолчанию 1, значения: 1/3, 1/2, 1, 2, 3.
• text — string, по умолчанию пусто.
• icon — string, по умолчанию person.
• checked — boolean, по умолчанию false.
• selected — boolean, по умолчанию false.
• disabled — boolean, по умолчанию false.
• color-class — string, по умолчанию bg-tertiary.
• avatar-image-url — string, по умолчанию пусто.
• avatar-title — string, по умолчанию пусто.
• aria-label — string, по умолчанию пусто.

Свойство атрибута value называется itemValue.

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

Методы

Публичных методов нет.

События

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

Доступность

• Роль: option при отображении внутри Dropdown; нет в автономном превью.
• Доступное имя: обязательно.
• Клавиши: ArrowDown, ArrowUp, Home, End, Enter, Space, Escape.
• Фокус: Принадлежит родительскому составному компоненту Dropdown; отдельный предпросмотр не фокусируется.

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

<sf-dropdown label="Статус"><sf-list-item value="open" text="Открыт"></sf-list-item><sf-list-item value="done" text="Готов"></sf-list-item></sf-dropdown>

Источник

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

См. также

• Dropdown — выпадающий список, которому принадлежат пункты.
• Выпадающий список — классы строки списка.