npm package: @n3/react-full-table
Description: Table with configurable columns, fixed headers, footers and scrollbars, filters and sorting switchers in columns for react applications based on @n3/kit
Latest version: 0.17.3

# @n3/react-full-table

Таблица с настройкой видимости колонок, фиксацией шапки, футера и скроллбара, фильтрами и переключателями сортировки в колонках для реакт-приложениях на базе @n3/kit. Базируется на [@n3/react-configurable-table](https://gitlab.develop.netrika.ru/web/frontend/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';

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

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

```javascript
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](https://www.npmjs.com/package/@n3/react-filters), они будут добавлены к стандартным фильтрам из [@n3/react-filters-kit](https://www.npmjs.com/package/@n3/react-filters-kit);

- `filterData` - `filterData` компонента [@n3/react-filters](https://www.npmjs.com/package/@n3/react-filters);

- `filterLabelKey` - `labelKey` компонента [@n3/react-filters](https://www.npmjs.com/package/@n3/react-filters);

- `filterTypeKey` - `typeKey` компонента [@n3/react-filters](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@n3/filters-utils), и представляется объектом вида:

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

    - `columnId` - строка, id колонки;
    - `filterData` - из объекта колонки;
    - `filters` - текущие значения фильтров;
    - `setAndApplyFilter` - функция применения значения фильтра. Аргументы:

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

  - `getNames`: Function - необязательная, смотри [@n3/filters-utils](https://www.npmjs.com/package/@n3/filters-utils);

  - `serializeValues`: Function - необязательная, смотри [@n3/filters-utils](https://www.npmjs.com/package/@n3/filters-utils);

  - `checkCanReset`: Function - необязательная, смотри [@n3/filters-utils](https://www.npmjs.com/package/@n3/filters-utils);

  - `parseValues`: Function - необязательная, смотри [@n3/filters-utils](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@n3/react-fixedtable) от верхнего края экрана, по умолчанию 0;

- `bottom` - необязательное, число, отступ фиксированных футеров [@n3/react-fixedtable](https://www.npmjs.com/package/@n3/react-fixedtable) от нижнего края экрана, по умолчанию 0;

- `fixedLeftCols` - необязательное, число, количество колонок слева, которые будут зафиксированы при горизонтальном скролле таблицы [@n3/react-fixedtable](https://www.npmjs.com/package/@n3/react-fixedtable), по умолчанию 0;

- `updateUniqs` - необязательное, массив, используется для обновления фиксированных заголовков [@n3/react-fixedtable](https://www.npmjs.com/package/@n3/react-fixedtable);

- `getScrollableWrapper` - необязательное, функция, используется для поиска родительского элемента со скроллом ([@n3/react-fixedtable](https://www.npmjs.com/package/@n3/react-fixedtable));

- `isAdaptive` - необязательное, булево, смотри [@n3/react-filters](https://www.npmjs.com/package/@n3/react-filters);

- `fastFiltersNumber` - необязательное, число, смотри [@n3/react-filters](https://www.npmjs.com/package/@n3/react-filters);

- `filtersBlockComponent` - необязательное, react-компонент, смотри [@n3/react-filters](https://www.npmjs.com/package/@n3/react-filters);

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

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

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

  - **isListInited** - смотри [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist);

  - **listState** - смотри [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist);

  - **listActions** - смотри [react-filterlist](https://www.npmjs.com/package/@vtaits/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](https://www.npmjs.com/package/@vtaits/filterlist), но принимает вторым аргументом объект `{ serializedValues: {...} }`, где `serializedValues` - сериализованные значения фильтров и сортировки. Поля объекта `additional`:

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

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

- **onChangeLoadParams** - аналогично функции **onChangeLoadParams** из [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist), но принимает вторым аргументом объект `{ serializedValues: {...} }`, где `serializedValues` - сериализованные значения фильтров и сортировки;

- **parseFiltersAndSort** - аналогично функции **parseFiltersAndSort** из [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist), но принимает вторым аргументом объект `{ parseValues, parseSortFromValues }`:

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

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

- **otherFilterlistProps** - остальные параметры [react-filterlist](https://www.npmjs.com/package/@vtaits/react-filterlist) за исключением `isRecountAsync`, оно всегда `true`.

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

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

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

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

#### actions

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

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

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

```javascript
{
  type: 'anchor',

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

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

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

Для рендера контента можно использовать функция `renderCell` из [@n3/react-configurable-table](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/pretty-num).

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

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

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

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

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

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

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