pptx-viewer

功能限制 ​

使用前请阅读

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

核心引擎（pptx-viewer-core） ​

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

运行时检测兼容性问题 ​

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

ts
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 验证）。未编辑的幻灯片可以干净地往返。
  • 图表： 位于 bestFit 位置且相互重叠的饼图外侧标签，会在饼图所在一侧内沿垂直方向被错开，并为每个移动过的标签绘制引导线；该间距规则为近似实现，并非通过 COM 测量得出。自动绘图区的饼图带有固定的 6.7 px 内边距，该值是按 PowerPoint 的尺寸拟合而非实测得出，因此饼图仍可能有一两个像素的差异。
  • 三维模型 会应用在 PowerPoint 中设置的相机（透视或正交、位置、向上向量、注视目标、视野）、模型变换（缩放、旋转、后置平移、每模型单位对应的米数）以及环境光、点光源、聚光灯和平行光；未设置这些的模型保持默认取景和灯光。这些尚未对照 PowerPoint 渲染结果验证：am3d:rot 的手性、am3d:preTrans 偏移（已解析但未应用）、正交缩放、光照强度单位和聚光灯锥角均为尽力实现，并且模型以其包围盒而非其设置的原点为中心。
  • 编辑器功能覆盖 仅是 PowerPoint 的一个子集。功能区样式图库（形状样式、形状效果、艺术字样式、图片样式，图片格式 > 调整中的更正、颜色和艺术效果图库，项目符号和编号库，表格样式，图表样式、图表颜色和快速布局，SmartArt 样式和更改颜色，以及设计 > 变体中的颜色和字体），以及上下文相关的形状格式、图片格式、表设计、图表设计和 SmartArt 设计选项卡已在全部五个绑定中可用；变体效果和背景样式图库以及 SmartArt 设计 > 布局尚无功能区图库（SmartArt 布局需在检查器中设置）。编辑顶点（以及“任意多边形：形状”和“曲线”绘图工具）、合并形状、画布上的图片裁剪（裁剪手柄、按纵横比裁剪、填充、适应）、选择性粘贴、空白画布与元素的上下文菜单、幻灯片窗格多选、真实的就地动画预览以及标准编辑快捷键已在全部五个绑定中可用。

基于 Apache-2.0 许可证发布

Copyright © 2025-present ChristopherVR