react-data-grid-plus

基于 [adazzle/react-data-grid](GitHub - adazzle/react-data-grid: Feature-rich and customizable data grid React component) 修改的自定义版本。

Features

• React 18.0+ support
• Evergreen browsers and server-side rendering support
• Tree-shaking support and only one npm dependency to keep your bundles slim
• Great performance thanks to virtualization: columns and rows outside the viewport are not rendered
• Strictly typed with TypeScript
• Keyboard accessibility
• Light and dark mode support out of the box. The light or dark themes can be enforced using the rdg-light or rdg-dark classes.
• Frozen columns
• Column resizing
• Multi-column sorting
  • Click on a sortable column header to toggle between its ascending/descending sort order
  • Ctrl+Click / Meta+Click to sort an additional column
• Column spanning
• Column grouping
• Row selection
• Row grouping
• Summary rows
• Dynamic row heights
• No rows fallback
• Cell formatting
• Cell editing
• Cell copy / pasting
• Cell value dragging / filling
• Customizable Renderers
• Right-to-left (RTL) support. We recommend using Firefox as Chrome has a bug with frozen columns.

Links

• Examples website
  • Source code
• Changelog
• Contributing

Install

1npm install react-data-grid-plus

react-data-grid-plus is published as ECMAScript modules for evergreen browsers / bundlers, and CommonJS for server-side rendering / Jest.

Quick start

1import 'react-data-grid-plus/lib/styles.css';
2
3import DataGrid from 'react-data-grid-plus';
4
5const columns = [
6  { key: 'id', name: 'ID' },
7  { key: 'title', name: 'Title' }
8];
9
10const rows = [
11  { id: 0, title: 'Example' },
12  { id: 1, title: 'Demo' }
13];
14
15function App() {
16  return <DataGrid columns={columns} rows={rows} />;
17}

API

Components

<DataGrid />

DataGridProps

columns: readonly Column<R, SR>[]

See Column.

An array describing the grid's columns.

:warning: Passing a new columns array will trigger a re-render for the whole grid, avoid changing it as much as possible for optimal performance.

rows: readonly R[]

An array of rows, the rows data can be of any type.

topSummaryRows?: Maybe<readonly SR[]>

An optional array of summary rows, usually used to display total values for example. topSummaryRows are pinned at the top of the rows view and the vertical scroll bar will not scroll these rows.

bottomSummaryRows?: Maybe<readonly SR[]>

An optional array of summary rows, usually used to display total values for example. bottomSummaryRows are pinned at the bottom of the rows view and the vertical scroll bar will not scroll these rows.

rowKeyGetter?: Maybe<(row: R) => K>

A function returning a unique key/identifier per row. rowKeyGetter is required for row selection to work.

1import DataGrid from 'react-data-grid-plus';
2
3interface Row {
4  id: number;
5  name: string;
6}
7
8function rowKeyGetter(row: Row) {
9  return row.id;
10}
11
12function MyGrid() {
13  return <DataGrid columns={columns} rows={rows} rowKeyGetter={rowKeyGetter} />;
14}

:bulb: While optional, setting this prop is recommended for optimal performance as the returned value is used to set the key prop on the row elements.

onRowsChange?: Maybe<(rows: R[], data: RowsChangeData<R, SR>) => void>

A function receiving row updates. The first parameter is a new rows array with both the updated rows and the other untouched rows. The second parameter is an object with an indexes array highlighting which rows have changed by their index, and the column where the change happened.

1import { useState } from 'react';
2import DataGrid from 'react-data-grid-plus';
3
4function MyGrid() {
5  const [rows, setRows] = useState(initialRows);
6
7  return <DataGrid columns={columns} rows={rows} onRowsChange={setRows} />;
8}

rowHeight?: Maybe<number | ((row: R) => number)>

Default: 35 pixels

Either a number defining the height of row in pixels, or a function returning dynamic row heights.

headerRowHeight?: Maybe<number>

Default: 35 pixels

A number defining the height of the header row.

summaryRowHeight?: Maybe<number>

Default: 35 pixels

A number defining the height of summary rows.

selectedRows?: Maybe<ReadonlySet<K>>

A set of selected row keys. rowKeyGetter is required for row selection to work.

isRowSelectionDisabled?: Maybe<(row: NoInfer<R>) => boolean>

A function used to disable row selection on certain rows.

onSelectedRowsChange?: Maybe<(selectedRows: Set<K>) => void>

A function called when row selection is changed.

1import { useState } from 'react';
2import DataGrid, { SelectColumn } from 'react-data-grid-plus';
3
4const rows: readonly Rows[] = [...];
5
6const columns: readonly Column<Row>[] = [
7  SelectColumn,
8  // other columns
9];
10
11function MyGrid() {
12  const [selectedRows, setSelectedRows] = useState((): ReadonlySet<number> => new Set());
13
14  return (
15    <DataGrid
16      rowKeyGetter={rowKeyGetter}
17      columns={columns}
18      rows={rows}
19      selectedRows={selectedRows}
20      isRowSelectionDisabled={isRowSelectionDisabled}
21      onSelectedRowsChange={setSelectedRows}
22    />
23  );
24}
25
26function rowKeyGetter(row: Row) {
27  return row.id;
28}
29
30function isRowSelectionDisabled(row: Row) {
31  return !row.isActive;
32}

sortColumns?: Maybe<readonly SortColumn[]>

An array of sorted columns.

onSortColumnsChange?: Maybe<(sortColumns: SortColumn[]) => void>

A function called when sorting is changed

1import { useState } from 'react';
2import DataGrid, { SelectColumn } from 'react-data-grid-plus';
3
4const rows: readonly Rows[] = [...];
5
6const columns: readonly Column<Row>[] = [
7  {
8    key: 'name',
9    name: 'Name',
10    sortable: true
11  },
12  // other columns
13];
14
15function MyGrid() {
16  const [sortColumns, setSortColumns] = useState<readonly SortColumn[]>([]);
17
18  return (
19    <DataGrid
20      columns={columns}
21      rows={rows}
22      sortColumns={sortColumns}
23      onSortColumnsChange={setSortColumns}
24    />
25  );
26}

Grid can be sorted on multiple columns using ctrl (command) + click. To disable multiple column sorting, change the onSortColumnsChange function to

1onSortColumnsChange(sortColumns: SortColumn[]) {
2  setSortColumns(sortColumns.slice(-1));
3}

defaultColumnOptions?: Maybe<DefaultColumnOptions<R, SR>>

Column options that are applied to all the columns

1function MyGrid() {
2  return (
3    <DataGrid
4      columns={columns}
5      rows={rows}
6      defaultColumnOptions={{
7        minWidth: 100,
8        resizable: true,
9        sortable: true,
10        draggable: true
11      }}
12    />
13  );
14}

onFill?: Maybe<(event: FillEvent<R>) => R>

onCopy?: Maybe<(event: CopyEvent<R>) => void>

onPaste?: Maybe<(event: PasteEvent<R>) => R>

onCellClick?: Maybe<(args: CellClickArgs<R, SR>, event: CellMouseEvent) => void>

Triggered when a cell is clicked. The default behavior is to select the cell. Call preventGridDefault to prevent the default behavior

1function onCellClick(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
2  if (args.column.key === 'id') {
3    event.preventGridDefault();
4  }
5}
6
7<DataGrid rows={rows} columns={columns} onCellClick={onCellClick} />;

This event can be used to open cell editor on single click

1function onCellClick(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
2  if (args.column.key === 'id') {
3    event.preventGridDefault();
4    args.selectCell(true);
5  }
6}

Arguments:

args: CellClickArgs<R, SR>

• args.rowIdx: number - row index of the currently selected cell
• args.row: R - row object of the currently selected cell
• args.column: CalculatedColumn<TRow, TSummaryRow> - column object of the currently selected cell
• args.selectCell: (enableEditor?: boolean) => void - function to manually select the cell and optionally pass true to start editing

event extends React.MouseEvent<HTMLDivElement>

• event.preventGridDefault:: () => void
• event.isGridDefaultPrevented: boolean

onCellDoubleClick?: Maybe<(args: CellClickArgs<R, SR>, event: CellMouseEvent) => void>

Triggered when a cell is double clicked. The default behavior is to open the editor if the cell is editable. Call preventGridDefault to prevent the default behavior

1function onCellDoubleClick(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
2  if (args.column.key === 'id') {
3    event.preventGridDefault();
4  }
5}
6
7<DataGrid rows={rows} columns={columns} onCellDoubleClick={onCellDoubleClick} />;

onCellContextMenu?: Maybe<(args: CellClickArgs<R, SR>, event: CellMouseEvent) => void>

Triggered when a cell is right clicked. The default behavior is to select the cell. Call preventGridDefault to prevent the default behavior

1function onCellContextMenu(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
2  if (args.column.key === 'id') {
3    event.preventGridDefault();
4  }
5}
6
7<DataGrid rows={rows} columns={columns} onCellContextMenu={onCellContextMenu} />;

onCellKeyDown?: Maybe<(args: CellKeyDownArgs<R, SR>, event: CellKeyboardEvent) => void>

A function called when keydown event is triggered on a cell. This event can be used to customize cell navigation and editing behavior.

Examples

• Prevent editing on Enter

1function onCellKeyDown(args: CellKeyDownArgs<R, SR>, event: CellKeyboardEvent) {
2  if (args.mode === 'SELECT' && event.key === 'Enter') {
3    event.preventGridDefault();
4  }
5}

• Prevent navigation on Tab

1function onCellKeyDown(args: CellKeyDownArgs<R, SR>, event: CellKeyboardEvent) {
2  if (args.mode === 'SELECT' && event.key === 'Tab') {
3    event.preventGridDefault();
4  }
5}

Check more examples

onSelectedCellChange?: Maybe<(args: CellSelectArgs<R, SR>) => void>;

Triggered when the selected cell is changed.

Arguments:

• args.rowIdx: number - row index
• args.row: R - row object of the currently selected cell
• args.column: CalculatedColumn<TRow, TSummaryRow> - column object of the currently selected cell

onScroll?: Maybe<(event: React.UIEvent<HTMLDivElement>) => void>

A function called when the grid is scrolled.

onColumnResize?: Maybe<(column: CalculatedColumn<R, SR>, width: number) => void>

A function called when column is resized.

enableVirtualization?: Maybe<boolean>

Default: true

This prop can be used to disable virtualization.

renderers?: Maybe<Renderers<R, SR>>

This prop can be used to override the internal renderers. The prop accepts an object of type

1interface Renderers<TRow, TSummaryRow> {
2  renderCell?: Maybe<(key: Key, props: CellRendererProps<TRow, TSummaryRow>) => ReactNode>;
3  renderCheckbox?: Maybe<(props: RenderCheckboxProps) => ReactNode>;
4  renderRow?: Maybe<(key: Key, props: RenderRowProps<TRow, TSummaryRow>) => ReactNode>;
5  renderSortStatus?: Maybe<(props: RenderSortStatusProps) => ReactNode>;
6  noRowsFallback?: Maybe<ReactNode>;
7}

For example, the default <Row /> component can be wrapped via the renderRow prop to add context providers or tweak props

1import DataGrid, { RenderRowProps, Row } from 'react-data-grid-plus';
2
3function myRowRenderer(key: React.Key, props: RenderRowProps<Row>) {
4  return (
5    <MyContext.Provider key={key} value={123}>
6      <Row {...props} />
7    </MyContext.Provider>
8  );
9}
10
11function MyGrid() {
12  return <DataGrid columns={columns} rows={rows} renderers={{ renderRow: myRowRenderer }} />;
13}

:warning: To prevent all rows from being unmounted on re-renders, make sure to pass a static or memoized component to renderRow.

rowClass?: Maybe<(row: R, rowIdx: number) => Maybe<string>>

A function to add a class on the row

1import DataGrid from 'react-data-grid-plus';
2
3function MyGrid() {
4  return <DataGrid columns={columns} rows={rows} rowClass={rowClass} />;
5}
6
7function rowClass(row: Row, rowIdx: number) {
8  return rowIdx % 2 === 0 ? 'even' : 'odd';
9}

direction?: Maybe<'ltr' | 'rtl'>

This property sets the text direction of the grid, it defaults to 'ltr' (left-to-right). Setting direction to 'rtl' has the following effects:

• Columns flow from right to left
• Frozen columns are pinned on the right
• Column resize handle is shown on the left edge of the column
• Scrollbar is moved to the left

className?: string | undefined

custom classname

style?: CSSProperties | undefined

custom styles

'aria-label'?: string | undefined

The label of the grid. We recommend providing a label using aria-label or aria-labelledby

'aria-labelledby'?: string | undefined

The id of the element containing a label for the grid. We recommend providing a label using aria-label or aria-labelledby

'aria-description'?: string | undefined

'aria-describedby'?: string | undefined

If the grid has a caption or description, aria-describedby can be set on the grid element with a value referring to the element containing the description.

'data-testid'?: Maybe<string>

This prop can be used to add a testid for testing. We recommend using role and name to find the grid element

1function MyGrid() {
2  return <DataGrid aria-label="my-grid" columns={columns} rows={rows} />;
3}
4
5function MyGridTest() {
6  const grid = screen.getByRole('grid', { name: 'my-grid' });
7}

<TreeDataGrid />

TreeDataGrid is component built on top of DataGrid to add row grouping. This implements the Treegrid pattern. At the moment TreeDataGrid does not support onFill and isRowSelectionDisabled props

TreeDataGridProps

groupBy?: Maybe<readonly string[]>

rowGrouper?: Maybe<(rows: readonly R[], columnKey: string) => Record<string, readonly R[]>>

expandedGroupIds?: Maybe<ReadonlySet<unknown>>

onExpandedGroupIdsChange?: Maybe<(expandedGroupIds: Set<unknown>) => void>

<TextEditor />

Props

See RenderEditCellProps

<Row />

See renderers

Props

See RenderRowProps

The ref prop is supported.

<SortableHeaderCell />

Props

onSort: (ctrlClick: boolean) => void

sortDirection: SortDirection | undefined

priority: number | undefined

tabIndex: number

children: React.ReactNode

<ValueFormatter />

Props

See FormatterProps

<SelectCellFormatter />

Props

value: boolean

tabIndex: number

disabled?: boolean | undefined

onChange: (value: boolean, isShiftClick: boolean) => void

onClick?: MouseEventHandler<T> | undefined

'aria-label'?: string | undefined

'aria-labelledby'?: string | undefined

<ToggleGroupFormatter />

Props

See RenderGroupCellProps

Hooks

useHeaderRowSelection<R>(): { isIndeterminate, isRowSelected, onRowSelectionChange }

useRowSelection<R>(): { isRowSelectionDisabled, isRowSelected, onRowSelectionChange }

Other

SelectColumn: Column<any, any>

SELECT_COLUMN_KEY = 'rdg-select-column'

Types

Column

name: string | ReactElement

The name of the column. By default it will be displayed in the header cell

key: string

A unique key to distinguish each column

width?: Maybe<number | string>

Default auto

Width can be any valid css grid column value. If not specified, it will be determined automatically based on grid width and specified widths of other columns.

1width: 80; // pixels
2width: '25%';
3width: 'max-content';
4width: 'minmax(100px, max-content)';

max-content can be used to expand the column to show all the content. Note that the grid is only able to calculate column width for visible rows.

minWidth?: Maybe<number>

Default: 50 pixels

Sets the maximum width of a column.

maxWidth?: Maybe<number>

Sets the maximum width of a column.

cellClass?: Maybe<string | ((row: TRow) => Maybe<string>)>

A function to add a class on the row

headerCellClass?: Maybe<string>

summaryCellClass?: Maybe<string | ((row: TSummaryRow) => Maybe<string>)>

renderCell?: Maybe<(props: RenderCellProps<TRow, TSummaryRow>) => ReactNode>

Render function used to render the content of cells

renderHeaderCell

Render function used to render the content of header cells

renderSummaryCell

Render function used to render the content of summary cells

DataGridHandle

RenderEditCellProps

RenderCellProps

RenderGroupCellProps

RenderRowProps

Generics

• R, TRow: Row type
• SR, TSummaryRow: Summary row type
• K: Row key type