PptxGenJS 导出 PPTX 实战：RTL 对齐、富文本 runs 与列表 bullet，如何把网页幻灯片变成“可编辑文件”

“把网页里的幻灯片导出成 PPTX”，最容易走的一条路是：截图 → 塞进 PPTX。这条路确实快，但它直接放弃了用户最在意的一点：可编辑性（文本不可选、不可改、不可复用样式）。

如果你选择“真正导出 PPTX 结构”（文本仍然是文本、形状仍然是形状），会立刻遇到三类硬问题：

单位体系不一致：DOM 是 px，PPTX 更偏向物理单位（inches/points），一处换算不稳就会整体漂移。
富文本不再是一个字符串：加粗/下划线/颜色/高亮必须拆成多个 text runs，否则样式会丢。
RTL 更是“全链路坑”：对齐、标点、数字与列表符号的方向问题，往往只在阿拉伯语/希伯来语上线后才暴露。

这篇文章用一个可复用的“浏览器端导出方案”把这些问题捋顺：DOM → 中间层模型（IR） → PptxGenJS 渲染器，重点讲清 RTL 对齐、富文本 runs 与 列表 bullet 三个最容易翻车、也最值得工程化的细节。

TL;DR（30 秒讲清楚）

问题：导出 PPTX 后文本对齐错、富文本样式丢、列表符号/编号错位，RTL 语言尤为明显。
方案：在浏览器固定 viewport 渲染导出态；抽 IR（元素类型 + 位置尺寸 + 样式 + 资源）；PptxGenJS 只做渲染；用 rtlMode + text-align(start/end) 翻转解决 RTL。
验证：用对照样本（LTR+RTL+混排+列表）做回归；记录导出耗时 p95、失败率、产物体积，确保“改一次坏一片”不再发生。

适用读者与前置知识

适合：你有 Web 端编辑/渲染的幻灯片（或海报、长图）系统，希望导出“可编辑的 PPTX”。
不适合：你只需要“有一个文件能下载”，完全不关心可编辑与排版细节（截图式导出更省事）。
前置：理解 DOM/CSS 基础；知道 px/pt/in 的概念；能接受“IR + 渲染器”分层。

问题定义（Problem Statement）

在浏览器端把已渲染的幻灯片 DOM 导出为可编辑 PPTX，要求：元素位置尺寸稳定、富文本样式可保留、列表可复现、并支持 RTL 语言在对齐与阅读方向上正确呈现。

目标与非目标（Goals / Non-goals）

目标

可编辑：文本仍是文本，shape 仍是 shape，图片支持 cover/contain 的裁剪语义。
一致性可控：同一份内容在浏览器预览与 PPTX 里尽量一致，误差可被回归测试捕获。
RTL 可用：对齐翻转正确；列表符号/编号在“外侧”正确；必要时设置文档级 RTL。

非目标

不追求 100% 像素级一致（不同 Office/字体渲染器存在天然差异）。
不在本文解决“PPTX 字体嵌入”全量方案（很多场景依赖客户端已有字体/主题字体）。

方案概览：DOM → IR → PptxGenJS（把一致性做成系统能力）

真实链路（从点击 Export 到拿到 .pptx）

进入导出渲染页：用一个“专用导出页面”渲染目标文档，固定 viewport（例如固定宽度 1161px）。
加载数据与主题：把内容 JSON、主题 token、语言 locale 等准备好，进入“导出态”。
DOM → IR：遍历每个 slide：背景、shape、image、svg、text；抽取 computed styles；把位置尺寸统一成 inches。
富文本拆分：递归遍历 text node，按 <strong>/<u>/<span>/<mark> 等标记拆成多个 runs。
列表识别：判断是否处于 list item；生成 bullet（无序符号/有序编号）并修正文本框的对齐宽度。
RTL 分流：按 locale 决定 rtlMode；把 text-align: start/end 映射为左右对齐；设置 PPTX 级别 RTL（可选）。
PptxGenJS 渲染：逐页 addSlide；逐元素 addText/addImage/addShape；生成 base64；触发下载。

关键伪代码（读者可复现）

1) 固定导出 viewport：让 px→inches 有稳定锚点

如果你的页面是响应式的，那么同一份内容在不同窗口宽度下的 boundingRect 会变；导出时你就会得到“随机布局”。工程上最稳的做法是：专门做一个导出渲染页，固定 viewport 与设计宽度。

伪代码：px→inches（设计宽度合同）

const DESIGN_WIDTH_PX = 1161; // 固定导出页宽度
const DESIGN_WIDTH_IN = 10;   // 业务约定：设计宽度对应 10 inch（PPTX 友好）

function pxToIn(px) {
  return px * (DESIGN_WIDTH_IN / DESIGN_WIDTH_PX);
}

2) DOM → IR：抽一个“可复用输入合同”，别让两条通道各读一遍 DOM

一旦你决定未来还要导出 PDF/图片/其它格式，那么“直接从 DOM 画到 PPTX”会让你很快陷入复制粘贴。所以推荐先抽 IR（中间层模型），它是导出链路的“输入合同”。

伪代码：Slide/Element 抽取（省略大量细节）

function capturePresentationFromDOM(rootEl) {
  const slideEls = [...rootEl.querySelectorAll('.slide')]
    .filter((el) => !isGeneratingOrFailed(el));

  return {
    name: readTitle(),
    slides: slideEls.map((slideEl) => {
      const slideRect = slideEl.getBoundingClientRect();
      return {
        background: readBackground(slideEl), // color + image(base64/url)
        sizePx: { w: slideRect.width, h: slideRect.height },
        elements: [
          ...readShapes(slideEl, slideRect),
          ...readImages(slideEl, slideRect),
          ...readSvgsAsRasterImages(slideEl, slideRect),
          ...readRichTexts(slideEl, slideRect),
        ].map((el) => ({
          ...el,
          // 核心：把 px 统一到 inches，后续 PptxGenJS 直接用
          x: pxToIn(el.rect.left - slideRect.left),
          y: pxToIn(el.rect.top - slideRect.top),
          w: pxToIn(el.rect.width),
          h: pxToIn(el.rect.height),
        })),
      };
    }),
  };
}

3) 富文本 runs：递归拆分文本节点，让“样式”可以被复现

在 DOM 里，一段文本可能长这样：粗体 + 下划线 + 彩色 span + 高亮 mark 混在一起。如果你导出时只读 textContent，这些样式都会丢。解决方式是：递归遍历节点，维护一个 overrides 栈，把每个 TEXT_NODE 转成一个 run。

富文本 runs 拆分（示意图） — 图：只要把“样式来源”工程化成 overrides，富文本就能稳定复现，而不是靠字符串拼运气。

伪代码：递归拆分 runs（概念版）

function buildTextRuns(node, inheritedStyle, overrides, outRuns) {
  if (node.type === 'TEXT') {
    outRuns.push({
      text: sanitize(node.text),
      options: {
        fontFace: pickFont(inheritedStyle.fontFamily, node.text),
        fontSize: cssPxToPt(inheritedStyle.fontSize),
        color: overrides.color ?? cssToHex(inheritedStyle.color),
        bold: overrides.bold ?? weightToBold(inheritedStyle.fontWeight),
        italic: overrides.italic ?? false,
        underline: overrides.underline ?? false,
        strike: overrides.strike ?? false,
        highlight: overrides.highlight,
        lineSpacing: cssLineHeightToPt(inheritedStyle.lineHeight, inheritedStyle.fontSize),
        charSpacing: cssLetterSpacingToPt(inheritedStyle.letterSpacing),
      },
    });
    return;
  }

  if (node.tag === 'strong') overrides = { ...overrides, bold: true };
  if (node.tag === 'u') overrides = { ...overrides, underline: true };
  if (node.tag === 'mark') overrides = { ...overrides, highlight: readHighlight(node) };
  if (node.tag === 'span') overrides = { ...overrides, color: readTextColor(node) };
  if (node.tag === 'br') outRuns.push({ text: '' /* line break marker */, options: {} });

  for (const child of node.children) {
    buildTextRuns(child, inheritedStyle, overrides, outRuns);
  }
}

4) 列表 bullet：无序/有序都要能复现，RTL 下更要“放在外侧”

列表是导出最常见的“细节地雷”：缩进、编号增长、符号样式，以及 RTL 下 bullet 在左还是右。一个可控的做法是把列表信息显式写进 IR 的 boxProps：

无序列表：存一个 Unicode code（例如圆点），加一个 indent。
有序列表：存 type=number 与 numberStartAt，渲染时生成 “1.” “2.” …

伪代码：列表识别（概念版）

function detectBullet(nodeContainer) {
  if (!isInsideListItem(nodeContainer)) return null;

  const indent = 20; // 视觉缩进（可校准）
  if (isInsideOrderedList(nodeContainer)) {
    return { indent, type: 'number', numberStartAt: nextIndex() };
  }
  return { indent, code: '25CF' }; // ●
}

5) RTL 对齐：用 start/end + rtlMode，把“逻辑对齐”映射到 PPTX 的左右对齐

解决 RTL 的第一步不是“把所有 left 改成 right”，而是：在编辑/渲染层尽量使用逻辑对齐（start/end），导出时根据 rtlMode 做一次映射。这样 LTR/RTL 才能共享同一份内容结构。

伪代码：text-align 映射（start/end → left/right）

function alignForPptx(textAlign, rtlMode) {
  if (rtlMode) {
    if (textAlign === 'start') return 'right';
    if (textAlign === 'end') return 'left';
  } else {
    if (textAlign === 'start') return 'left';
    if (textAlign === 'end') return 'right';
  }
  return textAlign; // left/center/right/justify 直接透传
}

然后，把 RTL 作为一级参数传给渲染器（不要散落在各处 if/else）：PPTX 文档层可开启 rtlMode，文本框也可以携带 rtlMode。

6) PptxGenJS 渲染：addText 支持 runs，是高保真的关键

一旦有了 IR，PPTX 渲染器就应该尽量“薄”：逐页创建 slide，逐元素 addText/addImage/addShape。富文本的关键在于：把 TextProps[] 转成 PptxGenJS 的 text list（每个 run 一段 text+options）。

伪代码：IR → PPTX（核心结构）

async function renderPptx({ ir, rtlMode, lang }) {
  const pptx = new PptxGenJS();
  pptx.layout = 'LAYOUT_16x9';
  pptx.rtlMode = rtlMode;
  if (rtlMode) pptx.theme = { lang: lang || 'he' };

  for (const slideIR of ir.slides) {
    const slide = pptx.addSlide();
    if (slideIR.background) slide.background = slideIR.background;

    for (const el of slideIR.elements) {
      if (el.type === 'text') {
        const runs = el.textRuns.map((r) => ({ text: r.text, options: r.options }));
        const align = alignForPptx(el.box.align, rtlMode);
        slide.addText(runs, { x: el.x, y: el.y, w: el.w, h: el.h, ...el.box, align, rtlMode });
      }
      if (el.type === 'image') slide.addImage({ x: el.x, y: el.y, w: el.w, h: el.h, ...el.image });
      if (el.type === 'shape') slide.addShape(el.shape.name, { x: el.x, y: el.y, w: el.w, h: el.h, ...el.shape.props });
    }
  }

  return pptx.write('base64');
}

指标与验证（Metrics & Validation）

建议至少建立三类“能长期跑”的验证：

正确性：抽样文档的视觉回归（浏览器预览 vs PPTX 渲染结果），重点关注文本换行、对齐、列表缩进、背景图与裁剪。
RTL 专项：至少准备 5 份 RTL 样本：纯 RTL、RTL+数字、RTL+英文缩写、RTL+列表、RTL+标点括号。
性能与稳定性：导出耗时 p95（按页数分桶）、失败率、产物体积 p95（避免字体/图片处理导致膨胀）。

通过标准（建议）：

正确性：样本库像素 diff 不回退；RTL/混排样本不跑版、不乱序。
缺字：notdef 缺字率接近 0；fallback 命中可追踪可定位。
性能/体积：导出耗时 p95 与文件体积 p95 不回退（或在可接受阈值内）。

最小可复现验证（示例：导出后在 Office 打开抽样检查）：

RTL 文本是否为右对齐（当使用 start 对齐时）。
有序列表编号是否递增，且编号在“外侧”。
混排（英文+数字）是否顺序合理（不出现“数字跑到行首/行尾乱跳”）。
高亮与文字颜色是否保留（runs 是否被拆分）。
背景图是否有正确透明度（如果有 opacity 需求）。

预期与判定（建议）：

对齐：RTL 文本在视觉上“靠右”，且与浏览器预览的 start/end 逻辑一致。
列表：编号/符号在“外侧”，缩进稳定；不出现“编号压住文字/跑到文本框里”的错位。
富文本：runs 拆分后样式不丢（颜色/高亮/下划线等）；混排顺序不乱。

不通过先查：start/end 到 left/right 的映射是否依赖 rtlMode；列表建模是否把 bullet 当成独立语义而不是文本拼接； runs 拆分是否按 DOM 节点递归而不是 innerHTML 拼字符串；以及字体是否发生了客户端替换导致宽度变化。

常见坑与规避（Pitfalls）

不要在编辑层写死 left/right：优先用 start/end，导出时根据 rtlMode 映射，才能共享同一份内容。
富文本不要用 innerHTML 拼：用递归拆 runs；每个 TEXT_NODE 对应一个 run，才可控。
列表缩进要有“视觉合同”：indent 的单位与映射要统一，否则 LTR/RTL 一调就互相打架。
图片要先标准化：base64 需要清洗（去 data: 前缀、去空白）；mime 要可猜测；cover/contain 的数学要一致。
复杂 SVG 别硬矢量化：mask/filter/CSS 变量容易翻车，优先 rasterize 成 PNG（高倍率降低锯齿）。

FAQ（常见问题）

Q1：为什么要“导出渲染页”，不能直接在编辑器页面导出？

因为编辑器页面通常是响应式、带交互层、带动画或覆盖层的；boundingRect 与 computed style 会受各种因素影响。导出渲染页把变量收敛掉：固定 viewport、固定导出态，才能保证 IR 稳定。

Q2：PPTX 为什么更适合“可编辑导出”？

因为 PPTX 天然就是面向编辑的结构：文本框、形状、图片都有明确语义。你保留语义，就给用户留下二次编辑空间；反之截图式导出会让后续编辑成本转移到用户（或客服）身上。

Q3：rtlMode 开了就一定正确吗？

不一定。rtlMode 更像“阅读方向的提示”，真正影响视觉的是：对齐方式映射、列表符号位置、以及混排文本的处理策略。工程上建议把 rtlMode 当作一级参数贯穿链路，而不是只在最后渲染时开一个开关。

Q4：富文本 runs 会不会让导出变慢？

会增加一些工作量，但通常不是瓶颈。真正容易成为瓶颈的是：图片下载/转码、SVG rasterize、以及超大文档的循环渲染。 runs 拆分带来的收益（高保真 + 可维护）往往远大于它的开销。

Q5：字体不一致怎么办？PowerPoint 没有你用的字体怎么办？

这是“可编辑导出”的现实约束：客户端字体不同会导致宽度与换行变化。常见策略是：选择跨平台更常见的字体族作为默认；按 locale 准备非拉丁 fallback；必要时在主题里指定字体；并用回归样本把“换行漂移”控制在可接受范围。

Q6：什么时候应该放弃语义，退回截图式导出？

当页面充满复杂滤镜、混合模式、动画叠层、或大量 SVG mask/filter，且你又没有资源去实现对应的矢量语义时，截图式导出反而更稳定。关键是：把“降级边界”写清楚，别让少数复杂页拖垮整个导出链路。

Q7：RTL 下列表编号的点号放哪边？是 `1.` 还是 `.1`？

没有“天然正确”的答案，关键是统一。建议你把它写成显式规则：在 RTL 下编号是否镜像、点号放外侧还是内侧、缩进如何计算。然后把这条规则做成回归样本（RTL+有序列表），避免不同渲染器（预览/PPTX）各自“自作主张”。

Q8：怎么把 PPTX 导出的回归从“肉眼”变成“可自动化”？

最小可行做法是：固定一组样本文档，导出 PPTX 后用可重复的方式渲染成图片（例如用 Office/渲染服务/第三方转换工具），再做像素 diff 或 pHash 对比。你不需要一开始追求 100% 自动化，但要先把“样本库 + 对照结果”跑起来。

PptxGenJS 导出 PPTX 实战：RTL 对齐、富文本 runs 与列表 bullet，如何把网页幻灯片变成“可编辑文件”

PptxGenJS 导出 PPTX 实战：RTL 对齐、富文本 runs 与列表 bullet，如何把网页幻灯片变成“可编辑文件”

TL;DR（30 秒讲清楚）

适用读者与前置知识

问题定义（Problem Statement）

目标与非目标（Goals / Non-goals）

目标

非目标

方案概览：DOM → IR → PptxGenJS（把一致性做成系统能力）

真实链路（从点击 Export 到拿到 .pptx）

关键伪代码（读者可复现）

1) 固定导出 viewport：让 px→inches 有稳定锚点

2) DOM → IR：抽一个“可复用输入合同”，别让两条通道各读一遍 DOM

3) 富文本 runs：递归拆分文本节点，让“样式”可以被复现

4) 列表 bullet：无序/有序都要能复现，RTL 下更要“放在外侧”

5) RTL 对齐：用 start/end + rtlMode，把“逻辑对齐”映射到 PPTX 的左右对齐

6) PptxGenJS 渲染：addText 支持 runs，是高保真的关键

指标与验证（Metrics & Validation）

常见坑与规避（Pitfalls）

FAQ（常见问题）

Q1：为什么要“导出渲染页”，不能直接在编辑器页面导出？

Q2：PPTX 为什么更适合“可编辑导出”？

Q3：rtlMode 开了就一定正确吗？

Q4：富文本 runs 会不会让导出变慢？

Q5：字体不一致怎么办？PowerPoint 没有你用的字体怎么办？

Q6：什么时候应该放弃语义，退回截图式导出？

Q7：RTL 下列表编号的点号放哪边？是 1. 还是 .1？

Q8：怎么把 PPTX 导出的回归从“肉眼”变成“可自动化”？

Q7：RTL 下列表编号的点号放哪边？是 `1.` 还是 `.1`？