@n3/react-full-table

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

Установка

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

или

`
yarn add @n3/react-full-table
`

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

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

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

columns={columns}
rootIds={rootIds}
loadItems={loadItems}
/>
`

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

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

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.

$3

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

columns={columns}
rootIds={rootIds}
loadItems={loadItems}
/>
`

$3

#### actions

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

`javascript
{
type: 'actions',

actions: [
{
renderIcon: () => ,
handler: (row) => {},
getProps: (row) => ({}),
},
],
}
`

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

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

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

#### anchor

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

`javascript
{
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. Колонка должна принять следующие параметры:

`javascript
{
type: 'tag',

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

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

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

#### date

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

`javascript
{
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

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

`javascript
{
type: 'number',

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

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

$3

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

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

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

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

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

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

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

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

$3

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

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

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