# @bsuite/data-grid 中文文档

规范地址：https://npmcn.com/package/%40bsuite/data-grid/

版本：3\.0\.5
npm 元数据更新时间：2026-10-20T18:04:55.897Z
中文译文更新时间：2026-11-08T20:55:56.731Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：266 kB，98 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，@tanstack/react-table ^9\.2\.4
- 首次发布：2026-08-07T02:32:56.278Z
- 最新版本发布：2026-10-20T18:04:55.424Z
- 近 30 天下载量：2077（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

虚拟化,BSuite应用软件的电子表格-feel数据网格——单元格范围选择,键盘网格导航,TSV剪贴板回转,填充手柄,撤销/重做. 建于 @tanstack/ react-table + @tanstack/react-vitual上.

## 安装

```sh
npm install @bsuite/data-grid
```

也可以使用：`pnpm add @bsuite/data-grid`、`yarn add @bsuite/data-grid`、`bun add @bsuite/data-grid`

## README

# @bsuite/data-grid (中文(简体) )

## 部分持久性结果

`onCellsEdited` 仍然接受同步或同步 `void` (每个单元格) 已成功). 独立保存批次的主机可以返回 `CellEditResult`数字 :

```tsx
<DataGrid
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  onCellsEdited={async (edits) => {
    const failures: CellEditFailure[] = [];
    for (const edit of edits) {
      try {
        await saveCell(edit.rowId!, edit.columnId, edit.value);
      } catch (error) {
        retainRetryDraft(edit); // Host-owned draft, separate from the grid's data.
        failures.push({
          rowId: edit.rowId!,
          columnId: edit.columnId,
          status: 'failed',
          message: error instanceof Error ? error.message : undefined,
        });
      }
    }
    return { failures };
  }}
  onError={showSaveError}
/>
```

导入 `CellEditFailure` 财务报告和审定财务报表 `CellEditResult` 从 `@bsuite/data-grid`编辑 电网排放的电网包括: `rowId`; 字段仍然是可选的 `CellEdit` 用于与现有的主机创建对象兼容。 使用匹配结果 `rowId` 财务报告和审定财务报表 `columnId`,从不使用当前显示索引. `getRowId` 必须返回 当行可以被重新排序或被过滤时,独特的,稳定的记录标识符. 这个 遗留索引回落无法识别整个主机数据重排的记录 .

每个省略的单元格都成功。 失败要求 `status: 'failed'`· ; `message` 是可选的,默认为“未能保存编辑”。 未知或重复 身份使结果无效,并将提交的单元格报告为失败 主机在重试不确定的写入前必须刷新 。 拒绝召回 继续表示整批失败。 因此,部分储蓄者必须返回 失败的子集, 而不是在一些写成功之后扔出 . 每个 `applyCells` (或重试) 调用解决 与收货 准确 引用,即使较新的尝试后来会取代其一个或多个单元格.

删除失败的乐观值并显示相应的单元格 拒绝消息。 主机数据/调试控制其显示值; 丢弃 a 主机重试草稿不能留下隐藏的网格上覆。 成功覆盖 保留到主机数据确认该值,然后释放后期服务器 更新可见. 主机必须更新或取消其权威数据 坚持不懈。 新的编辑可以澄清单元格的旧拒绝.

撤消只包含成功的单元格 。 部分撤销并重做移动成功 与历史相反的单元格,并将被拒绝的单元格保留在原侧 用于重试。 本地拒绝使用不可用行, 而不是发送信件到 记录现在占据其以前的指数。 等待保存可撤销;其 延迟完成无法替换更新的叠加或取消历史 .

保护每个细胞的所有权 **网格状态**,而不是数据库写入命令。 主机 必须序列化同单元格写入(包括撤销/重写)或使用服务器条件 写作。 UI 所有权检查无法取消已运行的数据库更新 . 当一个主机将整个批量的序列化, 捕捉它的许诺队列 外部渲染, 将每个批次链起来,然后不转换就恢复队列的拒绝 失败的批次成功。 保持主机草稿/错误的最新尝试所有权 州也一样. `onError` 仅接收当前拥有的失败单元格;它没有 报告属于旧尝试的 stale 失败.

## 重试保留的草案

使用 `gridRef.current.applyCells([{ rowId, columnId, value }])` 已键入 失败的值 `CellEdit`s. (中文(简体) ). 它将每个身份重新组合到当前行和 使用与直接编辑相同的拒绝、持久性和撤销管道。 这个 处理持久性结果后实现承诺;检查东道主草稿 存储任何剩余的失败。 失踪/重复身份 任何写作。 不要直接调用主机持续调用重试 : 电网拒绝和历史状态与保存断开.

所有值的突变,包括粘贴/填充/清晰/未完成/重试,都明确要求 可编辑栏. 链接字段必须使用所提供的记录拾取器和 链接突变调回; 粘贴标签绝不是记录引用.

## 执行和核查范围

这将扩展已有的网格并撤销堆栈; 没有替换引擎或新建 使用依赖性。 稳定身份跟随已安装的TanStack表9.2.4 `table_getRowId` 执行(海关提取器,否则字符串索引), 用上下文7和已安装的软件包确认 `dist/core/rows/coreRowsFeature.utils.js`。见官员 [TanStack 行身份指南](https://tanstack.com/table/latest/docs/guide/rows#row-ids)。 。 。 . 在网格内保留失败的乐观草稿的替代方案失败了 refetch/丢弃权限被否决;再试编辑属于主机.

挂载测试练习 实际网格键盘粘贴, 混合失败,回推, 撤销/重做,重排/过滤,无操作/无效行为,并重叠完成. `ui_touched=true`:在23个现有客户关系管理中,消费者的推出仍然开放 制作网站, 新的Conduit候选人表面, 其他庄园消费者. 包件测试不能确定已部署的UX接受. 消费者线路,预览 和母机的D8/活性验证.

## 每个细胞编辑限制

稳定 `3.0.5` 最终完成已出版 `3.0.5-next.0` 没有运行时间的源 变化。 开发消费者使用预览文物进行UX测试; 稳定的出版和消费者的收养仍然是单独的发行步骤。 这个 父源集成不更新任何应用程序锁文件 。 跟着 [预览发布标准](https://npmcn.com/package/docs/20260824-preview-canary-publishing-standard-v1.00A.md)。 。 。 .

使用 `isCellEditable={(row, columnId) => !row.imported}` 用于权威行 必须在可以编辑的网格内保持只读状态。 这个可选的,纯洁的, 同步上游只限制编辑:列仍需要 `editable: true`,链接字段仍然需要其现有的记录拾取器. 表示它保留了仅列可编辑性.

上游收到最新的主机行,没有乐观值. 它控制着 鼠标/键盘编辑器条目和 `aria-readonly`,粘贴/清晰/填充目标,以及 用于再试/undo/再试的突变边界. 在解析前跳过保护目标 在粘贴/填充/清除时或乐观显示; TSV 位置保留, 因此 值从不移入不同的行。 明确 `applyCells` 和历史业务 返回当前受保护单元格的正常每个细胞拒绝收据。 合格 手动兄弟姐妹在混合批量中仍然保存。 选择、导航和复制保留 可用;完全只读选择没有填充手柄。 混合选择保留 但受保护的目的地单元格保持不变.

开放编辑通过重排跟踪稳定行/列的身份和视觉坐标; 执行时再次检查权限。 如果他们的行或列消失 网格取消无形编辑, 报告没有保存编辑通过 `onError`, (中文(简体) ), 并恢复键盘输入。 在等待当前策略后排队撤消 ưμ㼯A 主机必须保留自己的服务器和突变守护: 此 API 防止不可能的UI编辑,也不提供数据库授权.

使整个电网瘫痪的替代办法会妨碍人工行的工作; 消费者事件截取会复制鼠标、键盘和键盘的突变规则, 剪贴板和历史。 一个共享的上游使这些路径保持一致。 这个 挂载回归覆盖被冻结/可滚动的单元格、连接的拾取器、混合 动态编辑/剪贴板/历史工作期间的突变范围和政策变化. 无障碍遵循 [WAI-ARIA 网格图案](https://www.w3.org/WAI/ARIA/apg/patterns/grid/)。 。 。 .

## 常见问题

### @bsuite/data-grid 是什么？

虚拟化,BSuite应用软件的电子表格-feel数据网格——单元格范围选择,键盘网格导航,TSV剪贴板回转,填充手柄,撤销/重做\. 建于 @tanstack/ react-table \+ @tanstack/react-vitual上\.

### 如何安装 @bsuite/data-grid？

在项目目录运行 npm install @bsuite/data-grid，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）、@tanstack/react-table（^9\.2\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bsuite/data-grid 支持 TypeScript 吗？

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

### @bsuite/data-grid 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bsuite/data-grid 可以商用吗？

@bsuite/data-grid 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @bsuite/data-grid 的下载量有多少？

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

### @bsuite/data-grid 还在维护吗？

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