@office-open/core
@office-open/core 是 @office-open/docx、@office-open/pptx 和 @office-open/xlsx 的共享基础设施层。通常无需直接安装——但如果你需要构建自定义 OOXML 元素或扩展库，它提供了所有构建模块。
模块概览
描述符系统
核心描述符系统提供 TypeScript Options 对象与 XML 之间的声明式双向映射。同一个描述符同时驱动序列化（Options → XML 字符串）和解析（Element → Options）。
import type { CustomDescriptor } from "@office-open/core";
所有描述符都是 CustomDescriptor<T> —— 手写 stringify() 和 parse() 方法的自定义描述符：
const myPartDesc: CustomDescriptor<MyOptions> = {
kind: "custom",
stringify(value, ctx) {
/* ...生成 XML 字符串... */
},
parse(el, ctx) {
/* ...从 XML 元素读取为 options... */
},
};
运行时函数 stringify() 和 parse() 执行实际转换：
// 序列化：Options → XML 字符串
const xml = stringify(spacingDesc, { before: 240, after: 120 }, ctx);
// <w:spacing w:before="240" w:after="120"/>
// 解析：Element → Partial<Options>
const opts = parse(spacingDesc, element, ctx);
// { before: 240, after: 120 }
值与验证
OOXML 规范值类型的运行时验证函数：
| 函数 | 说明 |
|---|---|
decimalNumber(val) | 验证并向下取整 |
hexColorValue(val) | 验证十六进制颜色 |
twipsMeasureValue(val) | TWIP 测量值 |
hpsMeasureValue(val) | 半磅测量值（字号） |
percentageValue(val) | 标准化百分比字符串 |
单位转换器
import {
convertMillimetersToTwip,
convertInchesToTwip,
convertPixelsToEmu,
convertEmuToPixels,
convertPointsToEmu,
} from "@office-open/core";
convertMillimetersToTwip(25.4); // 1440 (1 英寸)
convertPixelsToEmu(100); // 952500
convertPointsToEmu(12); // 152400
图表与 SmartArt
@office-open/docx 和 @office-open/pptx 共享的图表描述符（BarChart、LineChart、PieChart、AreaChart、ScatterChart）和 SmartArt 组件。图表 XML 生成和解析均通过描述符驱动。
DrawingML
颜色、填充、轮廓、效果和几何形状的共享基元。
密码哈希
所有包都支持用于文档保护的明文 password 字段。核心加密模块实现了 ECMA-376 Agile Encryption（SHA-512）：
import { derivePasswordHash } from "@office-open/core";
// 自动生成 hashValue、saltValue、spinCount、algorithmName
const derived = derivePasswordHash("secret");
// { hashValue: "...", saltValue: "...", spinCount: 100000, algorithmName: "SHA-512" }
DOCX 文档保护、PPTX 修改验证和 XLSX 工作表/工作簿保护在提供 password 字段时内部使用此模块。
该模块还导出 randomBytes(length) 用于生成密码学安全的随机字节，以及 hashPasswordAgile(password, salt, spinCount) 用于直接计算 ECMA-376 Agile Encryption 哈希。
编译与打包
generateDocument()、generatePresentation() 和 generateWorkbook() 内部使用的共享 ZIP 编译工具。通常你直接调用各格式包的顶层生成函数，而非直接使用 core：
import { generateDocument } from "@office-open/docx";
import { generatePresentation } from "@office-open/pptx";
import { generateWorkbook } from "@office-open/xlsx";
// 异步 — 默认返回 Buffer（Node.js）或 Blob（浏览器）
const buffer = await generateDocument(docOptions);
const blob = await generateDocument(docOptions, { type: "blob" });
// 也有同步变体
const buf = generateWorkbook(xlsxOptions);
异步方法使用 Web Worker 实现非阻塞 DEFLATE。同步方法会阻塞主线程，但避免了 Worker 开销。压缩策略与 Microsoft Office 一致：XML 条目使用 DEFLATE（级别 1，SuperFast）；媒体按类型区分——已压缩格式（JPEG、PNG、GIF）使用 STORE，其余（EMF/WMF/BMP/TIFF）使用 DEFLATE 级别 1。