@n3/react-full-table

Таблица с настройкой видимости колонок, фиксацией шапки, футера и скроллбара, фильтрами и переключателями сортировки в колонках для реакт-приложениях на базе @n3/kit. Базируется на @n3/react-configurable-table.

Установка

npm install @n3/react-full-table --save

или

yarn add @n3/react-full-table

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

На минималках:

import { FullTable } from '@n3/react-full-table';

<FullTable
  columns={columns}
  rootIds={rootIds}
  loadItems={loadItems}
/>

На максималках:

import { FullTable } from '@n3/react-full-table';

<FullTable
  filters={filters}
  filterData={filterData}
  filterLabelKey={filterLabelKey}
  filterTypeKey={filterTypeKey}
  columns={columns}
  rootIds={rootIds}
  columnFilterTypes={columnFilterTypes}
  disabledColumns={disabledColumns}
  onDisabledColumnsChange={onDisabledColumnsChange}
  perPageFilterName={perPageFilterName}
  pageFilterName={pageFilterName}
  placeholder={placeholder}
  perPage={perPage}
  canChangePage={canChangePage}
  canChangePerPage={canChangePerPage}
  perPageOptions={perPageOptions}
  initialPerPage={initialPerPage}
  top={top}
  bottom={bottom}
  fixedLeftCols={fixedLeftCols}
  updateUniqs={updateUniqs}
  getScrollableWrapper={getScrollableWrapper}
  isAdaptive={isAdaptive}
  fastFiltersNumber={fastFiltersNumber}
  filtersBlockComponent={filtersBlockComponent}
  minColumnsNumber={minColumnsNumber}
  getDownloadUrl={getDownloadUrl}
  getDownloadName={getDownloadName}
  loadItems={loadItems}
  parseFiltersAndSort={parseFiltersAndSort}
  onChangeLoadParams={onChangeLoadParams}
  sortParamName={sortParamName}
  parseSort={parseSort}
  serializeSort={serializeSort}
  headData={headData}
  filtersWrapperId={filtersWrapperId}
  filtersToggleButtonId={filtersToggleButtonId}
  paginatorWrapperId={paginatorWrapperId}
  topPageSizeToggleButtonId={topPageSizeToggleButtonId}
  topPageSizeToggleButtonWrapperId={topPageSizeToggleButtonWrapperId}
  bottomPageSizeToggleButtonId={bottomPageSizeToggleButtonId}
  bottomPageSizeToggleButtonWrapperId={bottomPageSizeToggleButtonWrapperId}
  settingsToggleButtonId={settingsToggleButtonId}
  {...otherFilterlistProps}
/>

• filters - filters компонента @n3/react-filters, они будут добавлены к стандартным фильтрам из @n3/react-filters-kit;

• filterData - filterData компонента @n3/react-filters;

• filterLabelKey - labelKey компонента @n3/react-filters;

• filterTypeKey - typeKey компонента @n3/react-filters;

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

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

  • number - необязательное, ReactNode, номер колонки;

  • type - необязательное, строка, используется для задания кастомной функции рендера ячеек данной колонки через bodyCellRenderers. Аналогично @n3/react-configurable-table, но есть встроенные визуализаторы (см. ниже);

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

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

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

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

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

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

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

  • hasSort - необязательное, булево, если установлено значение false, у колонки нет переключателя сортировки;

  • filterData - необязательное, объект, дополнительные параметры компонента фильтра. Специальные параметры

    • filterName - необязательное, строка, поле, по которому будет проводиться фильтрация, если нужно фильтровать не по id колонки;

  • filterType - необязательное, строка, тип фильтра колонки по ключу из columnFilterTypes или одного из встроенных типов:

    • input - текстовый фильтр, базируется на Input из @n3/kit, можно задать дополнительные свойства через filterData;

    • search - текстовый фильтр, базируется на SearchInput из @n3/kit, можно задать дополнительные свойства через filterData;

  • filterComponent - необязательное, react-компонент, компонент, отображаемый в шапке колонки. Props:

    • columnId - строка, id колонки;

    • filterProps - объект, смотри выше;

    • filters - текущие значения фильтров;

    • setAndApplyFilter - функция применения значения фильтра. Аргументы:

      1. columnId - из props;
      2. value - значение фильтра;

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

• columnFilterTypes - необязательное, объект описаний фильтров формата @n3/filters-utils, и представляется объектом вида:

  • component - react-компонент фильтра. Принимает следующие props:

    • columnId - строка, id колонки;

    • filterData - из объекта колонки;

    • filters - текущие значения фильтров;

    • setAndApplyFilter - функция применения значения фильтра. Аргументы:

      1. columnId - из props;
      2. value - значение фильтра;

  • getNames: Function - необязательная, смотри @n3/filters-utils;

  • serializeValues: Function - необязательная, смотри @n3/filters-utils;

  • checkCanReset: Function - необязательная, смотри @n3/filters-utils;

  • parseValues: Function - необязательная, смотри @n3/filters-utils;

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

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

• perPageFilterName - необязательное, строка, используется для вывода пагинатора, когда не задано perPage, название фильтра, отвечающее за количество элементов, отображаемых на странице, по умолчанию per_page;

• pageFilterName - необязательное, строка, используется для вывода пагинатора, название фильтра, отвечающее за номер страницы, по умолчанию page;

• placeholder - необязательное, строка, текст сообщения, которое выводится, когда данных нет;

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

• canChangePage - необязательное, булево, будет ли выведен пагинатор, по умолчанию true;

• canChangePerPage - необязательное, булево, будет ли выведен селект количества элементов на страницу, если количество элементов задаётся через perPageFilterName, по умолчанию true;

• perPageOptions - необязательное, массив чисел, опции селекта количества элементов на страницу, по умолчанию [10, 20, 50];

• initialPerPage - необязательное, количество элементов на страницу по умолчанию, если не определено, используется первый элемент perPageOptions;

• top - необязательное, число, отступ фиксированных заголовков @n3/react-fixedtable от верхнего края экрана, по умолчанию 0;

• bottom - необязательное, число, отступ фиксированных футеров @n3/react-fixedtable от нижнего края экрана, по умолчанию 0;

• fixedLeftCols - необязательное, число, количество колонок слева, которые будут зафиксированы при горизонтальном скролле таблицы @n3/react-fixedtable, по умолчанию 0;

• updateUniqs - необязательное, массив, используется для обновления фиксированных заголовков @n3/react-fixedtable;

• getScrollableWrapper - необязательное, функция, используется для поиска родительского элемента со скроллом (@n3/react-fixedtable);

• isAdaptive - необязательное, булево, смотри @n3/react-filters;

• fastFiltersNumber - необязательное, число, смотри @n3/react-filters;

• filtersBlockComponent - необязательное, react-компонент, смотри @n3/react-filters;

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

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

• getDownloadUrl - необязательное, функция генерации url для экспорта, принимает первым аргументом объект, содержащий свойства:

  • isListInited - смотри react-filterlist;

  • listState - смотри react-filterlist;

  • listActions - смотри react-filterlist;

  • serializeValues - функция сериализации применённых фильтров;

• getDownloadName - необязательное, функция генерации имени файла для экспорта, аргументы аналогичны getDownloadUrl;

• sortParamName - необязательное, строка, ключ, по которому состяние сортировки передаётся на сервер, по умолчанию 'o';

• parseSort - необязальное, функция парсинга сортировки, должна вернуть сортировку в формате @vtaits/filterlist, принимает аргументы:

  • sortParamName - строка, параметр таблицы;

  • values - объект значений;

• serializeSort - необязальное, функция сериализации сортировки, должна вернуть объект сериализованных значений, принимает аргументы:

  • sortParamName - строка, параметр таблицы;

  • sort - сортировка в формате @vtaits/filterlist;

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

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

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

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

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

• filtersParams - необязательное, параметры инициализации @n3/react-filters-kit;

• getRowActions - небязательное, функция получения списка действий для строки в формате @n3/kit/TableActions, принимает аргументы:

  1. row - данные строки таблицы

  2. tableParams - параметры таблицы:

  • tableParams.filters - текущие значения фильтров;
  • tableParams.pageFilterName - параметр таблицы;
  • tableParams.data - данные текщуей страницы таблицы;
  • tableParams.setAndApplyFilter - функиция применения фильтра;

• filtersWrapperId - необязательное, строка, id dom-элемента корневого блока фильтров;

• filtersToggleButtonId - необязательное, строка, id dom-элемента кнопки раскрытия фильтров;

• paginatorWrapperId - необязательное, строка, id dom-элемента корневого элемента пагинтора;

• topPageSizeToggleButtonWrapperId - необязательное, строка, id обёртки dom-элемента кнопки изменения количества элементов на странице над таблицей;

• topPageSizeToggleButtonId - необязательное, строка, id dom-элемента кнопки изменения количества элементов на странице над таблицей;

• bottomPageSizeToggleButtonWrapperId - необязательное, строка, id обёртки dom-элемента кнопки изменения количества элементов на странице под таблицей;

• bottomPageSizeToggleButtonId - необязательное, строка, id dom-элемента кнопки изменения количества элементов на странице под таблицей;

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

• loadItems - аналогично функции loadItems из filterlist, но принимает вторым аргументом объект { serializedValues: {...} }, где serializedValues - сериализованные значения фильтров и сортировки. Поля объекта additional:

  • count - общее количество элементов;

  • footerData - массив строк футера;

• onChangeLoadParams - аналогично функции onChangeLoadParams из react-filterlist, но принимает вторым аргументом объект { serializedValues: {...} }, где serializedValues - сериализованные значения фильтров и сортировки;

• parseFiltersAndSort - аналогично функции parseFiltersAndSort из react-filterlist, но принимает вторым аргументом объект { parseValues, parseSortFromValues }:

  • parseValues - асинхронная функция парсинга значений фильтров, принимающая только один аргумент - объект значений;

  • parseSortFromValues - функция парсинга сортировки, принимающая только один аргумент - объект значений;

• otherFilterlistProps - остальные параметры react-filterlist за исключением isRecountAsync, оно всегда true.

Автоматическая синхронизация с адресной строкой (react-router-dom)

import { FullTableWithRouter } from '@n3/react-full-table';

<FullTableWithRouter
  columns={columns}
  rootIds={rootIds}
  loadItems={loadItems}
/>

Встроенные визуализаторы

actions

Выводит иконки-действия. Колонка должна принять следующие параметры:

{
  type: 'actions',

  actions: [
    {
      renderIcon: () => <i className="fa fa-cog" />,
      handler: (row) => {},
      getProps: (row) => ({}),
    },
  ],
}

actions - массив объектов, по каждому из которых строится иконка с действиями, используя FakeLink из @n3/kit. Параметры:

• renderIcon - обязательное, функция рендера иконки;
• handler - необязательное, функция обработчика клика по иконке. Может быть асинхронной. Первым аргументом принимает текущий элемент data. На время исполнения кнопка блокируется;
• getProps - необязательное, функция, собирающая дополнительные props компонента FakeLink. Первым аргументом принимает текущий элемент data.

Остальные параметры переходят в props FakeLink.

anchor

Выводит ссылку. Колонка должна принять следующие параметры:

{
  type: 'anchor',

  getHref: (row, columnId, column) => `/items/${row.id}/`,
  target: '_blank',
}

• getHref - обязательное, функция, используется для получения ссылки. Первым аргументом принимает текущий элемент data. Если возвращает null, будет отображено содержимое без ссылки;

• target - необязательное, строка, target ссылки,

Для рендера контента можно использовать функция renderCell из @n3/react-configurable-table, по умолчанию рендерит значение по ключю id колонки текущего элемента data.

link

Аналогично anchor, но использует Link из react-router-dom для рендера.

tag

Выводит тег из @n3/kit. Колонка должна принять следующие параметры:

{
  type: 'tag',

  getColor: (row, columnId, column) => row.active ? 'green' : 'red',
}

• getColor - обязательное, функция, используется для получения цвета тега. Первым аргументом принимает текущий элемент data. Если возвращает null, будет отображено содержимое без тега;

Для рендера контента можно использовать функция renderCell из @n3/react-configurable-table, по умолчанию рендерит значение по ключю id колонки текущего элемента data.

date

Выводит форматированную дату. Колонка должна принять следующие параметры:

{
  type: 'date',
  dateFormat: 'yyyy-LL-dd',
  getDate: (row, columnId, column) => '2021-01-27',
  parseDate: (row, columnId, column) => new Date(), // или null, если дата не определена
}

• parseDate - необязательное, функция, кастомная функция парсинга даты;
• dateFormat - необязательное, строка, входной формат даты, работает только в случае, если parseDate не определена;
• getDate - необязательное, функция, кастомная функция получения даты в виде строки, работает только в случае, если parseDate не определена.

datetime

Выводит форматированные дату и время. Формат аналогичен date.

number

Выводит форматированное число. Колонка должна принять следующие параметры:

{
  type: 'number',

  thousands: true,
  decimalScale: 4,
  params: {},
}

• thousands - необязательное, булево, делать ли разбиение по тысячам, по умолчанию false;
• precision - необязательное, число, количество знаков после запятой, по умолчанию 2;
• params - необязательное, объект, дополнительные параметры pretty-num.

Действия со строками

Редактирование строки

Базируется на компоненте Link из react-router-dom

import {
  FullTable,
  getEditRowAction,
} from '@n3/react-full-table';

<FullTable
  columns={columns}
  rootIds={rootIds}
  loadItems={loadItems}
  getRowAction={(row, tableParams) => [
    getEditRowAction({
      to: `/edit/${row.id}/`,
    }),
  ]}
/>

Удаление строки

Базируется на основе createRemoveTableAction из @n3/kit/createRemoveTableAction.

import {
  FullTable,
  getRemoveRowAction,
} from '@n3/react-full-table';

<FullTable
  columns={columns}
  rootIds={rootIds}
  loadItems={loadItems}
  getRowAction={(row, tableParams) => [
    getRemoveRowAction(tableParams, {}, {
      remove: async () => {
        // ...
      },
      approveTitle: 'Удаление проекта',
      approveContent: 'Восстановить проект будет невозможно.',
      approveButtonText: 'Удалить проект',
      cancelButtonText: 'Отменить',
      notification: {
        title: 'Успешно',
        content: 'Проект успешно удалён',
      },
    }),
  ]}
/>

Генерация id элементов

Можно использовать утилиту generateIds.

import {
  FullTable,
  generateIds,
} from '@n3/react-full-table';

<FullTable
  columns={columns}
  rootIds={rootIds}
  loadItems={loadItems}
  {...generateIds('myTable')}
/>