Иерархический список (дерево) — древовидный каталог с большим количеством данных.

docs.apptests

Когда нужно обеспечить пользователю удобную работу с большим количеством данных (сотни элементов). При этом либо пользователь имеет возможность структурировать эти данные в древовидный каталог, либо данные уже приходят к нему в таком виде из системы. Если эти условия не соблюдаются, то лучше использовать обычный список.

  • Название
  • Иконки элемента (опционально)
  • Кнопка дополнительных действий над элементом (опционально)
  • Кнопки «Развернуть» и «Свернуть»
  • Чекбокс (опционально)
  • Поиск по элементам (опционально)
tree-select

Если введен поисковый запрос — в дереве показываются только элементы:

  • которые соответствуют поисковому запросу;
  • являются родительскими по отношению к найденным в поисковом запросе.

Текст, совпавший с поисковым запросом в названии элемента, выделяется жирным.

docs.apptests
docs.apptests

Может быть одиночный или множественный выбор (ограничивается на уровне дерева).

Элемент можно выбрать, нажав на него (в любую область, кроме иконки «Развернуть» («Свернуть») и кнопки доп. действий). Чтобы выбрать несколько элементов мышью, используются клавиши Ctrl или Shift, чтобы выбрать несколько элементов с клавиатуры — клавиша Space.

Нелистовые элементы можно разворачивать и сворачивать по клику на иконку «стрелка».

docs.apptests

Если в древовидном списке включены чекбоксы, то выбор нескольких элементов возможен через клик на чекбокс.

docs.apptests

Режим задаётся через multiple: checkbox или keyboard для множественного выбора. Одиночный выбор — режим по умолчанию, поэтому просить о нём нужно отсутствием атрибута. Это обычный input, поэтому [multiple] можно связать и менять в любой момент. Если было выбрано несколько узлов, при переходе к одиночному выбору остаётся первый выбранный, а укороченное значение уходит в форму; при одиночном выборе значение приходит скаляром, при множественном — массивом, поэтому смена режима меняет форму значения в форм-контроле. Дерево внутри kbq-tree-select делит модель выбора с селектом, поэтому число выбираемых узлов задаёт селект: переключение дерева между одиночным и множественным выбором там бросает исключение, а переключение между checkbox и keyboard разрешено.

Это касается только kbq-tree-selection и kbq-list-selection. У Select и kbq-tree-select свойство multiple по-прежнему нельзя менять после инициализации — будет исключение.

Иногда может присутствовать кнопка дополнительных действий над элементом.

docs.appbadge
testsbadge

Есть несколько вариантов множественного выбора элементов. См. в примерах.

Дерево запоминает, какие узлы были раскрыты, и восстанавливает состояние после перезагрузки страницы. Включено по умолчанию — используйте [useStateSaving]="false" для отключения у компонента.

Выделение не сохраняется: оно принадлежит форме, к которой привязано дерево.

Раскрытие сохраняется по значению, которое возвращает getValue для узла, поэтому значение должно быть строкой, стабильной между перезагрузками и уникальной в пределах дерева. У дерева на NestedTreeControl метода getValue нет, и оно не сохраняет ничего — как и дерево, отрисованное внутри оверлея, в том числе в kbq-tree-select.

Раскрытие, выполненное самим приложением — treeControl.expandAll() или прямая запись в expansionModel, — не сохраняется, пока не вызвать saveState(). Удалить сохранённое: clearSavedState().

Ключи, хранилище и срок жизни записи одинаковы у всех компонентов, которые сохраняются, — см. Сохранение состояния компонентов.

Клавиша
Действие
TabЕсли фокус установлен на предыдущем компоненте в таб-последовательности по отношению к дереву → Переход к первой строке дерева или к выделенной строке
Если фокус установлен на любом элементе дерева и у него нет доп. действий → Переход к следующему компоненту в таб-последовательности по отношению к дереву
Если фокус установлен на любом элементе дерева и у него есть доп. действия → Переход к первому доп. действию
Если фокус установлен на доп. действии элемента → Переход к следующему доп. действию (если оно есть), иначе переход к следующему компоненту в таб-последовательности по отношению к дереву
Shift + TabЕсли фокус установлен на любом элементе дерева → Переход к предыдущему компоненту в таб-последовательности по отношению к дереву
Если фокус установлен на следующем компоненте в таб-последовательности по отношению к дереву → Переход к первой строке дерева или к выделенной строке
→Если фокус установлен на закрытом нелистовом элементе → Раскрытие вложенных элементов этого элемента
Если фокус установлен на раскрытом нелистовом элементе → Переход к первому вложенному элементу
Если фокус установлен на листовом элементе → Ничего не происходит
←Если фокус установлен на раскрытом нелистовом элементе → Закрытие вложенных элементов этого элемента
Если фокус установлен на закрытом нелистовом элементе → Переход к родительскому элементу
Если фокус установлен на листовом элементе → Переход к родительскому элементу
Если фокус установлен на элементе верхнего уровня → Ничего не происходит
↵Если фокус установлен на элементе дерева → Запуск основного действия этого элемента
Если фокус установлен на элементе дерева с чекбоксом → Ничего не происходит
Если фокус установлен на доп. действии → применение этого доп. действия
SpaceЕсли фокус установлен на элементе дерева с чекбоксом → Выбрать этот элемент дерева (и все вложенные, если есть)
Если фокус установлен на элементе дерева → Ничего не происходит
Если фокус установлен на доп. действии → применение этого доп. действия
↑ ↓Если фокус установлен на элементе дерева → Переход к следующему (если элемент последний — ничего не происходит) / предыдущему элементу дерева (если элемент первый — ничего не происходит)
PgUpСместить фокус на самый нижний видимый элемент

Если текущий элемент — самый нижний видимый → Пролистать дерево вниз
Если текущий элемент — самый нижний в дереве → Ничего не происходит
PgDnСместить фокус на самый верхний видимый элемент

Если текущий элемент — самый верхний видимый → Пролистать дерево вверх
Если текущий элемент — самая верхний в дереве → Ничего не происходит
HomeСместить фокус на первый элемент дерева
EndСместить фокус на последний загруженный элемент дерева
Ctrl + кликПри клике по элементам дерева — множественный выбор строк
При клике в выбранный элемент — элемент перестает быть выбранным
Shift + ↓

Shift + ↑
Если фокус установлен на элементе дерева → Множественный выбор следующих / предыдущих элементов дерева (если строка первая или последняя — ничего не происходит)
Ctrl + CЕсли фокус установлен на элементах дерева → Копирование содержимого элементов
По умолчанию копируются названия элементов. Разделитель между элементами — перенос строки
Ctrl + AЕсли фокус установлен на любом элементе дерева → Выбрать все элементы дерева (включая незагруженные)
Печатные символыПереход к следующему элементу, название которого начинается с введённых символов. Несколько символов, набранных подряд, ищутся как одно слово

Дерево передаёт вспомогательным технологиям структуру, которую отрисовывает, поэтому скринридер сообщает уровень вложенности элемента и то, раскрыт ли он, выбран ли и отмечен ли.

  • Дерево — это role="tree", каждая строка — role="treeitem".
  • Табуляция останавливается на самом дереве, а строки остаются с tabindex="-1", но строка, на которую переходят стрелки, получает настоящий фокус и вдобавок сообщается через aria-activedescendant.
  • У строк-веток есть aria-expanded — в том числе при активном фильтре, который отключает стрелки раскрытия, но не превращает ветки в листья, — а у каждой строки есть aria-level.
  • Строки с чекбоксом сообщают aria-checked, в том числе mixed для частично выбранной ветки; строки без чекбокса — aria-selected.
  • Стрелки раскрытия скрыты от вспомогательных технологий: их состояние уже есть на строке, а управляют ими клавиши ← и →.
  • У дерева нет собственной видимой подписи, поэтому задайте ему доступное имя через aria-label или укажите в aria-labelledby элемент, который его подписывает. Дереву внутри kbq-tree-select не нужно ни то, ни другое — его подписывает сам селект.

Отрисовываются все раскрытые элементы, без виртуализации: закрытая ветка не стоит ничего, раскрытая — по строке DOM на элемент. Дерево, показывающее тысячи строк сразу, стоит держать закрытым или сужать данные поиском.

По умолчанию узлы отслеживаются по идентичности, поэтому источник данных, который пересоздаёт объекты узлов на каждой эмиссии — например, flattener, — пересоздаёт и все строки, а пересозданный узел снова оказывается закрытым. Задайте контролу дерева trackBy, возвращающий стабильный ключ узла: тогда узел раскрывается по этому ключу, а дерево переиспользует строку с тем же ключом между обновлениями данных. Сделайте это до того, как что-либо раскрыто, — свойством или в опциях, последнем аргументе FlatTreeControl и NestedTreeControl:

Тогда expansionModel хранит ключи, а не узлы, а типы дерева, его событий и источника данных получают ещё один параметр — тип ключа: KbqTreeSelection<FileFlatNode, string>, KbqTreeFlatDataSource<FileNode, FileFlatNode, string>.

Собственный input дерева trackBy — TrackByFunction от индекса и узла — переопределяет ключ, по которому переиспользуются строки; на раскрытие он не влияет. Без trackBy контрола только он позволяет переиспользовать строки.

Предложения по улучшению
Если вы нашли ошибку или хотите доработать статью, создайте запрос на GitHub.