# @betteroffice/xlsx 中文文档

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

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

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

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

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

- 包体积（解压后）：8 MB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-12T17:18:05.720Z
- 最新版本发布：2026-10-27T11:28:12.309Z
- 近 30 天下载量：363474（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

Excel-feelful XLSX电子表格编辑器和取景器核心:全OOXML忠心,实时人类+AI代理协作. 无框架(Rust/Wasm).

## 安装

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

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

## README

# @ betteroffice/ xlsx (韩语)

无框架 XLSX 解析、公式计算、编辑和渲染 发动机。 包括画布画、取景口、点击测试、无障碍和剪贴板帮助.

## 安装

```bash
bun add @betteroffice/xlsx
```

无对等依存.

## 使用量

工作表、行和列指数都是零的,所以 `editCell(0, 9, 2, ...)` 在单元格 C10 上写入 第一页.

```ts
import { initWasm, openWorkbook } from '@betteroffice/xlsx';

export async function updateWorkbook(bytes: Uint8Array): Promise<Uint8Array> {
  await initWasm();
  const workbook = openWorkbook(bytes);
  try {
    workbook.editCell(0, 9, 2, '=SUM(C1:C9)');
    return workbook.save();
  } finally {
    workbook.dispose();
  }
}
```

单元格输入解析文本、数字、布尔和公式; 公式从 `=`。编辑单元格重新计算其依赖.

## 入境点

这些入境点出口自 `@betteroffice/xlsx`数字 :

| 进入点 | 说明 |
| --- | --- |
| `initWasm(input?)` | 初始化引擎;同时调用共享初始化. |
| `openWorkbook(bytes, options?)` | 打开 XLSX 字节作为同步 `WorkbookHandle` 初始化后. |
| `openWorkbookSession(bytes, options?)` | 在有同步接入功能的专职工人中打开工作手册. |
| `paintDisplayList(ctx, frame, dpr, origin?)` | 将显示列表绘入画布 2D 上下文 . |
| `isPngExportAvailable()` | 检查初始化引擎是否支持PNG导出. |
| `isProposalsAvailable()` | 检查初始化引擎是否支持编辑提案. |
| `exportXlsxStructured(bytes, options?)` | 从字节同步导出存储的工作簿内容 . |
| `exportXlsxMarkdown(bytes, options?, markdownOptions?)` | 从字节同步导出 Markdown . |

`initWasm()` 默认加载已装入的 WASM 资产。 通过 WASM 字节或编译 `WebAssembly.Module` 在无法获取此 URL 的运行时间中。 完成后处理工作簿手柄.

## Canvas 渲染和网格辅助工具

`WorkbookHandle.displayList(viewport)` 返回活动工作表的显示列表。 备份存储大小 对于设备像素比,并给出其逻辑 CSS 维度 :

```ts
import { paintDisplayList, type WorkbookHandle } from '@betteroffice/xlsx';

export function drawWorkbook(workbook: WorkbookHandle, canvas: HTMLCanvasElement) {
  const dpr = window.devicePixelRatio || 1;
  canvas.width = 800 * dpr;
  canvas.height = 600 * dpr;
  canvas.style.width = '800px';
  canvas.style.height = '600px';
  const ctx = canvas.getContext('2d');
  if (!ctx) throw new Error('Canvas 2D is unavailable');
  const frame = workbook.displayList({ x: 0, y: 0, width: 800, height: 600 });
  paintDisplayList(ctx, frame, dpr);
}
```

用于自定义网格 `cellAtPoint`, (中文(简体) ), `cellRect`,以及 `rangeRect` 用于测试和几何, `buildA11yGrid` 用于获取数据,以及 `toTsv` 编号 : `fromTsv` 用于剪贴板文本. 这个 `@betteroffice/xlsx/headless` 输入导出纯网格助手和类型而不包含画画 或WASM装载机.

## 范围移动

`workbook.moveRange(sheet, source, destination)` 在工作表中移动 A1 区域并重写 引用一个倒移步骤; 目的地是新的左上单元格。 移动时的表面错误 拒绝而不是丢弃原始工作手册.

## 打印和PNG 导出

`workbook.printDisplayList(sheet, range, metrics, gridlines)` 使用 `PrintMetrics` 从工作簿的普通字体中测量。 呼叫者选择纸张大小、边距和页码; `paintDisplayList` 接受支持存储像素中的可选来源,用于定位结果.

`workbook.renderPng(viewport)` 导出活动工作表的视图. `workbook.renderRangePng()` 出口 使用范围,或接受 `{ range, scale }` 以选择 A1 范围和光栅尺度。 两人返回PNG 字节同步; 检查 `isPngExportAvailable()` 在叫他们之前.

## 工人会议

低层 `openWorkbookSession` API( 也从 `@betteroffice/xlsx/worker`)为 实验 它返回一个 `WorkbookSession` 与 通过承诺返回业务 `session.call`,加同步键 `session.save()` 财务报告和审定财务报表 `session.dispose()` 方法。 。 .

React编辑器默认使用工人并暴露出自己的同步API. 使用 [`@betteroffice/xlsx-react`](https://www.npmjs.com/package/@betteroffice/xlsx-react) 为编辑UI.

## 编辑建议

`workbook.propose(agentId, note, edits)` 阶段单元格编辑以供审查而不应用. `listProposals`, (中文(简体) ), `acceptProposal`,以及 `rejectProposal` 管理队列; 接受应用 作为撤消步骤并重新计算受抚养人的建议。 检查 `isProposalsAvailable()` 首先是:; 接受掷出 `StaleProposalError` 如果目标细胞在集结后有所改变.

## 版本已检查的编辑批次

`readCells` 返回带有其版本的单元格; `validateEdits` 检查一批没有承诺, 财务报告和审定财务报表 `applyEdits` 应用所有步骤或返回打入的拒绝,而不修改工作簿. 见 [在版本检查的批次中编辑 XLSX](https://docs.betteroffice.dev/docs/javascript#edit-xlsx-in-version-checked-batches) 对于目标,守卫, 支持的步骤,和限制.

## 有结构的出口

`exportStructured` 财务报告和审定财务报表 `exportMarkdown` 用定位锚和诊断读取承诺内容 不计算公式。 见 [用锚导出 XLSX 内容](https://docs.betteroffice.dev/docs/javascript#export-xlsx-content-with-anchors) 用于范围、隐藏内容、限制和以字节为基础的出口.

## 协作

这个 `@betteroffice/xlsx/collaboration` 进口 `CollaborationProvider` 用于连接复制品 到二进制运输。 见 [协作指南](https://docs.betteroffice.dev/docs/collaboration) 供货商生命周期、运输装置和共享起始状态.

打开工作簿 `openWorkbook(bytes, { collaborative: true })`合作工作手册 同步单元格内容、公式、样式、列宽和行高,与本地撤销和 重做它的效果同步. 结构编辑:插入或删除行和列,添加、去除、移动或重命名 工作表,并更改图表或定义的名称.

## 操作简介

`editCellProfiled`, (中文(简体) ), `applyOpsProfiled`,以及 `displayListProfiled` 返回引擎阶段持续时间 毫秒与结果。 见 [操作简介](https://docs.betteroffice.dev/docs/javascript#operation-profiles)。 。 。 .

## 文档

-   [Java脚本指南](https://docs.betteroffice.dev/docs/javascript)
-   [软件包指南](https://docs.betteroffice.dev/docs/packages)
-   [Npm 上的反应编辑器](https://www.npmjs.com/package/@betteroffice/xlsx-react)
-   [仓库](https://github.com/openooxml/betteroffice)

## 常见问题

### @betteroffice/xlsx 是什么？

Excel-feelful XLSX电子表格编辑器和取景器核心:全OOXML忠心,实时人类\+AI代理协作\. 无框架\(Rust/Wasm\)\.

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

在项目目录运行 npm install @betteroffice/xlsx，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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