解析 - Office Open

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

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

两个函数均接受任意 DataType 输入：Uint8Array、ArrayBuffer、类型化数组视图、number[]、base64 字符串等。Blob（含 File）与 ReadableStream 输入由 async 入口接受；每个高层 parse 都有同步的 parse*Sync 对应版本，接收已归一化的字节。

#往返解析（parseWorkbook）

parseWorkbook 函数将 .xlsx 文件解析为可以传递给 generateWorkbook() 的 WorkbookOptions，支持完整的往返流程（导出 → 解析 → 重新导出）：

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

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

// 如需修改单元格，然后重新导出
const buffer = await generateWorkbook(opts);

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

json

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

#解析字段

字段	来源	说明
`worksheets`	`xl/worksheets/sheet{n}`	包含 rows 和选项的工作表数组
`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`	修订版本号
`revisionLog`	`xl/revisionHeaders.xml`	共享工作簿修订历史（见修订）

#工作表解析字段

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

#底层解析（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`	应用属性路径
`customProps`	`string \| undefined`	自定义属性路径（`docProps/custom.xml`）

#访问部件

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，修改单元格，使用 generateWorkbook() 重新导出
提取数据 -- 遍历工作表行以提取单元格值
合并工作簿 -- 解析多个 .xlsx 文件并合并其工作表
检查格式 -- 读取样式定义和数字格式
转换 -- 修改已解析的元素并重建工作簿