Таблица с настройкой видимости колонок.
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';
Создаёт контекст для таблицы и виджета настройки колонок.
-
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
- необязательное, масив объектов, используется для вывода данных в футере таблицы.
Дропдаун с настройками видимости колонок.
-
setColumnsState
- обязательное, функция, обработчик изменения выключенных колонок; -
minColumnsNumber
- необязательное, минимальное количество листовых колонок, которое должно показываться на экране, по-умолчанию2
; -
searchPlaceholder
- необязательное, строка, плейсхолдер поля поиска в дропдауне, по-умолчанию"Поиск"
; -
buttonText
- необязательное, строка, текст кнопки-дропдауна настроек, по-умолчанию"Настройка колонок"
; -
hasSearch
- необязательное, булево, доступен ли поиск по колонкам, по-умолчаниюtrue
; -
canCheckAll
- необязательное, булево, доступна ли опция выключения/включения всех колонок, по-умолчаниюtrue
; -
checkAllText
- необязательное, строка, текст чекбокса выключения/включения всех колонок, по-умолчанию"Все"
; -
placement
- необязательное, строка, положение popper-элемента, по-умолчанию "bottom-end". Список возможных вариантов; -
popperStyle
- необязательное, объект, дополнительные стили popper-компонента; -
offsetDistance
- необязательное, число, расстояние от дропдауна до кнопки; -
className
- внутенний класс, который должен быть присвоен корневому dom-елементу; -
settingsToggleButtonId
- необязательное, строка, id кнопки настройки колонок.
Компонент, строящий таблицу по настройкам колонок и их видимости.
-
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
.
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
.
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,
}}
/>
Рекомендуется только для написания сторонних библиотек.
import { Table } from '@n3/react-configurable-table';
Аналогично TableConsumer
, но требуется вручную передать параметры columns
, rootIds
, disabledColumns
, data
и headData
.
-
columns
- аналогичноTableProvider
; -
rootIds
- аналогичноTableProvider
; -
data
- аналогичноTableProvider
; -
headData
- аналогичноTableProvider
; -
disabledColumns
- текущее состояние выключенных колонок.
import { SettingsDropdown } from '@n3/react-configurable-table';
Аналогично SettingsConsumer
, но требуется вручную передать параметры columns
, rootIds
, disabledColumns
и setColumnsState
.
-
columns
- аналогичноTableProvider
; -
rootIds
- аналогичноTableProvider
; -
disabledColumns
- текущее состояние выключенных колонок; -
setColumnsState
- обязательное, функция, вызывается при изменении видимости колонок, первым аргументом принимает новое значениеdisabledColumns
.
Хук, возвращающий параметры:
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>
Утилита для получения плоского списка листовых колонок.
import { getLeafColumnsIds } from ' @n3/react-configurable-table';
const leafColumnsIds = getLeafColumnsIds(columns, rootIds);
Репозиторий использует стабильную версию yarn.
-
yarn build
- сборка; -
yarn clean
- удалить все собранне файлы; -
yarn test
- валидация кода; -
yarn start
- запуск storybook с примерами.