Tree

<sf-tree> показывает вложенный список: папки и файлы, разделы сайта, категории каталога. Ветви раскрываются и сворачиваются, пункты выбираются мышью и клавиатурой. Каждый пункт — Tree Item; оформление совпадает с обычным деревом. Для короткого плоского списка берите обычный список, для пути к текущей странице — Breadcrumbs.

Пример

<sf-tree aria-label="Папки проекта">
  <sf-tree-item label="Документы" open open-label="Развернуть" close-label="Свернуть">
    <sf-tree-item label="Договоры"></sf-tree-item>
    <sf-tree-item label="Счета"></sf-tree-item>
  </sf-tree-item>
  <sf-tree-item label="Изображения" open-label="Развернуть" close-label="Свернуть">
    <sf-tree-item label="Обложки"></sf-tree-item>
    <sf-tree-item label="Иконки"></sf-tree-item>
  </sf-tree-item>
  <sf-tree-item label="Архив"></sf-tree-item>
</sf-tree>

Применение

Пункты из разметки

Пункты — дочерние <sf-tree-item>, вложенные друг в друга так же, как ветви дерева. Дерево читает их при подключении и рисует заново; пункты, добавленные в <sf-tree> позже, дописываются в конец. Подпись, ссылку, тип и состояние пункта задают его атрибуты — они описаны на странице Tree Item.

Пункты данными

Свойство items принимает массив пунктов. Поля пункта: label, href, target, rel, type (folder или file), value, open, selected, active, disabled, openIcon, closedIcon, icon, openLabel, closeLabel и children — массив вложенных пунктов. Новый массив перерисовывает дерево целиком; так передают дерево, которое строит шаблон или приходит с сервера. Задавайте items после регистрации тега.

<sf-tree aria-label="Файлы проекта" data-tree-files-demo></sf-tree>

customElements.whenDefined('sf-tree').then(() => {
  document.querySelectorAll('[data-tree-files-demo]').forEach((tree) => {
    tree.items = [
      {
        label: 'Документы',
        open: true,
        children: [
          {label: 'Договор.pdf', type: 'file'},
          {label: 'Смета.xlsx', type: 'file'},
        ],
      },
      {label: 'Изображения', children: [{label: 'Обложка.png', type: 'file'}]},
      {label: 'README.md', type: 'file'},
    ];
  });
});

Выбор

selection задаёт, что делает нажатие на пункт. none (по умолчанию) — нажатие открывает ссылку пункта или отправляет sf-tree-item-click. single выбирает один пункт, multiple переключает выбор каждого пункта отдельно. Выбранный пункт отмечен атрибутом selected; изначальный выбор задают тем же атрибутом в разметке.

<div class="flex flex-col gap-2" data-tree-selection-demo>
  <sf-tree aria-label="Папка для сохранения" selection="single">
    <sf-tree-item label="Входящие" value="inbox" selected></sf-tree-item>
    <sf-tree-item label="Проекты" value="projects" open open-label="Развернуть" close-label="Свернуть">
      <sf-tree-item label="Сайт компании" value="site"></sf-tree-item>
      <sf-tree-item label="Мобильное приложение" value="app"></sf-tree-item>
    </sf-tree-item>
    <sf-tree-item label="Архив" value="archive"></sf-tree-item>
  </sf-tree>
  <p class="m-0" role="status" data-tree-selection-result>Выбрана папка: inbox</p>
</div>

document.querySelectorAll('[data-tree-selection-demo]').forEach((demo) => {
  const result = demo.querySelector('[data-tree-selection-result]');
  demo.addEventListener('sf-tree-selection-change', (event) => {
    result.textContent = `Выбрана папка: ${event.detail.value}`;
  });
});

События

События всплывают от пунктов, поэтому их удобно слушать на <sf-tree>. onToggle(handler) передаёт обработчику элемент пункта первым аргументом.

const tree = document.querySelector('sf-tree[selection="single"]');

tree.addEventListener('sf-tree-selection-change', (event) => {
  saveTarget(event.detail.value);
});

tree.onToggle((item, detail) => {
  if (detail.open) loadChildren(detail.value);
});

await customElements.whenDefined('sf-tree');
tree.items = await fetchFolders();

Перетаскивание на узел

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

• accept-records — узел принимает записи, перетащенные из списка, например строки таблицы с drag-rows. После отпускания приходит sf-tree-records-drop с {value, ids, source}: value — узел, ids — записи, source — откуда их взяли.
• accept-files — узел принимает файлы с компьютера; приходит sf-tree-files-drop с {value, files}.

Доступность

• Дереву нужно доступное имя: aria-label на <sf-tree>.
• Дерево — одна остановка Tab. Стрелки вверх и вниз переходят по видимым пунктам, Home и End — к первому и последнему. Стрелка вправо раскрывает ветвь, а у раскрытой переходит к первому вложенному пункту; стрелка влево сворачивает ветвь или переходит к родителю. Набор букв переводит фокус к пункту, подпись которого с них начинается.
• Enter раскрывает и сворачивает ветвь, а на пункте без вложенных открывает его ссылку; Space выбирает пункт при selection="single" или multiple. Фокус и выбор независимы: стрелки двигают фокус, не меняя выбор.
• Кнопка раскрытия ветви по умолчанию подписана по-английски. На русской странице задавайте пунктам с вложенными open-label и close-label, как в примерах.
• При выборе пункты сообщают aria-selected, а при selection="multiple" дерево сообщает и aria-multiselectable.

Справочник API

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

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

Атрибуты

• template — string, по умолчанию default.
• root-class — string, по умолчанию пусто.
• aria-label — string, по умолчанию пусто.
• role — string, по умолчанию tree, значения: tree.
• selection — string, по умолчанию none, значения: none, single, multiple.
• items — array из object, по умолчанию []. Пункты, заданные данными вместо дочерних sf-tree-item (задаётся как свойство, а не атрибут): [{label, href?, target?, rel?, kind?, value?, open?, selected?, active?, disabled?, icon?, openIcon?, closedIcon?, chevronOpenIcon?, chevronClosedIcon?, openLabel?, closeLabel?, children?}]. text или title заменяют label. Установка заменяет пункты и перерисовывает дерево; дочерние sf-tree-item читаются один раз и удаляются, поэтому родитель, который перерисовывает изменённые пункты, передаёт их этим способом.
• accept-records — boolean, по умолчанию false. Узел принимает записи, перетащенные из списка (application/x-sf-records+json), и сообщает об этом событием sf-tree-records-drop.
• accept-files — boolean, по умолчанию false. Узел принимает файлы, перетащенные с компьютера, и сообщает об этом событием sf-tree-files-drop.

Методы

• onToggle(handler: function, options?: object|boolean) — возвращает object. Добавляет обработчик sf-tree-item-toggle от любого пункта дерева; обработчик вызывается с (item, detail, event).

События

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

• sf-tree-selection-change — detail: { component: object, tagName: string, template: string, item: object, selected: boolean, value: string }. Запрошен или изменён выбор элемента дерева.
• sf-tree-records-drop — detail не описан. На узел отпустили записи, перетащенные из списка: {value, ids, source}. Дерево ничего не перемещает.
• sf-tree-files-drop — detail не описан. На узел отпустили файлы с компьютера: {value, files}. Дерево ничего не загружает.

Доступность

• Роль: дерево (tree).
• Доступное имя: обязательно.
• Клавиши: Tab, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, Enter, Space, поиск по первым буквам.
• Фокус: В порядке табуляции страницы находится один видимый элемент дерева; стрелки перемещают перемещаемый фокус независимо от выделения.

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

<sf-tree></sf-tree>

Источник

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

См. также

• Tree Item — атрибуты одного пункта.
• Breadcrumbs — путь к текущей странице.