功能限制

使用前请阅读

pptx-viewer 覆盖了 OpenXML 规范的较大范围，但部分功能采用近似实现、仅支持读取，或受浏览器平台限制。本页记录已知限制，不代表对所有 Office 功能和第三方扩展的完整兼容性保证。加载演示文稿后请检查 data.warnings；正式的覆盖清单见 OpenXML 支持情况。

核心引擎（pptx-viewer-core）

功能	状态	说明
.ppt 导出	部分支持	墨迹、SmartArt、图表和三维模型会通过内嵌的 OOXML 往返数据包，在 PowerPoint 中重新打开为可编辑对象；每种图片格式都按照 PowerPoint 自身 97-2003 保存的方式嵌入（PNG、原生 EMF/WMF、DIB、栅格化的 SVG）；母版带有演示文稿自身的标题、正文和其他文本样式、占位符形状（标题、正文、日期、页脚、幻灯片编号）以及主题，因此 PowerPoint 报告的是演示文稿自身的母版样式、主题颜色和字体；组合、表格（按 PowerPoint 2003 的做法写为单元格矩形组合）以及超过 7 MB 的文件都能打开（均已通过 COM 在 PowerPoint 中重新打开验证）。视频以及非 WAV 音频会写为其海报图片，这与 PowerPoint 自身 97-2003 保存的结果完全一致。没有栅格回退的 SVG 图片会在浏览器中栅格化，在 Node.js 中则通过可选的 @napi-rs/canvas 对等依赖栅格化（只有两者都不可用时才使用占位符）。PowerPoint 写入的受密码保护 .ppt 文件（RC4 CryptoAPI）可凭密码打开，本写入器保存的加密 .ppt 也能在 PowerPoint 中打开。尚未解决：只写入第一张幻灯片的母版，因此包含多个母版的演示文稿的每张幻灯片都会使用这一个母版；GIF 图片的第一帧会存为 PNG（与 PowerPoint 自身 97-2003 保存一致），但未压缩，因此大型 GIF 生成的文件比 PowerPoint 写入的大得多。详见 OpenXML 支持情况。
SmartArt 布局	缺少缓存绘图时采用近似布局	未保存缓存 dsp:drawing 的演示文稿由逐数据点的 DiagramML 引擎（143 种布局）或较早的按族解释器计算布局。在 229 个通过 COM 创建的图库测试样例中，228 个能生成与 PowerPoint 相同的形状集合，143 个的几何形状误差在 1% 以内（181 个在 5% 以内），129 个的每个字号都一致。Name and Title Organization Chart、带标签的层次结构和表格层次结构、带助理的水平组织结构图以及三种布局（Arrow Ribbon、Balance、Varying Width List）仍不精确。测量依据见 OpenXML 支持情况。

动画编辑

在动画面板中创建的效果会合并到幻灯片已有的 p:timing 树中，演示文稿原有的效果保持字节不变。已知的功能缺口：

• 方向仅涵盖边和角的变体。 每个进入和退出效果都按照 PowerPoint 自身针对其预设和方向的行为树保存；更改现有效果的预设或方向会重建该行为树，新的持续时间会重新调整其时间（通过 COM 在 PowerPoint 中重新打开后，其自身的渲染与在 PowerPoint 中创建的效果逐帧一致）。方向选择器只提供 PowerPoint 具有的变体：飞入和爬入提供全部八个方向，擦除、切入和伸展提供四条边（React 的选择器尚无四角选项，因此飞入和爬入只提供四条边）。劈裂、缩放、百叶窗和形状显现效果保持默认变体，浮入没有方向（上浮和下浮是独立的预设），闪烁为近似实现。
• 部分预设在播放时采用近似效果。 进入和退出效果按演示文稿自身的行为树播放：包括其公式、每个行为各自的时间与加减速、沿路径长度匀速移动的动作路径、淡化和擦除，因此飞入会像 PowerPoint 一样从幻灯片边缘外侧开始。与 PowerPoint 的 CreateVideo 渲染逐帧对比 116 种预设与方向变体（200 磅形状、2 秒），可见形状与 PowerPoint 的平均偏差约在 15 像素以内；旋转和淡化旋转仅在宽度经过零的瞬间有所不同，向上弧线在其曲线开始阶段最多偏离 75 像素。仍为近似实现：彩色打字机播放替代效果，方框、圆形、菱形和加号退出效果忽略其方向，强调效果使用预设关键帧。
• 部分支持： 100% 的 p14:bounceEnd（已无移动行程，PowerPoint 自身的渲染也不稳定）会被限制为 95%。基于媒体书签的触发器（“书签时”）、带方向选项的 p15 系列切换效果，以及缩放切换效果的放大/缩小方向，均可在全部五个绑定中创建；“弹跳结束”的回弹曲线已按 PowerPoint 自身的帧拟合。

运行时检测兼容性问题

无需猜测某个文件是否触及功能限制。加载流程会将许多（但并非全部：例如动画替代效果不会产生任何警告）不支持或近似处理的结构记录在 data.warnings 中，其类型为 PptxCompatibilityWarning：

interface PptxCompatibilityWarning {
	code: string; // stable machine-readable code
	message: string;
	severity: 'info' | 'warning';
	scope: 'presentation' | 'slide' | 'element' | 'save';
	slideId?: string; // present for slide/element-scoped warnings
	elementId?: string;
	xmlPath?: string; // where in the package the construct lives
}

如果应用需要向用户提示还原度问题，或根据文件情况决定启用哪些功能，请在 load() 后检查 data.warnings，并在 save() 后再次检查。

各部分（浏览器 / Node.js / Web Worker）的运行范围，以及源于浏览器沙箱而非功能缺失的平台相关行为，见运行环境。

各框架组件（React、Vue 3、Angular、Svelte 5、原生 JavaScript）

基于 CSS 的渲染需要对部分视觉效果作出取舍

幻灯片通过 HTML/CSS 而非 Canvas 显示，可以提供缩放后依然清晰的文本、原生无障碍能力和 DOM 交互。相应的取舍是：少数 PowerPoint 效果没有完全对应的 CSS 表达方式，需要近似处理。

近似实现的视觉效果

效果	状态	说明
三维形状和场景（a:sp3d / a:scene3d）	金属材质仍有残留误差	金属材质此前在高仰角光照下会出现过度泛白；现在高光拥有独立的、有上限的仰角，并根据 134 张 PowerPoint 渲染结果重新拟合（在 0-255 的量级上，平均绝对误差从 75.0 降到 36.4），因此仍存在较小的残留误差。2026-09-16 针对 relaxedInset/slope/hardEdge 棱台的修复，尚未针对新的 PowerPoint 渲染结果重新验证。依据见视觉效果还原。
艺术字包络变形（inflate / deflate / can / slant / fade / cascade / ...）	can 预设在部分深度下不精确	字形按沿上、下曲线的弧长放置。已对照 PowerPoint Slide.Export 重新测量（宽 1920 px，Noto Sans、Verdana 和 Arial，2026-09-25）：在大多数深度下，can 预设的墨迹 IoU 为 0.94-0.97，平均轮廓误差 0.8-1.7 px（第 95 百分位 1.5-6 px），inflate / deflate 为 0.96-0.97。在扫描的 20 个 adj 值中有 9 个（textCanUp 80000-93333，textCanDown 3333-23333），PowerPoint 会让一行或两行文字提前约框宽的 1.2% 结束并使字形倾斜；此行为尚未建模（这些情况下 IoU 为 0.73-0.86）。无法获取字体文件的字体使用从浏览器自身渲染描出的轮廓，与真实字体文件的差异在 0.002 IoU 以内。参见视觉效果保真度。

倒影、柔化边缘和路径渐变也采用近似实现，但与真实 PowerPoint 的对比结果较为接近。各自的实现方法和 COM 测量依据见视觉效果还原。

已知的渲染与编辑缺口（2026-09 审查）

2026 年 9 月针对真实 PowerPoint 的一次审查发现了以下仍未解决的缺口：

• 保存编辑过的幻灯片仍可能改动少量标记细节。 公式、换行、继承的格式、母版文本样式、主题背景、批注时间戳、图片填充、媒体单击动作、文本片段的语言和属性、注音（ruby）片段、轮廓宽度、内阴影颜色、渐变内边距、继承项目符号上的项目符号颜色、制表位对齐方式，以及动画和音频元数据、未改动的图表现在都能正确往返，docProps 会在保存时按照 PowerPoint 的方式刷新。空的 <a:pPr/>、没有任何内容的 <a:p/>、备注中的 endParaRPr 和 prstTxWarp/avLst 在重写后的幻灯片上都能保留，docProps/app.xml 中的字数和段落数会按照 PowerPoint 的计数方式，根据幻灯片、备注和 SmartArt 的文本重新计算（已通过 COM 验证）。重写后的幻灯片上仍有少量残留：图片上空的 <a:extLst/> 和视频的 showWhenStopped 标志可能会丢失。未编辑的幻灯片可以干净地往返。
• 图表： 位于 bestFit 位置的饼图外侧标签相互重叠时，PowerPoint 会把它们错开并为移动过的标签绘制引导线，这一点尚未实现。采用自动绘图区的饼图也比 PowerPoint 绘制得略大（小图表中最多约 8%）。显示类别名称和百分比但没有 c:separator 的数据标签会用 ", " 连接绘制在一行中，而 PowerPoint 会把它们放在两行。
• 三维模型 会忽略在 PowerPoint 中设置的相机、变换和灯光。
• 编辑器功能覆盖 仅是 PowerPoint 的一个子集：多个功能区图库尚不可用。编辑顶点（以及“任意多边形：形状”和“曲线”绘图工具）、合并形状、画布上的图片裁剪（裁剪手柄、按纵横比裁剪、填充、适应）、选择性粘贴、空白画布与元素的上下文菜单、幻灯片窗格多选、真实的就地动画预览以及标准编辑快捷键已在全部五个绑定中可用。

EMF/WMF 图元文件（emf-converter 依赖）

实现位于独立项目

emf-converter 是拥有独立仓库的 npm 包，pptx-viewer-core 只是使用它。下表记录该包当前的行为；如果两者不一致，请以该包自身的版本说明为准。

需要 Canvas API

图元文件转换需要 OffscreenCanvas 或 HTMLCanvasElement。未提供 Canvas polyfill 的纯 Node.js 环境无法处理 EMF/WMF 图像（核心引擎的其他功能在 Node 中仍可正常运行）。

功能	状态	说明
渐变画刷和纹理画刷	重采样残留误差	渐变、图案画刷和 EMF+ 纹理画刷（自 3.3.0 起也包括压缩位图）可精确渲染色标和平铺；浏览器的图案过滤与 Windows GDI+ 相比会留下细微的边缘平滑差异（测量结果见该包的 README）。
光栅操作	精确	全部 256 种 ROP3 代码和所有按位 ROP2 画笔模式均可精确求值，包括 BeginPath/EndPath 路径内部（自 3.3.0 起）。
文本和变换	使用浏览器字体引擎	字形度量可能与 Windows GDI 不同：会遵循 ExtTextOut 的 dx 数组、LOGFONT 高度的正负号以及 escapement 角度，但没有 dx 数组时，字形间距取决于浏览器的字体替换。旋转和倾斜的世界变换会应用于形状、位块传输（blit）和文本（自 3.3.0 起）；倾斜下的文本使用单一旋转角度。

相关阅读

• 项目介绍：了解项目整体支持的功能。
• 架构说明：了解这些取舍背后的原因。
• OpenXML 支持情况：覆盖清单中“支持”的正式定义。
• 视觉效果还原：通过真实 PowerPoint 验证的 CSS/SVG 近似效果。
• 运行环境：各部分的运行范围及浏览器沙箱相关说明。