PPTX

解析

使用 parsePresentation 和 parsePptx 读取现有 .pptx 文件

解析现有 .pptx 文件，将其转换为结构化数据，用于检查、修改或往返（round-trip）工作流。

parsePresentation

高级 API，将 .pptx 文件解析为 PresentationOptions，可直接传给 generatePresentation()。parsePresentation 和 parsePptx 均接受任意 DataType 输入。

import { parsePresentation, generatePresentation } from "@office-open/pptx";
import { readFileSync, writeFileSync } from "node:fs";

const opts = parsePresentation(readFileSync("input.pptx"));

// 重新创建并导出
const buffer = await generatePresentation(opts);
writeFileSync("output.pptx", buffer);

解析后的演示文稿结构

parsePresentation 返回 PresentationOptions 对象：

属性	类型	说明
`slides`	`SlideOptions[]`	幻灯片选项数组
`masters`	`MasterDefinition[]`	母版定义（仅多母版时存在）
`title`	`string`	文档标题（来自核心属性）
`creator`	`string`	文档创建者（来自核心属性）
`size`	`SlideSize`	幻灯片尺寸（"16:9"、"4:3" 或自定义）
`show`	`ShowOptions`	幻灯片放映设置

解析后的幻灯片结构

每张解析后的幻灯片是一个 SlideOptions 对象：

属性	类型	说明
`children`	`SlideChild[]`	形状、表格、图表、连接器等
`background`	`BackgroundOptions`	幻灯片背景（纯色/渐变）
`transition`	`TransitionOptions`	幻灯片切换效果
`notes`	`string`	演讲者备注文本
`layout`	`SlideLayoutType`	版式类型（如 "blank"、"title"）
`master`	`string`	母版名称（多母版文件中）
`comments`	`SlideCommentOptions[]`	幻灯片批注（作者、文本、位置）

解析后的幻灯片子元素

每个子元素使用带识别键的联合类型：

// 形状
{ shape: { x, y, width, height, textBody, fill, outline, effects, geometry, ... } }

// 表格
{ table: { x, y, width, height, rows, columnWidths, firstRow, bandRow, ... } }

// 图表
{ chart: { x, y, width, height, type, title, categories, series, showLegend } }

// SmartArt
{ smartart: { x, y, width, height, nodes, layout, style, color } }

// 连接器
{ connector: { x1, y1, x2, y2, beginArrowhead, endArrowhead, outline } }

// 分组
{ group: { x, y, width, height, rotation, children } }

// 图片
{ picture: { x, y, width, height, data } }

// 线条
{ line: { x1, y1, x2, y2, outline, ... } }

// 视频
{ video: { x, y, width, height, data, type, poster?, ... } }

// 音频
{ audio: { x, y, width, height, data, type, ... } }

往返示例

解析文件、修改后导出：

import { parsePresentation, generatePresentation } from "@office-open/pptx";
import { readFileSync, writeFileSync } from "node:fs";

const parsed = parsePresentation(readFileSync("template.pptx"));

// 在末尾添加新幻灯片
parsed.slides!.push({
  children: [
    {
      shape: {
        x: "2.6cm",
        y: "2.6cm",
        width: "15.9cm",
        height: "10.6cm",
        fill: "4472C4",
        textBody: { text: "新幻灯片" },
      },
    },
  ],
});

const buffer = await generatePresentation(parsed);
writeFileSync("modified.pptx", buffer);

或直接使用 JSON API：

{
  "children": [
    {
      "shape": {
        "x": "2.6cm",
        "y": "2.6cm",
        "width": "15.9cm",
        "height": "10.6cm",
        "fill": "4472C4",
        "textBody": { "text": "新幻灯片" }
      }
    }
  ]
}

{
  children: [
    {
      shape: {
        x: "2.6cm",
        y: "2.6cm",
        width: "15.9cm",
        height: "10.6cm",
        fill: "4472C4",
        textBody: { text: "新幻灯片" },
      },
    },
  ],
}

parsePptx

底层 API，返回原始文档结构，用于高级场景：

import { parsePptx } from "@office-open/pptx";

const pptx = parsePptx(buffer);

PptxDocument API

属性	类型	说明
`doc`	`ParsedArchive`	底层归档对象，可按路径访问各部件
`presentation`	`Element`	`p:presentation` 根元素
`slides`	`string[]`	幻灯片路径（如 `ppt/slides/slide1.xml`）
`slideMasters`	`string[]`	幻灯片母版路径
`slideLayouts`	`string[]`	幻灯片版式路径
`notesSlides`	`string[]`	备注幻灯片路径
`partRefs`	`PptxPartRefs`	媒体、图表、主题等引用
`presProps`	`string`	演示文稿属性路径
`viewProps`	`string`	视图属性路径
`coreProps`	`string`	核心（Dublin Core）元数据路径
`appProps`	`string`	应用程序属性路径

访问文档部件

const pptx = parsePptx(buffer);

// 读取幻灯片的原始 XML
const slideEl = pptx.doc.get(pptx.slides[0]);

// 列出所有媒体文件
console.log(pptx.partRefs.media);

// 访问图表数据
for (const chartPath of pptx.partRefs.charts) {
  const chartEl = pptx.doc.get(chartPath);
}

支持的解析功能

功能	详情
形状	位置、几何形状、填充（纯色/渐变/图案/图片）、轮廓、效果
表格	行、单元格、列宽、表格样式标志、边框
图表	类型、标题、分类、数据系列、图例可见性
SmartArt	节点树结构、布局、样式、配色
连接器	位置、箭头、轮廓
分组	位置、旋转、嵌套子元素
图片	位置、嵌入图片数据
线条	位置（x1/y1/x2/y2）、轮廓含虚线样式
视频	位置、嵌入视频数据、海报帧
音频	位置、嵌入音频数据
切换效果	类型、速度、方向
背景	纯色和渐变填充
备注	演讲者备注文本
动画	进入/退出/强调类型、触发方式、延迟、持续时间
批注	作者、文本、位置、日期
效果	外阴影、内阴影、发光、倒影、柔化边缘
富文本	粗体、斜体、下划线、删除线、字体、字号、颜色、间距

浏览器使用

const fileInput = document.querySelector("input[type=file]");
const file = fileInput.files[0];
const arrayBuffer = await file.arrayBuffer();

const opts = parsePresentation(arrayBuffer);
console.log("幻灯片数量:", opts.slides?.length);

提示

parsePresentation 返回纯对象，兼容 JSON API — 使用 { shape: {...} } 风格，而非 new Shape()。
解析后的数据可直接传给 generatePresentation(parsed) 实现完整往返。
masters 仅在文件包含多个幻灯片母版时才有值 — 单母版文件返回 masters: undefined。
当需要底层访问 XML 部件或关系数据时，使用 parsePptx。
并非所有 PPTX 功能都能在解析过程中完全保留 — 请使用你的具体文件进行测试。

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

导出

将演示文稿导出为 Buffer、Blob、Base64 或流

补丁

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