@n3/react-configurable-table

@n3/react-configurable-table

Таблица с настройкой видимости колонок.

Установка

npm install @n3/react-configurable-table styled-components --save

или

yarn add @n3/react-configurable-table styled-components

Использование

Для стандартного использования библиотека предоставляет три компонента: TableProvider, TableConsumer и SettingsConsumer.

import {
  TableProvider,
  TableConsumer,
  SettingsConsumer,
} from '@n3/react-configurable-table';

TableProvider

Создаёт контекст для таблицы и виджета настройки колонок.

props

• columns - обязательное, объект, ключами которого являются id колонок, а значениями - их параметры. Вид объект параметров:

  • title - необязательное, строка, выводится в шапке таблицы и пунктах меню настроек;

  • type - необязательное, строка, используется для задания кастомной функции рендера ячеек данной колонки через bodyCellRenderers;

  • childs - необязательное, массив строк, список id дочерних колонок. Если их нет, то колонка является листовой;

  • canDisable - необязательное, булево, может ли быть изменена видимость колонки, по-умолчанию true;

  • isFooterLeaf - необязательное, булево, является ли колонка листовой для футера;

  • payload - необязательное, объект, props каждой шапки и ячейки таблицы этого столбца;

  • thPayload - необязательное, объект, props каждой шапки таблицы этого столбца, перекрывает payload;

  • footerPayload - необязательное, объект, props каждой ячейки футера таблицы этого столбца, перекрывает payload;

  • tdPayload - необязательное, объект, props каждой ячейки таблицы этого столбца, перекрывает payload;

  • renderCell - необязательное, функция, используется для рендера контента ячейки, если не задан её type в bodyCellRenderers, принимает аргументы:

    • row - строка данных;

    • columnId - id колонки;

    • column - элемент объекта columns;

  • renderHeadCell - необязательное, функция, используется для рендера шапки таблицы, принимает аргументы:

    • columnId - id колонки;

    • column - элемент объекта columns;

  • renderFooterCell - необязательное, функция, используется для рендера футера таблицы, принимает аргументы:

    • row - строка данных footerData;

    • columnId - id колонки;

    • column - элемент объекта columns;

  • renderSettingsOption - необязательное, функция, используется для рендера пункта в меню настроек, принимает аргументы:

    • columnId - id колонки;

    • column - элемент объекта columns;

• rootIds - обязательное, список корневых колонок;

• disabledColumns - необязательное, выключенные колонки по умолчанию. Объект, ключами которого являются id листовых колонок, а значениями - выключена ли данная колонка. Если колонка не объявлена в данном объекте, значит, она не выключена;

• onDisabledColumnsChange - необязательное, функция, вызывается при изменении выключенных колонок. Первым аргументом принимает disabledColumns;

• data - обязательное, масив объектов, используется для вывода данных в теле таблицы. По умлочанию каждая листовая колонка берёт значение по ключу, являющемуся своим id, и выводит в td, может быть переопределено при помощи renderBodyCell или bodyCellRenderers (смотри ниже);

• headData - необязательное, масив объектов, используется для вывода данных в шапке таблицы при помощи renderHeadCell (смотри ниже);

• footerData - необязательное, масив объектов, используется для вывода данных в футере таблицы.

SettingsConsumer

Дропдаун с настройками видимости колонок.

props

• setColumnsState - обязательное, функция, обработчик изменения выключенных колонок;

• minColumnsNumber - необязательное, минимальное количество листовых колонок, которое должно показываться на экране, по-умолчанию 2;

• searchPlaceholder - необязательное, строка, плейсхолдер поля поиска в дропдауне, по-умолчанию "Поиск";

• buttonText - необязательное, строка, текст кнопки-дропдауна настроек, по-умолчанию "Настройка колонок";

• hasSearch - необязательное, булево, доступен ли поиск по колонкам, по-умолчанию true;

• canCheckAll - необязательное, булево, доступна ли опция выключения/включения всех колонок, по-умолчанию true;

• checkAllText - необязательное, строка, текст чекбокса выключения/включения всех колонок, по-умолчанию "Все";

• placement - необязательное, строка, положение popper-элемента, по-умолчанию "bottom-end". Список возможных вариантов;

• popperStyle - необязательное, объект, дополнительные стили popper-компонента;

• offsetDistance- необязательное, число, расстояние от дропдауна до кнопки;

• className - внутенний класс, который должен быть присвоен корневому dom-елементу;

• settingsToggleButtonId - необязательное, строка, id кнопки настройки колонок.

TableConsumer

Компонент, строящий таблицу по настройкам колонок и их видимости.

props

• renderHeadCell - необязательное, функция рендера элементов headData в th. Принимает аргументы row (элемент headData), columnId (id колонки) и column (элемент объекта columns). По умолчанию возвращает row[columnId];

• renderLeafHeadCell - необязательное, функция рендера листовых элементов columns в шапке. По умолчанию возвращает column.title. Принимает аргументы:

  • renderedTitle - тайтл колонки, полученный в результате вызова renderHeadCell, или column.title, если не определено renderHeadCell;

  • columnId (id колонки);

  • column (элемент объекта columns);

• shouldRenderHeadRow - необязательное, функция, определяющая, нужно ли отображать строку данных шапки. Принимает аргументы:

  • row - строка данных;

  • index - индекс строки в массиве;

  • visibleColumnsIds - массив id видимых колонок;

  • notDisabledColumnsIds - массив id не выключенных колонок;

• renderBodyCell - необязательное, функция рендера элементов data в теле таблицы. По умолчанию возвращает row[columnId]. Принимает аргументы:

  • row - строка данных;
  • columnId - id колонки;
  • column - элемент объекта columns;

• bodyCellRenderers - необязательное, объект, ключами которого являются type элементов объекта columns, а значениями - функции рендера ячеек колонки данного типа, аналогичные renderBodyCell. Если для данного type функция не определена, рендер производится через renderBodyCell;

• getBodyCellProps - необязательное, функция, собирающая дополнительные props компонента tdComponent. По умолачанию возвращает {}. Принимает аргументы:

  • row - строка данных;
  • columnId - id колонки;
  • column - элемент объекта columns;

• shouldRenderBodyRow - необязательное, функция, определяющая, нужно ли отображать строку данных. Принимает аргументы:

  • row - строка данных;

  • index - индекс строки в массиве;

  • visibleColumnsIds - массив id видимых колонок;

  • notDisabledColumnsIds - массив id не выключенных колонок;

• tableProps - необязательное, объект, дополнительные props table-компонента;

• tableComponent - необязательное, react-компонент, переопределённый table-компонент;

• trComponent - необязательное, react-компонент, переопределённый tr-компонент;

• theadComponent - необязательное, react-компонент, переопределённый thead-компонент;

• thComponent - необязательное, react-компонент, переопределённый th-компонент;

• tbodyComponent - необязательное, react-компонент, переопределённый tbody-компонент;

• tdComponent - необязательное, react-компонент, переопределённый td-компонент;

• tfootComponent - необязательное, react-компонент, переопределённый tfoot-компонент;

• renderRow - необязательное, функция рендера строк таблицы по строке данных. Рендерит элемент массива, поэтому свойство key обязательно для корневого узла. По умолчанию рендерит один trComponent с вложенными tdComponent. Примнимает первым аргументом объект следующих свойств:

  • trComponent - смотри выше;
  • row - строка данных;
  • index - номер элемента массива;
  • renderRow - для рекурсивного рендера;
  • renderCells - функция рендера ячеек по строке с учётом disabledColumns и кастомного рендера;

  Пример:

  const renderRow = ({
    trComponent: Tr,
    row,
    index,
    renderCells,
  }) => (
    <Tr key={index}>
      {renderCells(row)}
    </Tr>
  );
  

• maxColumnsLength - необязательное, число, максимальное количество колонок для рендера;

• isHeadTreeHidden - необязательное, булево, скрыть ли заголовки колонок в шапке, по-умолчанию false.

PropTypes

import {
  columnShape,
  columnsObjectOf,
  disabledColumnsObjectOf,
  basePropTypes,
  settingsDropdownPropTypes,
  bodyCellRenderersObjectOf,
  tablePropTypes,
} from '@n3/react-configurable-table';

• columnShape - объект параметров колонки;
• columnsObjectOf - объект columns (смотри выше);
• disabledColumnsObjectOf - объект disabledColumns (смотри выше);
• basePropTypes - базовые propPypes компоенентов Table и SettingsDropdown (содержит columns, disabledColumns и rootIds);
• settingsDropdownPropTypes - propPypes компоенента SettingsDropdown;
• bodyCellRenderersObjectOf - объект bodyCellRenderers (смотри выше);
• tablePropTypes - propPypes компонента Table.

Flow

import type {
  ColumnType,
  ColumnsObjectType,
  DisabledColumnsType,
  BasePropsType,
  SettingsDropdownPropsType,
  TablePropsType,
} from '@n3/react-configurable-table';

• ColumnType - параметры колонки;
• ColumnsObjectType - объект columns (смотри выше);
• DisabledColumnsType - объект disabledColumns (смотри выше);
• BasePropsType - базовые props компоенентов Table и SettingsDropdown (содержит columns, disabledColumns и rootIds);
• SettingsDropdownPropsType - props компоенента SettingsDropdown;
• BodyCellRenderersType - объект bodyCellRenderers (смотри выше);
• TablePropsType - props компонента Table.

Стилизация меню

Делается с помощью заменяемых компонентов.

import {
  SettingsConsumer,
} from '@n3/react-configurable-table';

...

<SettingsConsumer
  {...props}
  components={{
    Checkbox,
    DropdownButton,
    Popper,
    SearchInput,
    Settings,
    SettingsItem,
  }}
/>

Расширенное использование

Рекомендуется только для написания сторонних библиотек.

Table

import { Table } from '@n3/react-configurable-table';

Аналогично TableConsumer, но требуется вручную передать параметры columns, rootIds, disabledColumns, data и headData.

• columns - аналогично TableProvider;

• rootIds - аналогично TableProvider;

• data - аналогично TableProvider;

• headData - аналогично TableProvider;

• disabledColumns - текущее состояние выключенных колонок.

SettingsDropdown

import { SettingsDropdown } from '@n3/react-configurable-table';

Аналогично SettingsConsumer, но требуется вручную передать параметры columns, rootIds, disabledColumns и setColumnsState.

• columns - аналогично TableProvider;

• rootIds - аналогично TableProvider;

• disabledColumns - текущее состояние выключенных колонок;

• setColumnsState - обязательное, функция, вызывается при изменении видимости колонок, первым аргументом принимает новое значение disabledColumns.

useColumns

Хук, возвращающий параметры:

• columns
• data
• disabledColumns
• footerData
• headData
• rootIds
• setColumnsState

Использует контекст, созданный TableProvider.

import { TableProvider, withColumns } from '@n3/react-configurable-table';

...

const SomethingWithColumns = withColumns(Something);

...

<TableProvider
  columns={columns}
  rootIds={rootIds}
>
  <SomethingWithColumns />
</TableProvider>

getLeafColumnsIds

Утилита для получения плоского списка листовых колонок.

import { getLeafColumnsIds } from ' @n3/react-configurable-table';

const leafColumnsIds = getLeafColumnsIds(columns, rootIds);

Локальная разработка

Репозиторий использует стабильную версию yarn.

Инструкция по установке.

Команды

• yarn build - сборка;

• yarn clean - удалить все собранне файлы;

• yarn test - валидация кода;

• yarn start - запуск storybook с примерами.