@gravity-ui/react-data-table

中文文档
3.0.0发布于 2026/11/13MITTypeScriptCommonJS近 30 天下载 2.6万

数据表组件

中文使用文档
文档目录12 节
  1. 虚拟化和反应严格模式
  2. 属性
  3. 设置
  4. 外部服务器
  5. 栏
  6. 组
  7. 多级标题
  8. 页眉数据
  9. 定制主题
  10. 自定义单元格颜色
  11. 使用非标准字体的反应数据表
  12. 使用量

反应数据表 ^ npm package CI storybook

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

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

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

虚拟化和反应严格模式

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

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

@gravity-ui/react-data-table 处于维护模式,不会收到新功能。 我们建议迁移到 @ gravity-ui/ 表。 。 。 .

属性

财产类型需求默认说明
栏Array✓清单 表格栏
页眉数据Array将显示在标题内的数据行列表。 如果头部有粘性,行会也粘. 适用于他们与划入 data (单位:千美元)页眉数据(中文(简体) )
数据Array✓数据行列表
页脚数据Array将数据发送到表脚的行列表。 与串接方式相同 data
启动IndexNumber0初始索引(用于显示行索引)
设置Object表格设置
空数据信String"没有数据"数据为空时显示的消息
调制EmptyRowFunction空表格行的自定义渲染器,接受一列列 (columns) => ReactNode
行分类NameFunction设置字符串类的方法 (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。使用它来保存新的列宽.
可见RowIndexFunction方法 (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。否则,粘贴头将被完全禁用.
粘着TopNumber将信头贴在想要的高度( 在 DataTable.MOVING 模式)。 如果可滚动容器除表格外还包括其他内容,则使用。 如果信头不能粘住容器的边缘,最好使用精确定位的空格来使表格内容不会在信头上方凸出.
粘胶花见粘相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相类似 stickyHead 页:1 footerData
粘接点Number横行从 footerData 带有适当的下边距(在 DataTable.MOVING 模式).
同步头顶恢复Booleanfalse调整窗口大小时同步粘贴头的大小
动态内置参考React.RefObject<DynamicInnerRefT>当您想要直接调用方法时, 获取 ReactList 实例的参考文献, 例如, ReactList.scroll to (中文(简体) )。 。 。 . DynamicInnerRefT 也导出为设置,以正确定义类型,而不添加依赖工程的ReactList.
动态渲染器Booleanfalse行的动态渲染(仅视图端口). 需要特定的布局
动态招标模式String'uniform'反应List.type
动态项目大小估计器FunctionReactList. itemSize 估计器
动态项目编辑器Function反应列表. itemSizeGetter
动态渲染最小化Number1无论如何,即使少数行完全填满了容器高度(如果启用了动态渲染器,这是有道理的),也要提供最低限度的行数. 数值被传递 页:1 minSize reactList 组件属性。 。 。 .
动态渲染器使用staticSizeBooleanfalseReactList.useStaticSize (英语)
动态阈值NumberReactList.阈值
动态滚动父程序FunctionReactList.scroll 父母关系
动态渲染器FunctionReactList.scroll 父母维尤波特SizeGetter
可排序Booleantrue启用整个表格的排序
外部服务器Booleanfalse禁用组件侧的数据排序 . 更多信息
禁用重设Booleanfalse禁用排序重置( 可启用 none -> default <-> reversed default 排序方案)
默认顺序DataTable.ASCENDING DataTable.DESCENDINGDataTable.ASCENDING表格中的默认排序顺序
默认可响应Booleanfalse用于确定列是否可调整的值, 如果没有设置列的明确值
突出显示Boolean悬浮时突出显示表格行
条纹Boolean是否给偶数行配色
页眉Modmultiline pre启用多行(即 multiline )或预格式化标题( pre 数值)

外部服务器

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

  • 该表仍然是排序状态(所选列和排序方向)的主要来源,并负责根据该状态正确渲染表头.
  • 外部环境必须传递到表格中正确的排序行 props.data 答复 props.onSort 召回电话.
  • 取消列值的分组(参见 列. 组) (中文(简体) ).

栏

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

{
  "name": "column_name"
}

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

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

财产类型说明
名称string列名称和默认值 header 财务报告和审定财务报表 accessor
标题string 或者说 node列标题
标题string标题
类Namestring列类
宽度        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将相同的值组合成一个单元格,允许您创建复杂的表格. 更多细节
自动分组Boolean允许用分组对所有列进行升序排序,从而实现自动分组。 默认为 true

组

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

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

多级标题

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

页眉数据

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

定制主题

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

--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 代码的元素
<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>

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

  1. 使用 字体面视图 软件包

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

@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;
}

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

对于一个字体面:

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) => {
    ...
  })
}

对于多字体面相 :

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) => {
    ...
  })
}

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

使用量

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

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

更多信息见样本代码.

版本与发布记录

@gravity-ui/react-data-table 共发布 10 个版本,首次发布于 2023/02/03;过去 12 个月发布了 1 个版本。

版本发布日期距今
3.0.0latest2026/11/134 天前
2.2.12025/02/141.8 年前
2.1.12024/05/062 年前
2.1.02024/04/122 年前
2.0.12024/03/122 年前
2.0.02024/03/012 年前

关于 @gravity-ui/react-data-table 的常见问题

@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 和提交记录判断。