XLSX

@office-open/xlsx

使用声明式 TypeScript API 生成、解析和修补 .xlsx 电子表格

安装

pnpm add @office-open/xlsx

npm install @office-open/xlsx

yarn add @office-open/xlsx

bun add @office-open/xlsx

快速开始

{
  "worksheets": [
    {
      "name": "Sheet1",
      "rows": [
        { "cells": [{ "value": "Name" }, { "value": "Score" }] },
        { "cells": [{ "value": "Alice" }, { "value": 95 }] },
        { "cells": [{ "value": "Bob" }, { "value": 88 }] }
      ]
    }
  ]
}

import { generateWorkbook } from "@office-open/xlsx";

const buffer = await generateWorkbook({
  worksheets: [
    {
      name: "Sheet1",
      rows: [
        { cells: [{ value: "Name" }, { value: "Score" }] },
        { cells: [{ value: "Alice" }, { value: 95 }] },
        { cells: [{ value: "Bob" }, { value: 88 }] },
      ],
    },
  ],
});

主要组件

组件	说明
`worksheets`	根工作簿配置，包含工作表和属性
`worksheet`	单个工作表，包含行、样式和功能
`rows`, `cells`, `columns`	行、单元格和列，支持值、样式、高度和宽度
`styles`	基于索引的样式系统（字体、填充、边框）
`sharedStrings`	共享字符串表，用于字符串去重（自动管理）
`table`	数据表格，支持筛选、排序和汇总行
`pivotTable`	带聚合和筛选的数据透视表
`drawing`	工作表中的图片和图表定位
`comments`	单元格批注，支持作者跟踪和富文本
`hyperlink`	外部和内部超链接
`mergeCells`	跨行跨列合并单元格
`dataValidation`	列表、数字、日期和自定义验证规则
`conditionalFormatting`	基于单元格值的格式化规则
`autoFilter`	列标题筛选下拉框
`freezePane`	冻结行和列，保持表头可见
`sheetProtection`	密码保护工作表和可编辑范围
`revisionLog`	通过修订日志跟踪更改
`pageSetup`	页面大小、边距、方向和打印设置
`headerFooter`	打印页眉和页脚

补丁修改

通过替换 {{placeholder}} 占位符来修改已有的 .xlsx 模板：

import { patchWorkbook } from "@office-open/xlsx";

const result = await patchWorkbook({
  outputType: "nodebuffer",
  data: templateBuffer,
  placeholders: {
    name: "John Doe",
    amount: 1500,
    date: new Date("2024-12-31"),
  },
});

完整文档请参阅。

解析

将已有的 .xlsx 文件解析为 WorkbookOptions，用于检查或往返工作流：

import { parseWorkbook } from "@office-open/xlsx";

const opts = parseWorkbook(buffer);
// opts.worksheets — 工作表数组
// opts.worksheets[0].rows — 包含单元格的行
// opts.title, opts.creator — 核心属性

完整文档请参阅。

导出格式

每个异步方法都有对应的同步版本（例如 generateWorkbookSync）。完整列表请参阅页面。

方法	返回值	适用场景
`generateWorkbook(opts)`	`Buffer`	Node.js 文件 I/O
`generateWorkbook(opts, { type: "blob" })`	`Blob`	浏览器下载
`generateWorkbook(opts, { type: "base64" })`	`string`	Data URL、API 负载
`generateWorkbook(opts, { type: "string" })`	`string`	调试、检查
`generateWorkbookStream(opts)`	`ReadableStream<Uint8Array>`	流式传输大文件

编辑此页面或提交问题报告

补丁

通过替换占位符、字面文本或元数据修改现有 .pptx 文件

快速开始

使用 @office-open/xlsx 在 5 分钟内创建你的第一个 .xlsx 电子表格