@office-kit/xlsx

项目简介

Office Kit 的 xlsx 库可在 Node 22+ 和现代浏览器中用 TypeScript 读取、编辑和写入 Excel .xlsx 工作簿。它提供类型化的单元格值、样式、公式、图表和流式处理，并逐字节保留其未建模的功能。

核心功能

• 从字节、文件、Blob 或 fetch 响应读取和写入 .xlsx 工作簿，单元格值建模为可辨识联合类型。
• 支持写入样式、数字格式、带缓存值的公式、Excel 表格、数据验证、条件格式、图片、图表和图表工作表。
• 面向大型工作表的流式读取器和仅追加写入器，具有有界的行缓冲和共享字符串限制。
• 往返保留未建模的部分，包括数据透视表、VBA 项目、线程化评论、外部链接和自定义 XML。
• 在 CI 中依据 ECMA-376 架构以及语义不变量验证生成的 OOXML。
• 子路径导入，具有可摇树优化的 ESM 导出，且没有根 barrel。

适用场景

• 以编程方式编辑现有 Excel 报告或模板，同时保持数据透视表、宏和其他未建模部分不变。
• 通过流式写入生成大型 .xlsx 文件，以保持内存占用有界。
• 从 TypeScript 创建带格式、图表、图片、验证和条件格式的类型化 Excel 工作簿。
• 在 Node 服务或浏览器应用程序中读取和验证上传的 .xlsx 文件，使用类型化单元格值和错误类。

快速开始

• 使用 pnpm add @office-kit/xlsx 安装，或使用 npm、yarn 或 bun。需要 Node 22 或更高版本；该包仅提供 ESM，且没有根 barrel。使用 loadWorkbook 加载工作簿，使用 setCell 编辑单元格，然后使用 workbookToBytes 或 saveWorkbook 保存。对于大型工作表，使用 createWriteOnlyWorkbook 追加行，然后 finalize。

部署与要求

• 需要 Node 22 或更高版本；不支持 Node 18 和 20 EOL。可在 Node 和现代浏览器中运行；只有 @office-kit/xlsx/node 子路径会触及 fs，其余部分使用 Web Streams、Blob 和 Uint8Array。该包仅提供 ESM，其随附的类型可在 node16、nodenext 和 bundler 模块解析下解析。完整的加载和保存路径必须保持在 120 KB 以下（压缩并 brotli 压缩后），流式入口低于 80 KB。

采用前须知

• 许可证：MIT。在使用、修改或分发项目前，请确认其具体条款。