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

Если введен поисковый запрос — в дереве показываются только элементы:
Текст, совпавший с поисковым запросом в названии элемента, выделяется жирным.
Может быть одиночный или множественный выбор (ограничивается на уровне дерева).
Элемент можно выбрать, нажав на него (в любую область, кроме иконки «Развернуть» («Свернуть») и кнопки доп. действий). Чтобы выбрать несколько элементов мышью, используются клавиши Ctrl или Shift, чтобы выбрать несколько элементов с клавиатуры — клавиша Space.
Нелистовые элементы можно разворачивать и сворачивать по клику на иконку «стрелка».
Если в древовидном списке включены чекбоксы, то выбор нескольких элементов возможен через клик на чекбокс.
Режим задаётся через multiple: checkbox или keyboard для множественного выбора. Одиночный выбор —
режим по умолчанию, поэтому просить о нём нужно отсутствием атрибута. Это обычный input, поэтому [multiple] можно связать и менять в любой момент. Если было
выбрано несколько узлов, при переходе к одиночному выбору остаётся первый выбранный, а укороченное значение
уходит в форму; при одиночном выборе значение приходит скаляром, при множественном — массивом, поэтому смена
режима меняет форму значения в форм-контроле. Дерево внутри kbq-tree-select делит модель выбора с
селектом, поэтому число выбираемых узлов задаёт селект: переключение дерева между одиночным и множественным
выбором там бросает исключение, а переключение между checkbox и keyboard разрешено.
Это касается только kbq-tree-selection и kbq-list-selection. У Select и
kbq-tree-select свойство multiple по-прежнему нельзя менять после инициализации — будет исключение.
Иногда может присутствовать кнопка дополнительных действий над элементом.
Есть несколько вариантов множественного выбора элементов. См. в примерах.
Дерево запоминает, какие узлы были раскрыты, и восстанавливает состояние после перезагрузки страницы. Включено по умолчанию — используйте [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 контрола только он позволяет
переиспользовать строки.