XLSX

解析

解析、检查和往返 .xlsx 文件

本库提供两个层级的解析 API：

parseWorkbook — 高层往返 API，返回 WorkbookOptions
parseXlsx — 底层 API，提供对 .xlsx 文件原始 XML 部件的访问

两个函数均接受任意 DataType 输入：Uint8Array、ArrayBuffer、DataView、number[]、base64 字符串等。

往返解析（parseWorkbook）

parseWorkbook 函数将 .xlsx 文件解析为与 Workbook 构造函数相同的 WorkbookOptions 格式，支持完整的往返流程（导出 -> 解析 -> 重新导出）：

import { Workbook, Packer, parseWorkbook } from "@office-open/xlsx";
import { readFileSync } from "node:fs";

// 解析已有的 .xlsx 文件
const opts = parseWorkbook(readFileSync("input.xlsx"));

// 如需修改单元格，然后重新导出
const wb = new Workbook(opts);
const buffer = await Packer.toBuffer(wb);

返回的选项包含与输入格式相同的结构：

{
  "title": "My Workbook",
  "creator": "Author",
  "worksheets": [
    {
      "name": "Sheet1",
      "children": [
        { "cells": [{ "value": "Name" }, { "value": "Score" }] },
        { "cells": [{ "value": "Alice" }, { "value": 95 }] }
      ],
      "columns": [{ "min": 1, "max": 1, "width": 15 }],
      "mergeCells": [{ "from": { "row": 1, "col": 1 }, "to": { "row": 1, "col": 2 } }],
      "freezePanes": { "row": 1 },
      "autoFilter": "A1:B2"
    }
  ]
}

解析字段

字段	来源	说明
`worksheets`	`xl/worksheets/sheet{n}`	包含 children 和选项的工作表数组
`title`	`docProps/core.xml`	工作簿标题
`creator`	`docProps/core.xml`	作者名称
`subject`	`docProps/core.xml`	主题
`keywords`	`docProps/core.xml`	关键词
`description`	`docProps/core.xml`	描述
`lastModifiedBy`	`docProps/core.xml`	最后修改者
`revision`	`docProps/core.xml`	修订版本号

工作表解析字段

字段	说明
`name`	工作表名称
`children`	行数组，每行包含 `cells`
`columns`	列定义（含宽度）
`mergeCells`	合并单元格区域
`freezePanes`	冻结窗格配置
`autoFilter`	自动筛选区域字符串
`dataValidations`	数据验证规则
`conditionalFormats`	条件格式规则

底层解析（parseXlsx）

parseXlsx 函数读取 .xlsx 文件并提供对其原始 XML 部件的访问：

import { parseXlsx } from "@office-open/xlsx";
import { readFileSync } from "node:fs";

const doc = parseXlsx(readFileSync("input.xlsx"));

// 访问工作簿元素
console.log(doc.workbook);

// 访问工作表路径
console.log(doc.worksheets);

// 访问样式元素
console.log(doc.styles);

// 访问共享字符串元素
console.log(doc.sharedStrings);

XlsxDocument API

返回的 XlsxDocument 对象包含：

属性	类型	说明
`doc`	`ParsedArchive`	完整的已解析归档（所有部件）
`workbook`	`Element \| undefined`	工作簿元素（`xl/workbook.xml`）
`worksheets`	`string[]`	工作表路径
`styles`	`Element \| undefined`	样式元素
`sharedStrings`	`Element \| undefined`	共享字符串元素
`partRefs`	`XlsxPartRefs`	图表、媒体、绘图的引用
`coreProps`	`string \| undefined`	核心属性路径
`appProps`	`string \| undefined`	应用属性路径

访问部件

const doc = parseXlsx(data);

// 通过路径获取所有部件
const workbook = doc.doc.get("xl/workbook.xml");
const styles = doc.doc.get("xl/styles.xml");
const sheet1 = doc.doc.get("xl/worksheets/sheet1.xml");

// 部件引用映射到路径
for (const path of doc.partRefs.worksheets) {
  const sheet = doc.doc.get(path);
}

操作 XML 元素

已解析的元素使用 @office-open/xml 库的 Element 类型：

import { attr } from "@office-open/xml";

// 访问元素属性
for (const child of doc.workbook?.elements ?? []) {
  console.log(child.name);
}

使用场景

往返处理 -- 解析 .xlsx，修改单元格，重新导出
提取数据 -- 遍历工作表行以提取单元格值
合并工作簿 -- 解析多个 .xlsx 文件并合并其工作表
检查格式 -- 读取样式定义和数字格式
转换 -- 修改已解析的元素并重建工作簿

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

导出

将工作簿导出为 Buffer、Blob、Base64、流等格式

补丁修改

通过替换占位符修改已有的 .xlsx 文件