# @gravity-ui/table 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/table/

版本：2\.0\.0
npm 元数据更新时间：2026-11-09T13:36:03.218Z
中文译文更新时间：2026-11-16T23:48:34.311Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/table
原文对照：https://npmcn.com/package/%40gravity-ui/table/?lang=original
项目主页：https://github.com/gravity-ui/table#readme
源码仓库：https://github.com/gravity-ui/table

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.7 MB，1610 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，lodash ^4\.18\.1，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@dnd-kit/core ^6\.3\.0，@dnd-kit/sortable ^10\.0\.0，@gravity-ui/icons ^2\.0\.0，@gravity-ui/uikit ^8\.0\.0
- 首次发布：2024-05-21T13:00:46.947Z
- 最新版本发布：2026-11-09T13:36:02.957Z
- 近 30 天下载量：28958（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 21 个）

## 中文简介

`shell npm install --save @gravity-ui/table`

## 安装

```sh
npm install @gravity-ui/table
```

也可以使用：`pnpm add @gravity-ui/table`、`yarn add @gravity-ui/table`、`bun add @gravity-ui/table`

## README

# @gravity-ui/表 \\ [![npm package](https://img.shields.io/npm/v/@gravity-ui/table)](https://www.npmjs.com/package/@gravity-ui/table) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/table/.github/workflows/ci.yml?label=CI&logo=github)](https://github.com/gravity-ui/table/actions/workflows/ci.yml?query=branch:main) [![storybook](https://img.shields.io/badge/Storybook-deployed-ff4685)](https://preview.gravity-ui.com/table/)

## 安装

```shell
npm install --save @gravity-ui/table
```

## 使用量

```tsx
import React from 'react';
import {Table, useTable} from '@gravity-ui/table';
import type {ColumnDef} from '@gravity-ui/table/tanstack';

interface Person {
  id: string;
  name: string;
  age: number;
}

const columns: ColumnDef<Person>[] = [
  {accessorKey: 'name', header: 'Name', size: 100},
  {accessorKey: 'age', header: 'Age', size: 100},
];

const data: Person[] = [
  {id: 'name', name: 'John', age: 23},
  {id: 'age', name: 'Michael', age: 27},
];

const BasicExample = () => {
  const table = useTable({
    columns,
    data,
  });

  return <Table table={table} />;
};
```

### 构成部分

有两种表格组件可供您使用:

-   `BaseTable` - 仅具有基本风格的组成部分;
-   `Table` - 具有基于重力UI风格的组件.

#### 行选择

```tsx
import {selectionColumn} from '@gravity-ui/table';
import type {RowSelectionState} from '@gravity-ui/table/tanstack';

const columns: ColumnDef<Person>[] = [
  selectionColumn as ColumnDef<Person>,
  // ...other columns
];

const data: Person[] = [/* ... */];

const RowSelectionExample = () => {
  const [rowSelection, setRowSelection] = React.useState<RowSelectionState>({});

  const table = useTable({
    columns,
    data,
    enableRowSelection: true,
    enableMultiRowSelection: true,
    onRowSelectionChange: setRowSelection,
    state: {
      rowSelection,
    },
  });

  return <Table table={table} />;
};
```

要使用带有选择的分组, 使用 `useRowSelectionFixedHandler` 钩. 没有它, 父行复选框状态将是错误的 . [https://github.com/TanStack/table/issues/4878 互联网档案馆的存檔,存档日期2014-12-21](https://github.com/TanStack/table/issues/4878)

#### 自定义范围选择列

这个 `useToggleRangeSelectionHandler` hook 返回一个更改处理器,该处理器会监听 Shift+ 单击事件,并进行行范围选择。 它需要通过一个 `CellContext` 为了进入表和行的内部状态.

```tsx
import React, {type ChangeEvent, useCallback, useState} from 'react';

import {Table, useToggleRangeSelectionHandler, useTable} from '@gravity-ui/table';
import type {CellContext, ColumnDef, RowSelectionState} from '@gravity-ui/table/tanstack';
import {Checkbox, type CheckboxProps} from '@gravity-ui/uikit';

type CustomRangedSelectionCheckboxProps = Omit<CheckboxProps, 'onChange'> & {
  cellContext: CellContext<unknown, unknown>;
};

const CustomRangedSelectionCheckbox = ({
  className,
  cellContext,
  ...restProps
}: CustomRangedSelectionCheckboxProps) => {
  const rowToggleRangedSelectionHandler = useToggleRangeSelectionHandler(cellContext);

  const handleChange = useCallback(
    (event: ChangeEvent<HTMLInputElement>): void => {
      rowToggleRangedSelectionHandler(event);
    },
    [rowToggleRangedSelectionHandler],
  );

  return <Checkbox {...restProps} onChange={handleChange} />;
};

const customSelectionColumn: ColumnDef<unknown> = {
  id: '_select',
  header: ({table}) => (
    <Checkbox
      size="l"
      checked={table.getIsAllRowsSelected()}
      indeterminate={table.getIsSomeRowsSelected()}
      onChange={table.getToggleAllRowsSelectedHandler()}
    />
  ),
  cell: (cellContext) => (
    <CustomRangedSelectionCheckbox
      size="l"
      checked={cellContext.row.getIsSelected()}
      disabled={!cellContext.row.getCanSelect()}
      indeterminate={cellContext.row.getIsSomeSelected()}
      cellContext={cellContext}
    />
  ),
  size: 41,
  maxSize: 41,
  minSize: 41,
  enableResizing: false,
  enableSorting: false,
};

const columns: ColumnDef<Person>[] = [
  customSelectionColumn as ColumnDef<Person>,
  // ...other columns
];

const data: Person[] = [/* ... */];

const RowRangedSelectionExample = () => {
  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});

  const table = useTable({
    columns,
    data,
    enableRowSelection: true,
    enableMultiRowSelection: true,
    onRowSelectionChange: setRowSelection,
    state: {
      rowSelection,
    },
  });

  return <Table table={table} />;
};
```

还有一个 `RangedSelectionCheckbox` 组件,在内部使用钩并接受 `CellContext` 作为道具。 此组件为自定义选择列添加范围选择功能提供了快手.

```tsx
import type {ColumnDef} from '@gravity-ui/table/tanstack';
import {RangedSelectionCheckbox, SelectionCheckbox} from '@gravity-ui/table';

export const selectionColumn: ColumnDef<unknown> = {
  id: '_select',
  header: ({table}) => (
    <SelectionCheckbox
      checked={table.getIsAllRowsSelected()}
      disabled={!table.options.enableRowSelection}
      indeterminate={table.getIsSomeRowsSelected()}
      onChange={table.getToggleAllRowsSelectedHandler()}
    />
  ),
  cell: (cellContext) => (
    <RangedSelectionCheckbox
      checked={cellContext.row.getIsSelected()}
      disabled={!cellContext.row.getCanSelect()}
      indeterminate={cellContext.row.getIsSomeSelected()}
      cellContext={cellContext}
    />
  ),
  meta: {
    hideInSettings: true,
  },
  size: 32,
  minSize: 32,
};
```

默认情况下,所生成的选定列 `selectionColumn` 包括范围选择功能.

```tsx
import {selectionColumn} from '@gravity-ui/table';
import type {ColumnDef} from '@gravity-ui/table/tanstack';

const columns: ColumnDef<Person>[] = [
  selectionColumn as ColumnDef<Person>,
  // ...other columns
];
```

**说明**: 如果表格包含嵌入行, 范围选择将无法工作 。 目前,这被认为是未定义的行为.

#### 排序

学习反应表中的列属性 [文档](https://tanstack.com/table/v8/docs/guide/sorting)

```tsx
import type {SortingState} from '@gravity-ui/table/tanstack';

const columns: ColumnDef<Person>[] = [/* ... */];

const data: Person[] = [/* ... */];

const SortingExample = () => {
  const [sorting, setSorting] = React.useState<SortingState>([]);

  // Your column MUST have accessorFn for sorting to be enabled

  const table = useTable({
    columns,
    data,
    enableSorting: true,
    getRowId: (item) => item.id,
    onSortingChange: setSorting,
    state: {
      sorting,
    },
  });

  return <Table table={table} />;
};
```

如果您想要手动排序元素通过 `manualSorting` 属性 :

```tsx
const table = useTable({
  // ...
  manualSorting: true,
});
```

#### 分组

```tsx
import type {ExpandedState, Row} from '@gravity-ui/table/tanstack';

interface Person {
  id: string;
  name: string;
  age: number;
}

interface PersonGroup {
  id: string;
  name: string;
  items: Person[];
}

type Item = PersonGroup | Person;

const columns: ColumnDef<Item>[] = [
  {accessorKey: 'name', header: 'Name', size: 200},
  {accessorKey: 'age', header: 'Age', size: 100},
];

const data: Item[] = [
  {
    id: 'friends',
    name: 'Friends',
    items: [
      {id: 'nick', name: 'Nick', age: 25},
      {id: 'tom', name: 'Tom', age: 21},
    ],
  },
  {
    id: 'relatives',
    name: 'Relatives',
    items: [
      {id: 'john', name: 'John', age: 23},
      {id: 'michael', name: 'Michael', age: 27},
    ],
  },
];

const getGroupTitle = (row: Row<Item>) => row.getValue<string>('name');

const GroupingExample = () => {
  const [expanded, setExpanded] = React.useState<ExpandedState>({});

  const table = useTable({
    columns,
    data,
    enableExpanding: true,
    getSubRows: (item) => ('items' in item ? item.items : undefined),
    onExpandedChange: setExpanded,
    state: {
      expanded,
    },
  });

  return <Table table={table} getGroupTitle={getGroupTitle} />;
};
```

要使用带有选择的分组, 使用 `useRowSelectionFixedHandler` 钩. 没有它, 父行复选框状态将是错误的 . [https://github.com/TanStack/table/issues/4878 互联网档案馆的存檔,存档日期2014-12-21](https://github.com/TanStack/table/issues/4878)

要启用筑巢样式, 通过 `withNestingStyles = true` 在列配置中.

连接指标可以通过通过 `showTreeDepthIndicators = false`。 。 。 .

要添加扩展/缩放行的控件,请用 `TreeExpandableCell` 组件或具有类似自定义组件的组件:

```tsx
import {TreeExpandableCell} from '@gravity-ui/table';

const columns: ColumnDef<Item>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    size: 200,
    showTreeDepthIndicators: false,
    withNestingStyles: true,
    cell: ({row, info}) => (
      <TreeExpandableCell row={row}>{info.getValue<string>()}</TreeExpandableCell>
    ),
  },
  // ...other columns
];
```

#### 重排顺序

```tsx
import type {ReorderingProviderProps} from '@gravity-ui/table';
import {dragHandleColumn, ReorderingProvider} from '@gravity-ui/table';

const columns: ColumnDef<Person>[] = [
  dragHandleColumn,
  // ...other columns
];

const data: Person[] = [/* ... */];

const ReorderingExample = () => {
  const table = useTable({
    columns,
    data,
    getRowId: (item) => item.id,
  });

  const handleReorder = React.useCallback<
    NonNullable<ReorderingProviderProps<Person>['onReorder']>
  >(
    ({
      draggedItemKey,
      targetItemKey,
      baseItemKey,
      baseNextItemKey,
      enableNesting,
      nextChild,
      pullFromParent,
    }) => {
      // ...
    },
    [],
  );

  return (
    <ReorderingProvider table={table} onReorder={handleReorder}>
      <Table table={table} />
    </ReorderingProvider>
  );
};
```

#### 没有拖动柄的重排

设定 `dragWithoutHandle` 将整行用作拖动器并省略 `dragHandleColumn` 从一栏定义:

```tsx
const columns: ColumnDef<Person>[] = [
  {accessorKey: 'name', header: 'Name'},
  {accessorKey: 'age', header: 'Age'},
];

return (
  <ReorderingProvider table={table} dragWithoutHandle onReorder={handleReorder}>
    <Table table={table} />
  </ReorderingProvider>
);
```

指针在拖曳开始前必须以 8 像素移动, 因此正则行和控件单击保留 工作时 要排除行中的自定义部分开始拖曳, 调用 `preventDefault()` 联合国 `onPointerDown` 处理者.

`ReorderingProvider` 默认允许 dnd-kit 垂直自动滚动 。 过 `autoScroll={false}` 当应用程序提供自己的拖动自动滚动执行时;同时运行两者都可以 制作相竞的卷轴写作.

自定义拖动手柄应读取 `attributes`, (中文(简体) ), `listeners`,以及 `setActivatorNodeRef` 从 `DraggableRowContext` 并把它们附在控件元素上。 这可以重用行的 DnD 登记。 不要打电话 `useSortable` 重用同一行的 id: 后面挂起的手柄 虚拟化将取代该行注册的DOM节点.

#### 键盘重排和访问

`ReorderingProvider` 支持键盘行拖曳. 聚焦拖动控点, 按空格或 Enter 来取行, 使用箭头键来移动, 按 空格或 Enter 以放弃它 。 出逃取消移动. 键盘拖放仅适用于行;键盘与列头的相互作用保持不变.

使用 `accessibility` 定制 dnd-kit 的屏幕阅读器指令、 公告、 公告 ,用于键盘和指针拖放的焦点恢复. 当行和列提供者被嵌入时,他们共享相同的DnD上下文和无障碍设置; 供货商的命令不重要.

```tsx
<ReorderingProvider
  table={table}
  onReorder={handleReorder}
  accessibility={{
    screenReaderInstructions: {
      draggable:
        'Press Space to pick up a row, arrow keys to move, Enter to drop, or Escape to cancel.',
    },
  }}
>
  <Table table={table} />
</ReorderingProvider>
```

#### 列重排顺序

以 `ColumnReorderingProvider` 以允许其标题对列进行拖放重排.

```tsx
import {ColumnReorderingProvider} from '@gravity-ui/table';

const columns: ColumnDef<Person>[] = [
  {accessorKey: 'name', header: 'Name', size: 100},
  {accessorKey: 'age', header: 'Age', size: 100},
];

const ColumnReorderingExample = () => {
  const table = useTable({
    columns,
    data,
    getRowId: (item) => item.id,
  });

  return (
    <ColumnReorderingProvider table={table}>
      <Table table={table} />
    </ColumnReorderingProvider>
  );
};
```

### 列和列一起重排顺序

鸟巢 `ColumnReorderingProvider` 财务报告和审定财务报表 `ReorderingProvider` 可同时启用两个拖动轴。 提供者的顺序并不重要——他们内部有一个单一的dnd-kit上下文.

```tsx
import type {ColumnReorderingProviderProps, ReorderingProviderProps} from '@gravity-ui/table';
import {ColumnReorderingProvider, ReorderingProvider, dragHandleColumn} from '@gravity-ui/table';

const columns: ColumnDef<Person>[] = [
  dragHandleColumn,
  {accessorKey: 'name', header: 'Name'},
  {accessorKey: 'age', header: 'Age'},
];

const CombinedReorderingExample = () => {
  const [data, setData] = React.useState(initialData);
  const [columnOrder, setColumnOrder] = React.useState<string[]>([]);

  const table = useTable({
    columns,
    data,
    getRowId: (item) => item.id,
    state: {columnOrder},
    onColumnOrderChange: setColumnOrder,
  });

  const handleRowReorder = React.useCallback<
    NonNullable<ReorderingProviderProps<Person>['onReorder']>
  >(({draggedItemKey, baseItemKey}) => {
    // update data array
  }, []);

  const handleColumnReorder = React.useCallback<
    NonNullable<ColumnReorderingProviderProps<Person>['onReorder']>
  >(({columnOrder}) => {
    setColumnOrder(columnOrder);
  }, []);

  return (
    <ColumnReorderingProvider table={table} onReorder={handleColumnReorder}>
      <ReorderingProvider table={table} onReorder={handleRowReorder}>
        <Table table={table} />
      </ReorderingProvider>
    </ColumnReorderingProvider>
  );
};
```

如果你控制着 `columnOrder` (如坚持)通过 `onReorder` 并应用由此产生的命令:

```tsx
const [columnOrder, setColumnOrder] = React.useState<string[]>([]);

const table = useTable({
  columns,
  data,
  state: {columnOrder},
  onColumnOrderChange: setColumnOrder,
});

return (
  <ColumnReorderingProvider
    table={table}
    onReorder={({columnOrder}) => setColumnOrder(columnOrder)}
  >
    <Table table={table} />
  </ColumnReorderingProvider>
);
```

CSS API: (英语)

| CSS 变量 | 默认 | 说明 |
| --- | --- | --- |
| `--gt-table-reordering-insertion-line-color` | `#4d8bff` | 投放插入行的颜色 |
| `--gt-table-reordering-insertion-line-width` | `2px` | 滴入行的宽度 |
| `--gt-table-reordering-dragged-opacity` | `0.4` | 拖曳列的不透明度 |
| `--gt-table-drag-overlay-background` | `#fff` | 拖动预览背景 |
| `--gt-table-drag-overlay-shadow` | `0 3px 12px rgba(0,0,0,0.15)` | 拖动预览框-阴影 |
| `--gt-table-drag-overlay-border-radius` | `6px` | 拖动预览边框半径 |

禁止重排特定列, 设置 `enableColumnReordering: false` 在其栏定义中。 占位符(组)列不可拖动 。 使用 `activationDistance` (默认) `8`)来调谐指针在拖曳开始前必须移动多远,这可以使指针点击(类似排序)工作.

被平接的柱子也可以被重排,但只在它们之间:一个柱子可以被移动到被平接的左被平接的组内,右被平接的组内,或者中心(非被平接的)组内——它从不通过拖动来跨越一被平接的边界.

```tsx
<ColumnReorderingProvider
  table={table}
  onReorder={({columnOrder, columnPinning, pinned}) => {
    if (pinned) {
      setColumnPinning(columnPinning);
    } else {
      setColumnOrder(columnOrder);
    }
  }}
>
  <Table table={table} />
</ColumnReorderingProvider>
```

拖曳时 :

-   a. 拖放上方的指针;
-   被拖走的柱子变成半透明的;
-   划出一行蓝色的插入线;

```tsx
<ColumnReorderingProvider
  table={table}
  autoScroll
  dragOverlayRowCount={10}
  renderDragOverlay={({columnId}) => <CustomColumnPreview columnId={columnId} />}
>
  <Table table={table} />
</ColumnReorderingProvider>
```

#### 虚拟化

如果您想要使用网格容器作为滚动元素( 如果您想要使用窗口查看窗口虚拟化部分) 。 请确定在容器上设置一个固定的高度;否则虚拟化将行不通.

```tsx
import {useRowVirtualizer} from '@gravity-ui/table';

const columns: ColumnDef<Person>[] = [/* ... */];

const data: Person[] = [/* ... */];

const VirtualizationExample = () => {
  const table = useTable({
    columns,
    data,
    getRowId: (item) => item.id,
  });

  const containerRef = React.useRef<HTMLDivElement>(null);

  const rowVirtualizer = useRowVirtualizer({
    count: table.getRowModel().rows.length,
    estimateSize: () => 20,
    overscan: 5,
    getScrollElement: () => containerRef.current,
  });

  return (
    <div ref={containerRef} style={{height: '500px', overflow: 'auto'}}>
      <Table table={table} rowVirtualizer={rowVirtualizer} />
    </div>
  );
};
```

对于在连续双向滚动过程中必须保持覆盖的表格,允许适应性 直接DOM模式并使用稳定的语义键. 同一密钥必须在 不可改变的重排或树再生:

```tsx
import {getColumnAwareRowOverscan} from '@gravity-ui/table';

const rows = table.getRowModel().rows;
const columnCount = table.getVisibleLeafColumns().length;

const getItemKey = React.useCallback(
  (index: number) => rows[index]?.id ?? `missing:${index}`,
  [rows],
);

const rowVirtualizer = useRowVirtualizer({
  adaptiveFlushSync: true,
  count: rows.length,
  directDomUpdates: true,
  directDomUpdatesMode: 'position',
  estimateSize: () => 40,
  getItemKey,
  getScrollElement: () => containerRef.current,
  overscan: getColumnAwareRowOverscan(columnCount),
});
```

`adaptiveFlushSync` 保持温暖的挂载范围,同步地填满只可见的 范围. `directDomUpdates` 让虚拟化器更新行位置和体积,而不包含 每一份卷轴通知都做反应。 使用 `position` 除非变换为 周围布局需要。 保留 `getRowId` 财务报告和审定财务报表 `getItemKey` 稳定,并设定 `count` 从 在扩展、倒塌、重排或重排行后,当前的平整行模型. 任意习惯 `rangeExtractor` 仍然具有权威性,无法进行适应性窗口规划.

`getColumnAwareRowOverscan(columnCount, options?)` 将基准行切成数字 长出一串柱子。 默认情况下,它将240个单元的预算除以列数,下行数, 并将结果夹到4至24行。 使用 `table.getVisibleLeafColumns().length` 以排除隐藏 包括被钉住的柱子。 帮手和他们一起工作 `useRowVirtualizer` 财务报告和审定财务报表 `useWindowRowVirtualizer`; 您还可以通过一个明确的数字 `overscan` 换句话说.

支付您的单元格渲染成本的预算和限制。 如果您的应用程序将列虚拟化, 设定 `renderedColumnLimit` 到每行所制出的最大列数,包括被钉 列; 帮助者将所提供的列数限制在这个值上 :

```tsx
const overscan = getColumnAwareRowOverscan(table.getVisibleLeafColumns().length, {
  renderedColumnLimit: 16,
  cellBudget: 320,
  minOverscan: 4,
  maxOverscan: 20,
});
```

结果是基行超扫描,而不是对挂行或单元格的严格限制. 可见行为 除了超扫描器之外 适应性滚动可以扩大挂载范围. 所有帮助输入必须是非负安全整数,以及 `maxOverscan` 必须是至少 `minOverscan`; 无效值抛出 `RangeError`。零栏作为计算的一个.

`BaseTable.canDeferOffscreenCellContent` 是对非常宽的适应性表格的一种额外选择. 返回时 `true` 仅针对延迟挂载不能改变几何、焦点的被动单元格内容, 可访问性,或应用程序状态。 自定义行、 组行、 被绑定的单元格以及交互式或 副作用的内容仍应迫切.

使用默认的适应范围提取器, `BaseTable` 自动将活动拖动的行接上. 自定义范围提取器负责保留该行本身. 如果使用重排时 一个非适应虚拟化器,保持相同的语义 `getItemKey` 合同和通过 `rangeExtractor` 选项 :

```tsx
import {getVirtualRowRangeExtractor} from '@gravity-ui/table';

// ...

const tableRef = React.useRef<HTMLTableElement>(null);

const rowVirtualizer = useRowVirtualizer({
  // ...
  rangeExtractor: getVirtualRowRangeExtractor(tableRef.current),
});

return (
  <TableWithReordering
    ref={tableRef}
    table={table}
    rowVirtualizer={rowVirtualizer}
    onReorder={handleReorder}
  />
);
```

#### 窗口虚拟化

如果您想要使用窗口作为滚动元素, 请使用

```tsx
import {useWindowRowVirtualizer} from '@gravity-ui/table';

const columns: ColumnDef<Person>[] = [/* ... */];

const data: Person[] = [/* ... */];

const WindowVirtualizationExample = () => {
  const table = useTable({
    columns,
    data,
    getRowId: (item) => item.id,
  });

  const bodyRef = React.useRef<HTMLTableSectionElement>(null);

  const rowVirtualizer = useWindowRowVirtualizer({
    count: table.getRowModel().rows.length,
    estimateSize: () => 20,
    overscan: 5,
    scrollMargin: bodyRef.current?.offsetTop ?? 0,
  });

  return <Table table={table} rowVirtualizer={rowVirtualizer} bodyRef={bodyRef} />;
};
```

#### 调整大小

```tsx
const columns: ColumnDef<Person>[] = [/* ... */];

const data: Person[] = [/* ... */];

const ResizingDemo = () => {
  const table = useTable({
    columns,
    data,
    enableColumnResizing: true,
    columnResizeMode: 'onChange',
  });

  return <Table table={table} />;
};
```

#### 列设置

设定 `enableReset` 改为 `true` 显示设置的弹出重置按钮(默认隐藏). 它恢复了表格上的列能见度和顺序 `initialState`。重置更改 弹出草稿; 按应用程序保存。 没有 `initialState`重置显示全部 按定义顺序排列. 可选 `onSettingsReset` 回调收到恢复的能见度和列顺序 当重置被点击时,在草案应用前.

```tsx
const columns: ColumnDef<Person>[] = [
  // ...other columns
  {
    id: 'settings_column_id',
    header: ({table}) => <TableSettings table={table} />,
    meta: {
      hideInSettings: false, // Optional. Allows to hide this column from settings popover
      titleInSettings: 'ReactNode', // Optional. Overrides header field for settings popover (if you need different content for header and settings popover)
    },
  }, // or you can use function getSettingsColumn
];

const data: Person[] = [/* ... */];

const TableSettingsDemo = () => {
  const [columnVisibility, onColumnVisibilityChange] = React.useState<VisibilityState>({
    // for outside control and initial state
    column_id: false, // for hidding by default
  });
  const [columnOrder, onColumnOrderChange] = React.useState<string[]>([/* leaf columns ids */]); // for outside control and initial state

  // Alternative variant to get state, callbacks, and set on setting apply callbacks - using useTableSettings hook:
  // const {state, callbacks} = useTableSettings({initialVisibility: {}, initialOrder: []})

  const table = useTable({
    columns,
    data,
    state: {
      columnVisibility,
      columnOrder,
    },
    onColumnVisibilityChange,
    onColumnOrderChange,
  });

  return <Table table={table} />;
};
```

在反应表中更多地了解表格和列调整属性大小 [文档](https://tanstack.com/table/v8/docs/api/features/column-sizing)

## 已知问题和兼容性

### React 19 + React 编译器兼容性

**已知问题:** 使用 React 19 和 React 编译器时有一个已知的兼容性问题 `@gravity-ui/table` (取自"坦斯塔克表"上方). 数据变化时,该表可能不会重报. 见 [谭斯塔克表 第5567期](https://github.com/TanStack/table/issues/5567) 详细情况.

**工作间:**

如果使用 React 19 与 React 编译器并用表重递遇到问题,则可以使用 `'use no memo'` 在组件代码中的指示 :

```tsx
import React from 'react';
import {Table, useTable} from '@gravity-ui/table';
import type {ColumnDef} from '@gravity-ui/table/tanstack';

function MyTable() {
  'use no memo'; // Disable React Compiler memoization for this component

  const [data, setData] = React.useState<Person[]>([]);

  const table = useTable({
    data,
    columns,
  });

  return <Table table={table} />;
}
```

**替代解决方案 :**

您也可以明确记住表格实例或数据,以确保正确重报:

```tsx
import React from 'react';
import {Table, useTable} from '@gravity-ui/table';
import type {ColumnDef} from '@gravity-ui/table/tanstack';

function MyTable() {
  const [data, setData] = React.useState<Person[]>([]);

  // Explicitly memoize data to ensure re-renders
  const memoizedData = React.useMemo(() => data, [data]);

  const table = useTable({
    data: memoizedData,
    columns,
  });

  return <Table table={table} />;
}
```

**说明:** 这个问题位于基本的TanStack Table库中,需要在那里固定. 上面的绕道应该有用,直到有固定.

## 许可证

根据麻省理工学院的许可证分发。 见 [自由主义](https://npmcn.com/package/%40gravity-ui/table/LICENSE) 详细情况.

## 对于人工智能特工

一个无头, TanStack- Table- powerdata grade for Gravity UI apps - 访问它可以排序,可选择,可分组,可重排,以及虚拟化的表格, 而不是在 uikit 的基础上编织原始标记 `Table`。 。 。 .

### 何时使用

-   需要行或窗口虚拟化的大型数据集(`useRowVirtualizer`, (中文(简体) ), `useWindowRowVirtualizer`) (中文(简体) ).
-   列排序、调整大小、重排顺序`ColumnReorderingProvider`,指针和每个用户列设置(`TableSettings`) (中文(简体) ).
-   行选择(单行/多行,范围)和有可扩展单元格的树/组行.

### 不使用时

-   一个简单而静态的桌子,上面有几行,没有先进的特征——遗产 `Table` 从 [`@gravity-ui/uikit/legacy`](https://github.com/gravity-ui/uikit) 更轻.
-   非表格清单-使用 `List` 从 [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit)。 。 。 .
-   电子表格式的内行单元格编辑——此网格是读取/播放焦点,而不是一个可编辑的电子表格.

### 常见陷阱

-   **你建桌子的时候 `useTable`,然后将 `<Table table={table} />`。 。 。 .** 主道具为: `table` (实例),没有 `data`编号 :`columns` 直接打开 `<Table>`; 通过 `data` 财务报告和审定财务报表 `columns` 改为 `useTable`。 。 。 .
-   **类型来自 `@gravity-ui/table/tanstack` 子路径.** 导入 `ColumnDef`, (中文(简体) ), `RowSelectionState`, (中文(简体) ), `SortingState`等来源 `@gravity-ui/table/tanstack`,而不是从包根.
-   **排序需要一个访问器.** 一定有专栏 `accessorKey`编号 :`accessorFn` 用于排序工作; 设置 `enableSorting` 和提供 `getRowId`。 。 。 .
-   **React 19 + React 编译器可以跳过再发.** 这是一个上游 TanStack 表格问题 `'use no memo'` 给组件指令或提醒 `data`。 。 。 .
-   **区域选择随嵌入行而中断 .** 当表格分组/取消行时, 范围选择是未定义的行为; 使用 `useRowSelectionFixedHandler` 用于组合的正确的父检查框状态.

## AI代理的文件

安装版本的可代理读取文档位于 `node_modules/@gravity-ui/table/build/docs/INDEX.md`。 。 。 .

## 常见问题

### @gravity-ui/table 是什么？

shell npm install --save @gravity-ui/table

### 如何安装 @gravity-ui/table？

在项目目录运行 npm install @gravity-ui/table，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、lodash（^4\.18\.1）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@dnd-kit/core（^6\.3\.0）、@dnd-kit/sortable（^10\.0\.0）、@gravity-ui/icons（^2\.0\.0）、@gravity-ui/uikit（^8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gravity-ui/table 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gravity-ui/table 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gravity-ui/table 可以商用吗？

@gravity-ui/table 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gravity-ui/table 的下载量有多少？

根据 npm 官方下载统计，@gravity-ui/table 在 2026/10/17 – 2026/11/15 这 30 天内被下载 28,958 次，日均约 965 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gravity-ui/table 还在维护吗？

最新版本 2\.0\.0 发布于 2026/11/09（7 天前）；至今共发布 60 个版本，其中过去 12 个月发布了 21 个；首次发布于 2024/05/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

