# @betteroffice/xlsx-react 中文文档

规范地址：https://npmcn.com/package/%40betteroffice/xlsx-react/

版本：0\.5\.1
npm 元数据更新时间：2026-10-27T11:26:39.145Z
中文译文更新时间：2026-11-08T00:23:45.373Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40betteroffice/xlsx-react
原文对照：https://npmcn.com/package/%40betteroffice/xlsx-react/?lang=original
项目主页：https://betteroffice.dev/
源码仓库：https://github.com/openooxml/betteroffice

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

- 包体积（解压后）：494 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-07-12T17:18:24.185Z
- 最新版本发布：2026-10-27T11:26:38.461Z
- 近 30 天下载量：96842（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

Excel-finity React XLSX电子表格编辑器和取景器:全OOXML忠心,实时人类+AI代理协作.

## 安装

```sh
npm install @betteroffice/xlsx-react
```

也可以使用：`pnpm add @betteroffice/xlsx-react`、`yarn add @betteroffice/xlsx-react`、`bun add @betteroffice/xlsx-react`

## README

# @ betteroffice/ xlsx 反应

使用帆布网格,工具栏,选择,键盘输入和剪贴板支持的反应XLSX编辑器. 该引擎默认在Web Worker中运行,拥有许诺回回主机业务和出口.

## 安装

```bash
bun add @betteroffice/xlsx-react react react-dom
```

`react` 财务报告和审定财务报表 `react-dom` 18或19是同等同依存关系;XLSX核心作为依存关系列入.

## 使用量

```tsx
import { XlsxEditor } from '@betteroffice/xlsx-react';

export function Spreadsheet({ bytes }: { bytes: Uint8Array }) {
  return (
    <div style={{ height: 600 }}>
      <XlsxEditor file={bytes} fileName="report.xlsx" />
    </div>
  );
}
```

`file` 包含 XLSX 字节。 给编辑器一个高; 省略 `file` 显示为空 请求 XLSX 文件的编辑器 。 见 [托管](https://docs.betteroffice.dev/docs/migrating-to-0-5#hosting) 用于工人,块和CSP需求.

## 关键选项

默认道具由 `XlsxAsyncEditorProps`数字 :

| 道具 | 类型 | 说明 |
| --- | --- | --- |
| `file` | `Uint8Array | ArrayBuffer` | 要打开的 XLSX 字节 . |
| `fileName` | `string` | 下载名称; 默认为 `workbook.xlsx`。 。 。 . |
| `onReady` | `(api: XlsxAsyncEditorApi) => void | (() => void)` | 接收编辑器 API; 可选择返回清理 . |
| `onSave` | `(bytes: Uint8Array) => void` | 接收已保存的工作簿字节 . |
| `onSaveRequest` | `() => boolean | void | Promise<boolean | void>` | 截取保存; 返回 `true` 继续. |
| `downloadOnSave` | `boolean` | 另存下载; 默认为 `!onSave`。 。 。 . |
| `onDocumentChange` | `(change: XlsxDocumentChange) => void` | 接收 `{ version }` 在一个坚定的编辑之后. |
| `initialZoom` | `number` | 初始尺度,被夹到0.1至5;默认为1. |
| `loadingIndicator` | `React.ReactNode` | 在提供的文件打开时显示 . |
| `style` | `React.CSSProperties` | 覆盖根内线样式. |
| `onChange` | `() => void` | 在用户编辑修改工作手册后调用 . |
| `onError` | `(error: Error) => void` | 接收引擎错误 . |
| `readOnly` | `boolean` | 在保持导航和选择的同时屏蔽用户编辑. |
| `toolbar` | `React.ReactNode` | 替换默认工具栏; `null` 将取去. |
| `showToolbar` | `boolean` | `false` 隐藏工具栏区域,包括自定义内容. |
| `collaboration` | `XlsxEditorCollaborationOptions` | 配置编辑器拥有的复制和存在提供者 . |
| `i18n` | `Translations` | 覆盖使用 UI 字符串 `@betteroffice/xlsx-i18n`。 。 。 . |
| `plugins` | `readonly XlsxPlugin[]` | 安装主机插件 . |
| `pluginGrants` | `Readonly<Record<string, XlsxPluginGrant>>` | 通过插件ID授予能力. |
| `onPluginError` | `(error: XlsxPluginError) => void` | 接收插件失败 . |
| `className` | `string` | 编辑器根的 CSS 类 . |

所有列出的道具都是可选的. 默认工具栏隐藏于 `readOnly`; 供应 `toolbar` 除非 `showToolbar` 实值 `false`。 。 。 .

折旧: `legacySyncApi` 将同步 API 保留在行进引擎上, 并被删除于 0. 6. 0; 省略 默认的同步编辑器 API.

## 编辑器 API

`onReady` 接收 `XlsxAsyncEditorApi`。其出口在读取 工作簿,其命令库与工具栏和主机控件共享.

| 成员 | 目的 |
| --- | --- |
| `hydrated` | 工人编辑是否准备好. |
| `whenHydrated()` | 等待编辑准备. |
| `failure` | 当前引擎故障,或 `null`。 。 。 . |
| `commands` | 检查命令可用性并同步执行动作. |
| `version()`, (中文(简体) ), `readCells`, (中文(简体) ), `findText` | 待决输入承诺后读取 . |
| `validateEdits`, (中文(简体) ), `applyEdits` | 验证或应用版本检查的批次; 拒绝同时只读 . |
| `save()` | 提交输入、 返回字节和调用 `onSave` 无需下载或咨询 `onSaveRequest`。 。 。 . |
| `focus()` | 专注编辑. |
| `renderPng`, (中文(简体) ), `renderRangePng`, (中文(简体) ), `printDisplayList` | 同步进行. |
| `exportStructured`, (中文(简体) ), `exportMarkdown` | 同步导出内容 . |
| `proposeChanges` | 在工人编辑上进行跟踪单元格编辑的可选方法. |
| `collaboration` | 同步协作复制品,或 `null`。 。 。 . |
| `recoverySave()` | 非协作工会失败后恢复字节. |

将 API 视为属于打开文档 。 返回清理从 `onReady` 释放主机 当文档被替换或编辑器卸载时订阅.

## 保存

使用 `await api.commands.execute('save', null)` 从主机 UI 中保存 。 命令等待接受 输入和呼叫 `onSave` 当供应。 它也会下载当 `downloadOnSave ?? !onSave` 这是真的. 使用 `await api.save()` 不下载或咨询直接接收字节 `onSaveRequest`。 。 。 .

`onSaveRequest` 截取工具栏保存,保存命令,序列化前的 Ctrl/Cmd+S . 返回时 `true` 继续内置储蓄; `false` 或者说 `void` 处理或取消请求。 承诺 正在等待,同时提出的申请被合并,关于替换文件的请求被放弃.

命令返回成功或输入失败 。 被拒绝的单元格草稿必须改正或丢弃 在保存完成之前. `recoverySave()` 需要一次失败的非协作工人会议 返回时 `{ bytes, recovery: true }`。 。 。 .

## 工具栏

工具栏组成 API 是实验性. 使用 `toolbar` 以连接到 编辑器命令库. 见 [编写 XLSX 工具栏](https://docs.betteroffice.dev/docs/javascript#compose-the-xlsx-toolbar) 用于内置部件、自定义控制和命令结果.

## 插件和编辑批次

插件API是实验性的,可能会改变小放出. 插件贡献面板, 覆盖,并通过限制客户端命令;其读取和编辑 客户端支持版本检查的操作. 见 [主机 XLSX 编辑器插件](https://docs.betteroffice.dev/docs/javascript#host-xlsx-editor-plugins) 财务报告和审定财务报表 [在版本检查的批次中编辑 XLSX](https://docs.betteroffice.dev/docs/javascript#edit-xlsx-in-version-checked-batches)。 。 。 .

## 有结构的出口

等着 `api.exportStructured()` 或者说 `api.exportMarkdown()` 带有定位锚和 疏漏诊断. 见 [用锚导出 XLSX 内容](https://docs.betteroffice.dev/docs/javascript#export-xlsx-content-with-anchors) 用于范围、隐藏内容和导出限制.

## 协作

过 `collaboration` 时连接提供者 `collaboration.onReplica` 出版复制品. 编辑器保留默认的工人运行时间;参见 [协作指南](https://docs.betteroffice.dev/docs/collaboration) 用于交通设置和清理.

## 文档

-   [Java脚本指南](https://docs.betteroffice.dev/docs/javascript)
-   [协作指南](https://docs.betteroffice.dev/docs/collaboration)
-   [软件包指南](https://docs.betteroffice.dev/docs/packages)
-   [Npm 上的 XLSX 核心](https://www.npmjs.com/package/@betteroffice/xlsx)
-   [Npm 本地化软件包](https://www.npmjs.com/package/@betteroffice/xlsx-i18n)
-   [仓库](https://github.com/openooxml/betteroffice)

## 常见问题

### @betteroffice/xlsx-react 是什么？

Excel-finity React XLSX电子表格编辑器和取景器:全OOXML忠心,实时人类\+AI代理协作\.

### 如何安装 @betteroffice/xlsx-react？

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

### @betteroffice/xlsx-react 支持 TypeScript 吗？

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

### @betteroffice/xlsx-react 支持 ESM 还是 CommonJS？

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

### @betteroffice/xlsx-react 可以商用吗？

@betteroffice/xlsx-react 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @betteroffice/xlsx-react 的下载量有多少？

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

### @betteroffice/xlsx-react 还在维护吗？

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