# @gravity-ui/react-data-table 中文文档

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

版本：3\.0\.0
npm 元数据更新时间：2026-11-12T16:05:40.006Z
中文译文更新时间：2026-11-16T23:51:50.748Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：121 kB，22 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=18\.0\.0
- 首次发布：2023-02-02T16:42:54.888Z
- 最新版本发布：2026-11-12T16:05:39.730Z
- 近 30 天下载量：25807（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 1 个）

## 中文简介

数据表组件

## 安装

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

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

## README

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

用于渲染表格的反射组件.

单元格分组得到支持:行由分组列先排序. 分组与 `dynamicRender` 选项.

多栏分拣也得到支持. 缩写+ 点击一列后添加一列 排序列表中。 简单的单击仅按此列排序表格。 排序顺序在序列中切换 : `none -> default -> reversed default -> none`。 。 。 .

## 虚拟化和反应严格模式

虚拟化`settings.dynamicRender: true`)依赖 `react-list`,它与反应 18+有兼容性限制 开发中严格模式. 在严格Mode的挂载/卸载/重挂载检查中,会删除滚动收听器,而不恢复. 滚动可以显示空区域 `uniform` 财务报告和审定财务报表 `variable` 模式或停止渲染附加行 `simple` 模式.

此严格模式重载检查不会在生产架构中运行 .

`@gravity-ui/react-data-table` 处于维护模式,不会收到新功能。 我们建议迁移到 [@ gravity-ui/ 表](https://github.com/gravity-ui/table)。 。 。 .

## 属性

| 财产 | 类型 | 需求 | 默认 | 说明 |
| :-- | :-- | :-- | :-- | :-- |
| 栏 | `Array` | ✓ |  | 清单 [表格栏](https://npmcn.com/package/%40gravity-ui/react-data-table/#readme-Column) |
| 页眉数据 | `Array` |  |  | 将显示在标题内的数据行列表。 如果头部有粘性,行会也粘. 适用于他们与划入 `data` (单位:千美元)[页眉数据](https://npmcn.com/package/%40gravity-ui/react-data-table/#readme-headerData)(中文(简体) ) |
| 数据 | `Array` | ✓ |  | 数据行列表 |
| 页脚数据 | `Array` |  |  | 将数据发送到表脚的行列表。 与串接方式相同 `data` |
| 启动Index | `Number` |  | `0` | 初始索引(用于显示行索引) |
| 设置 | `Object` |  |  | [表格设置](https://npmcn.com/package/%40gravity-ui/react-data-table/#readme-Settings) |
| 空数据信 | `String` |  | "没有数据" | 数据为空时显示的消息 |
| 调制EmptyRow | `Function` |  |  | 空表格行的自定义渲染器,接受一列列 `(columns) => ReactNode` |
| 行分类Name | `Function` |  |  | 设置字符串类的方法 `(row, index, isFooterRow, isHeaderRow) => (<string> )` |
| 行键 | `Function` |  |  | 返回反应键值的方法 `(row, index) => (<scalar_type_value> )`。默认方法返回 `row.id` || `index` |
| 初始命令 | `Object` |  |  | 格式的初始排序`{columnId: <string>, order: <DataTable.ASCENDING` | `DataTable.DESCENDING>}` 或此类物体的清单. |
| 主题 | `String` |  | 阳出云去 | 主题名称. 要使用内置表格主题,请使用 `'legacy'` 数值。 与 @ gravity- ui/ uikit 颜色的相容性, 请使用 `'yandex-cloud'` (默认) |
| 索尔特 | `Function` |  |  | 排序听众 `([{columnId: <string>, order: <DataTable.ASCENDING` | `DataTable.DESCENDING>}]) => void`。使用它来保存排序状态并传递给 `initialSortOrder` 在页面刷新. |
| 排序 | `Object` |  |  | 格式排序 `{columnId: <string>, order: <DataTable.ASCENDING` | `DataTable.DESCENDING>}` 或此类物体的清单. |
| 回复 | `Function` |  |  | 调整收听器大小 `(columnId: string, newWidth: number) => void`。使用它来保存新的列宽. |
| 可见RowIndex | `Function` |  |  | 方法 `(row, index) => number` 返回行索引 `displayIndices` 旗帜。 应用外部排序时使用它指定正确的行索引 |
| 在罗克克 | `Function` |  |  | 单击一行的听众 `(row, index, event) => void` |
| 在数字之前无 | `Boolean` |  |  | 确定 `null`编号 :`undefined` 排序时的值。 如果真是这样, `null`编号 :`undefined` 值在升序时显示于上;在降序时显示于下。 若为 `false`编号 :`undefined`,在底部显示 |
| 获取 ColSpansOf 颜色 | `Function` |  |  | 为每行配置列 `({ row, columns, index, headerData, span, footer, odd }) => {[colName: string]: number} / undefined` |

## 设置

| 财产 | 类型 | 默认 | 说明 |
| :-- | :-- | :-- | :-- |
| 显示索引 | `Boolean | {maxIndex: number}` | `true` | 是否显示行索引( 从 `startIndex`) (中文(简体) ). 当设定为有 maxIndex 对象时, 它根据指定的最大索引值而不是实际数据长度控制索引列的宽度 |
| 粘相头 | `DataTable.FIXED DataTable.MOVING` |  | 启用两种模式之一的粘贴头 。 这个 `DataTable.FIXED` 如果表格容器相对于页面是固定的,则使用模式。 如果带有容器的页面可滚动,则更好地使用 `DataTable.MOVING`,但您的浏览器需要支持 `position: sticky`。否则,粘贴头将被完全禁用. |
| 粘着Top | `Number` |  | 将信头贴在想要的高度( 在 `DataTable.MOVING` 模式)。 如果可滚动容器除表格外还包括其他内容,则使用。 如果信头不能粘住容器的边缘,最好使用精确定位的空格来使表格内容不会在信头上方凸出. |
| 粘胶花 | 见粘相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 |  | 类似 `stickyHead` 页:1 `footerData` |
| 粘接点 | `Number` |  | 横行从 `footerData` 带有适当的下边距(在 `DataTable.MOVING` 模式). |
| 同步头顶恢复 | `Boolean` | `false` | 调整窗口大小时同步粘贴头的大小 |
| 动态内置参考 | `React.RefObject<DynamicInnerRefT>` |  | 当您想要直接调用方法时, 获取 ReactList 实例的参考文献, 例如, [ReactList.scroll to (中文(简体) )](https://github.com/caseywebdev/react-list#scrolltoindex)。 。 。 . `DynamicInnerRefT` 也导出为设置,以正确定义类型,而不添加依赖工程的ReactList. |
| 动态渲染器 | `Boolean` | `false` | 行的动态渲染(仅视图端口). 需要特定的布局 |
| 动态招标模式 | `String` | `'uniform'` | [反应List.type](https://github.com/coderiety/react-list#type-one-of-simple-variable-or-uniform-defaults-to-simple) |
| 动态项目大小估计器 | `Function` |  | [ReactList. itemSize 估计器](https://github.com/coderiety/react-list#itemsizeestimatorindex-cache) |
| 动态项目编辑器 | `Function` |  | [反应列表. itemSizeGetter](https://github.com/coderiety/react-list#itemsizegetterindex) |
| 动态渲染最小化 | `Number` | `1` | 无论如何,即使少数行完全填满了容器高度(如果启用了动态渲染器,这是有道理的),也要提供最低限度的行数. 数值被传递 [页:1 `minSize` reactList 组件属性](https://github.com/coderiety/react-list#minsize-defaults-to-1)。 。 。 . |
| 动态渲染器使用staticSize | `Boolean` | `false` | [ReactList.useStaticSize (英语)](https://github.com/caseywebdev/react-list#usestaticsize-defaults-to-false) |
| 动态阈值 | `Number` |  | [ReactList.阈值](https://github.com/caseywebdev/react-list#threshold-defaults-to-100) |
| 动态滚动父程序 | `Function` |  | [ReactList.scroll 父母关系](https://github.com/caseywebdev/react-list#scrollparentgetter-defaults-to-finding-the-nearest-scrollable-parent) |
| 动态渲染器 | `Function` |  | [ReactList.scroll 父母维尤波特SizeGetter](https://github.com/caseywebdev/react-list#scrollparentviewportsizegetter-defaults-to-scrollparents-viewport-size) |
| 可排序 | `Boolean` | `true` | 启用整个表格的排序 |
| 外部服务器 | `Boolean` | `false` | 禁用组件侧的数据排序 . [更多信息](https://npmcn.com/package/%40gravity-ui/react-data-table/#readme-externalSort) |
| 禁用重设 | `Boolean` | `false` | 禁用排序重置( 可启用 `none -> default <-> reversed default` 排序方案) |
| 默认顺序 | `DataTable.ASCENDING DataTable.DESCENDING` | `DataTable.ASCENDING` | 表格中的默认排序顺序 |
| 默认可响应 | `Boolean` | `false` | 用于确定列是否可调整的值, 如果没有设置列的明确值 |
| 突出显示 | `Boolean` |  | 悬浮时突出显示表格行 |
| 条纹 | `Boolean` |  | 是否给偶数行配色 |
| 页眉Mod | `multiline` `pre` |  | 启用多行(即 `multiline` )或预格式化标题( `pre` 数值) |

### 外部服务器

禁用组件侧的数据排序。 请注意:

-   该表仍然是排序状态(所选列和排序方向)的主要来源,并负责根据该状态正确渲染表头.
-   外部环境必须传递到表格中正确的排序行 `props.data` 答复 `props.onSort` 召回电话.
-   取消列值的分组(参见 [列. 组](https://npmcn.com/package/%40gravity-ui/react-data-table/#readme-group)) (中文(简体) ).

* * *

## 栏

列让您灵活自定义单元格的渲染 . 以最简单的形式来说,该栏描述的外观如下:

```json
{
  "name": "column_name"
}
```

手机会显示 `row.column_name` 如来相.

这个 `name` 字段是唯一的强制字段。 其余领域介绍如下:

| 财产 | 类型 | 说明 |
| :-- | :-- | :-- |
| 名称 | `string` | 列名称和默认值 `header` 财务报告和审定财务报表 `accessor` |
| 标题 | `string` 或者说 `node` | 列标题 |
| 标题 | `string` | 标题 |
| 类Name | `string` | 列类 |
| 宽度         | `string | number` | 列宽 |
| 可调整大小     | `boolean` | 确定是否可以更改列宽。 只有在 `onResize` 函数通过. |
| 调整MinWidth的大小 | `number` | 调整大小的最小列宽 . |
| 调整MaxWidth的大小 | `number` | 更改大小的最大列宽度 . |
| 对齐 | `DataTable.LEFT DataTable.CENTER DataTable.RIGHT` | 单元格中的文本对齐 |
| 访问器 | `func` | 回电 `(row) => (value)`。如果要在列中深度显示“隐藏”值,则使用它。 例如: `(row) => (row.child1.child2[0].value)` |
| 标题 | `string` 或者说 `func:string` | 回电 `(row) => (title)`。让您设置一个固定的标题(如果 `string`)或列单元格的动态标题。 返回一个字符串. |
| 提交 | `func:node` | 回电 `({value, row, index}) => (node)`让您任意制作一个单元格。 作为输入,它得到一个值,一个整行,或者一个行索引. 返回反应节点. |
| 自定义样式 | `func` | 回电 `({row, index, header, name}) => (styleObject)`。让我们为单元格设置自定义样式。 在回调中,您会通过一个带有数据,索引,列名的字符串,以及单元格是否为标题的旗帜. 在输出时,您期望一个带有样式的对象遵循React语法. |
| 点击 | `func` | 回电 `(row, column) => ()`手机上的Click监听器. |
| 可排序 | `Boolean` | 列是否可排序 . |
| 默认顺序 | `DataTable.ASCENDING DataTable.DESCENDING` | 列中的默认排序顺序 . |
| 排序访问器 | `func` | 回电 `(row) => (value)`中。如果您想要以其它数值排序,则使用它 `value`,或者如果 `value` 是非斯卡尔. |
| 递升排序 | `func` | 回电 `({row, index, span?}, {row, index, span?}) => (sortValue)`。如果想要完全自定义排序,则使用. |
| 子目录 | `array` | 嵌入的列 |
| 组 | `Boolean` | 将相同的值组合成一个单元格,允许您创建复杂的表格. [更多细节](https://npmcn.com/package/%40gravity-ui/react-data-table/#readme-group) |
| 自动分组 | `Boolean` | 允许用分组对所有列进行升序排序,从而实现自动分组。 默认为 `true` |

### 组

将相同的值组合为一个单元格。 请注意:

-   分组与 `Settings.dynamicRender` 选项,当它们一起启用时,表格可能效果不佳.
-   组合在 `Settings.externalSort` 选项已启用
-   这是值得的 `Settings.stripedRows` 财务报告和审定财务报表 `Settings.highlightRows` 设置.

* * *

### 多级标题

嵌入式柱子设置于 `sub` 字段。 带有附件的列,但 `sub` 字段, 只有影响标题的字段才有意义: `name`, (中文(简体) ), `header`, (中文(简体) ), `headerTitle`, (中文(简体) ), `align`,以及 `customStyle`。 。 。 .

### 页眉数据

这个 `headerData` 属性让您在表格开头添加行。 然而,如果头被粘住,行会和头相接. 在粘贴头模式下,此类行不会影响列宽,因此可能需要指定列宽.

### 定制主题

该表载有若干定制要素. 要为他们设置颜色,请使用 CSS 变量(例如,主题值为 `internal`:

```css
--data-table-color-base: #ffffff;
--data-table-color-stripe: rgba(0, 0, 0, 0.03);
--data-table-border-color: #dddddd;
--data-table-color-hover-area: #ffeba0;
--data-table-color-footer-area: var(--data-table-color-base);
```

### 自定义单元格颜色

表格单元格可以使用任意样式来渲染. **如果使用错误,它可能会打破布局!**

### 使用非标准字体的反应数据表

使用时 `stickyHead` 表格数据的道具和非标准字体、页眉列和表格列的大小可能不匹配。 如果表格数据已经装入,且表格在浏览器装入特定字体之前已经提供,这可能是问题所在.

为了避免这个问题,在渲染表格前先加载所希望的字体. 你可以一举一动 采用下列方式:

1.  使用 `<link rel="preload">` 输入 `<head>` hTML 代码的元素

```html
<head>
  <meta charset="utf-8" />
  <title>Web font example</title>

  <link
    rel="preload"
    href="fonts/my-font.woff2"
    as="font"
    type="font/woff2"
    crossorigin="crossorigin"
  />
  <link
    rel="preload"
    href="fonts/my-font.woff"
    as="font"
    type="font/woff"
    crossorigin="crossorigin"
  />
  <link
    rel="preload"
    href="fonts/my-font.ttf"
    as="font"
    type="font/ttf"
    crossorigin="crossorigin"
  />

  <link href="style.css" rel="stylesheet" type="text/css" />
</head>
<body>
  ...
</body>
```

请注意,在这种情况下,字体在接收并加载页面上的所有内容之前被加载. 如果您只使用此字体来渲染您的服务中的表格, 而表格不是您服务的核心, 用户将不得不等待他们可能再也不需要的字体上传 。 这种方法也不受一些现代浏览器的支持. 更多关于这个 [这里](https://developer.mozilla.org/ru/docs/Web/HTML/Preloading_content)。 。 。 .

2.  使用 [字体面视图](https://github.com/bramstein/fontfaceobserver) 软件包

要从 JS 代码中装入一个字体, 首先用 CSS 代码中的 @ font-face 指令来定义 :

```scss
@font-face {
  font-family: 'My font';
  src: url('fonts/my-font.woff2') format('woff2'),
       url('fonts/my-font.woff') format('woff');
       url('fonts/my-font.ttf') format('ttf');
  font-weight: 400;
  font-style: normal;
}
```

然后可以直接为表格本身加载数据来预装字体.

对于一个字体面:

```js
import FontFaceObserver from 'fontfaceobserver';

function preloadTableFont() {
    return new FontFaceObserver('My font').load();
}

function fetchData() {
    ...
}

function getTableData() {
  return Promise.all([
    fetchData(),
    preloadTableFont(),
  ])
  .then([data] => {
    ...
  })
  .catch((err) => {
    ...
  })
}
```

对于多字体面相 :

```js
import FontFaceObserver from 'fontfaceobserver';

const lightFont = new FontFaceObserver('My font', {weight: 300});
const regularFont = new FontFaceObserver('My font', {weight: 400});

function preloadTableFont() {
    return Promise.all([
        lightFont.load(),
        regularFont.load(),
    ]);
}

function fetchData() {
    ...
}

function getTableData() {
  return Promise.all([
    fetchData(),
    preloadTableFont(),
  ])
  .then([data] => {
    ...
  })
  .catch((err) => {
    ...
  })
}
```

这种方法得到浏览器的全力支持,只允许您为打开表格的用户下载字体.

### 使用量

```jsx
const data = [];
const columns = [];
const startIndex = 0;

return <DataTable data={data} columns={columns} startIndex={startIndex} />;
```

更多信息见样本代码.

## 常见问题

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

数据表组件

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

在项目目录运行 npm install @gravity-ui/react-data-table，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

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

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

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

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

