import {List} from '@gravity-ui/uikit';
§ItemsHeight
Определяет высоту списка элементов (или функцию, возвращающую значение высоты для списка). Данное свойство может быть полезным, когда высота списка задается динамически, например,(items: []) => number
.
§Items
Передает массив элементов для списка:
<List items={["one", "two", "three", "four", "five", "six", "seven"]} itemsHeight={160} />
Элемент может быть представлен скалярным или произвольным значением (при этом он всегда должен быть truthy
).
В случае произвольного значения обязательно указывайте функции фильтрации и рендеринга.
Рендеринг по умолчанию передает элемент только как текст.
Специальное поле item.disabled
делает элемент неактивным.
Настройка рендеринга и высоты открывает множество возможностей для экспериментов. Например, код ниже позволяет эмулировать группы:
<List items={[{title: 'one', group: true,disabled: true}, {title: 'two'},
{
title: 'three',
group: true,
disabled: true,
},
{
title: 'four',
},
]} onItemClick={(value) => console.log(value)}
renderItem={(item) => {
if (item.group) {
return (
<div className={'group'}>
<div className={'select-text'}>{item.title}</div>
</div>
);
}
return (
<div className={'select'}>
<div className={'select-text'}>{item.title}</div>
</div>
);
}}
itemHeight={(item) => (item.group ? 24 : 36)}
itemsHeight={160}
filterItem={(filter) => (item) => item.title.includes(filter)}
/>
§Filterable
Свойство filterable
отключает возможность ввода для поиска элемента, если его значение — false
. Значение по умолчанию — true
.
<List items={["one", "two", "three", "four", "five", "six", "seven"]} itemsHeight={160} filterable={false} />
§Sortable
Свойство sortable
позволяет менять местами элементы списка, если его значение — true
. Значение по умолчанию — false
.
<List items={["one", "two", "three", "four", "five", "six", "seven"]} itemsHeight={160} sortable={true} />
§Виртуализация
Чтобы виртуализация работала, нужно выполнить одно из двух условий:
- Задать свойство
itemsHeight
. В этом случае высота списка будет фиксированной и равной указанному значению. - Задать родительскому контейнеру списка стиль
display: flex
. В этом случае список будет подстраиваться под ширину контейнера.
§Внешнее управление
Иногда может потребоваться управлять действиями элементов с клавиатуры, сохраняя фокус на внешнем элементе.
В этом случае можно использовать передачу события onKeyDown
в список.
Аналогичным образом можно передать onFocus
и onBlur
, если нужно воспроизвести поведение при потере активного элемента.
§Filter
Свойство filter
позволяет задать значение фильтра, используемое для внешней сортировки.
§PropTypes
Имя | Описание | Тип | Значение по умолчанию |
---|---|---|---|
items | Список элементов | Array | [] |
itemHeight | Высота элемента в px или функция, возвращающая значение высоты для элемента: (item: any) => number . | Number/Function | 28 |
itemsHeight | Высота списка элементов или функция, возвращающая значение высоты для списка. Данное свойство может быть полезным, когда высота списка задается динамически: (items: []) => number . | Number/Function | |
renderItem | Функция рендеринга, получающая на вход элемент и возвращающая узел React: (item: any, isItemActive: bool, itemIndex: number) => React.ReactNode . | Function | |
filterItem | Функция фильтрации, которая принимает введенную строку в инпут поиска/фильтрации и возвращает функцию, принимающую на вход элемент и возвращающую булевое значение: (filter: string) => (item: any) => boolean . | Function | |
filterable | Флаг, активирующий поле фильтра. | Boolean | true |
filterPlaceholder | Заглушка для поля фильтра. | String | |
filter | Значение фильтра (при использовании внешней сортировки). | String | |
filterClassName | Класс для стилизации ввода фильтра. | String | |
onChangeFilter | Обработчик изменения фильтра (при использовании внешней сортировки): (filter: string) => void . | Function | |
onFilterEnd | Функция, вызываемая после завершения внутренней фильтрации: ({items}: {items: T[]}) => void . | Function | |
emptyPlaceholder | Заглушка для пустого списка. | React.ReactNode | |
sortable | Флаг, включающий сортировку списка. | Boolean | |
sortHandleAlign | Выравнивание индикатора сортировки (слева или справа). | left right | |
onSortEnd | Обработчик события сортировки — ({oldIndex: number, newIndex: number}) => void . | Function | |
virtualized | Флаг, включающий виртуализацию. При выключенном флаге будут отрисованы все элементы сразу. | Boolean | true |
onItemClick | Обработчик клика по элементу — (item: any, index: number, fromKeyboard?: bool) => void . | Function | |
deactivateOnLeave | При выставленном флаге выбор элемента сбрасывается при уходе курсора с элемента или потере фокуса списком. При снятом — последний выбранный элемент будет оставаться выбранным. | Boolean | true |
activeItemIndex | При заданном значении элемент с этим индексом рендерится как активный. | Number | |
selectedItemIndex | При заданном значении элемент с этим индексом рендерится как выбранный (цвет фона из --g-color-base-selection ). | Number/Array | |
itemClassName | Пользовательское имя класса, которое будет добавлено в контейнер элемента. | String | |
itemsClassName | Пользовательское имя класса, которое будет добавлено в список элементов. | String | |
role | HTML-атрибут role . | String | list |
id | HTML-атрибут id . | string | |
onChangeActive | Вызывается при изменении индекса варианта в списке, который выделен клавиатурным фокусом: (index?: number) => void . | Function |