List

Maintainer:
korvin89
GitHub
filterable
sortable
filterPlaceholder
emptyPlaceholder
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} />

Виртуализация

Чтобы виртуализация работала, нужно выполнить одно из двух условий:

  1. Задать свойство itemsHeight. В этом случае высота списка будет фиксированной и равной указанному значению.
  2. Задать родительскому контейнеру списка стиль display: flex. В этом случае список будет подстраиваться под ширину контейнера.

Внешнее управление

Иногда может потребоваться управлять действиями элементов с клавиатуры, сохраняя фокус на внешнем элементе. В этом случае можно использовать передачу события onKeyDown в список. Аналогичным образом можно передать onFocus и onBlur, если нужно воспроизвести поведение при потере активного элемента.

Filter

Свойство filter позволяет задать значение фильтра, используемое для внешней сортировки.

PropTypes

ИмяОписаниеТипЗначение по умолчанию
itemsСписок элементовArray[]
itemHeightВысота элемента в px или функция, возвращающая значение высоты для элемента: (item: any) => number.Number/Function28
itemsHeightВысота списка элементов или функция, возвращающая значение высоты для списка. Данное свойство может быть полезным, когда высота списка задается динамически: (items: []) => number.Number/Function
renderItemФункция рендеринга, получающая на вход элемент и возвращающая узел React: (item: any, isItemActive: bool, itemIndex: number) => React.ReactNode.Function
filterItemФункция фильтрации, которая принимает введенную строку в инпут поиска/фильтрации и возвращает функцию, принимающую на вход элемент и возвращающую булевое значение: (filter: string) => (item: any) => boolean.Function
filterableФлаг, активирующий поле фильтра.Booleantrue
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Флаг, включающий виртуализацию. При выключенном флаге будут отрисованы все элементы сразу.Booleantrue
onItemClickОбработчик клика по элементу — (item: any, index: number, fromKeyboard?: bool) => void.Function
deactivateOnLeaveПри выставленном флаге выбор элемента сбрасывается при уходе курсора с элемента или потере фокуса списком. При снятом — последний выбранный элемент будет оставаться выбранным.Booleantrue
activeItemIndexПри заданном значении элемент с этим индексом рендерится как активный.Number
selectedItemIndexПри заданном значении элемент с этим индексом рендерится как выбранный (цвет фона из --g-color-base-selection).Number/Array
itemClassNameПользовательское имя класса, которое будет добавлено в контейнер элемента.String
itemsClassNameПользовательское имя класса, которое будет добавлено в список элементов.String
roleHTML-атрибут role.Stringlist
idHTML-атрибут id.string
onChangeActiveВызывается при изменении индекса варианта в списке, который выделен клавиатурным фокусом: (index?: number) => void.Function