pptx2js 0.4.0

package/lib/mapper.js

@@ -0,0 +1,98 @@
+/**
+ * ④ 映射引擎 — 实体 → 平台无关 IR
+ */
+const { getSlideSizeInches } = require('./presentation');
+
+/**
+ * @param {import('./extractor').SlideEntity[][]} entitiesBySlide
+ * @param {{ parsed: Record<string, object> }} ctx
+ */
+function mapToIR(entitiesBySlide, ctx) {
+  const layout = getSlideSizeInches(ctx.parsed);
+
+  const slides = entitiesBySlide.map((entities, index) => {
+    const elements = [];
+    let background = null;
+
+    for (const entity of entities) {
+      if (entity.kind === 'background' && entity.shape) {
+        background = { color: entity.shape.fill, decision: entity.decision };
+        continue;
+      }
+
+      if (entity.kind === 'skip') {
+        elements.push({
+          type: 'skip',
+          decision: entity.decision,
+          skipReason: entity.skipReason,
+          bounds: entity.bounds,
+        });
+        continue;
+      }
+
+      if (entity.kind === 'text' && entity.text) {
+        elements.push({
+          type: 'text',
+          decision: entity.decision,
+          bounds: entity.bounds,
+          runs: entity.text.runs,
+          degradeReason: entity.degradeReason,
+        });
+        continue;
+      }
+
+      if (entity.kind === 'image' && entity.image) {
+        elements.push({
+          type: 'image',
+          decision: entity.decision,
+          bounds: entity.bounds,
+          mediaPath: `media/${entity.image.fileName}`,
+          zipPath: entity.image.zipPath,
+          degradeReason: entity.degradeReason,
+        });
+        continue;
+      }
+
+      if (entity.kind === 'table' && entity.table) {
+        elements.push({
+          type: 'table',
+          decision: entity.decision,
+          bounds: entity.bounds,
+          rows: entity.table.rows,
+          colWidths: entity.table.colWidths,
+        });
+        continue;
+      }
+
+      if (entity.kind === 'chart' && entity.chart) {
+        elements.push({
+          type: 'chart',
+          decision: entity.decision,
+          bounds: entity.bounds,
+          chartType: entity.chart.type,
+          data: entity.chart.data,
+          title: entity.chart.title,
+        });
+        continue;
+      }
+
+      if (entity.kind === 'shape' && entity.shape) {
+        elements.push({
+          type: 'shape',
+          decision: entity.decision,
+          bounds: entity.bounds,
+          shape: entity.shape.type,
+          fill: entity.shape.fill,
+          line: entity.shape.line,
+          degradeReason: entity.degradeReason,
+        });
+      }
+    }
+
+    return { index, background, elements };
+  });
+
+  return { layout, slides };
+}
+
+module.exports = { mapToIR };

package/lib/packager.js

@@ -0,0 +1,72 @@
+/**
+ * ⑥ 资源打包器
+ * 复制 media/ 文件，写入退化生成图片。
+ * TODO: 重名冲突处理（不同 zip 路径、同名文件时避免覆盖）
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @typedef {object} PackagerInput
+ * @property {import('./unpacker').PptxArchive} archive
+ * @property {import('./mapper').IntermediateRepresentation} ir
+ */
+
+/**
+ * @param {PackagerInput} input
+ * @param {string} outputDir
+ * @param {{ noMedia?: boolean }} options
+ * @returns {Promise<string[]>} 已写入的媒体文件相对路径列表
+ */
+async function packageMedia(input, outputDir, options = {}) {
+  if (options.noMedia) return [];
+
+  const mediaDir = path.join(outputDir, 'media');
+  fs.mkdirSync(mediaDir, { recursive: true });
+
+  const written = [];
+  const { zip } = input.archive;
+  for (const [entryPath, entry] of Object.entries(zip.files)) {
+    if (entry.dir) continue;
+    if (!entryPath.startsWith('ppt/media/')) continue;
+    const name = path.basename(entryPath); // TODO: 重名冲突时生成唯一文件名
+    const dest = path.join(mediaDir, name);
+    const data = await entry.async('nodebuffer');
+    fs.writeFileSync(dest, data);
+    written.push(path.join('media', name));
+  }
+  return written;
+}
+
+/**
+ * @param {string} outputDir
+ * @param {object} log
+ */
+function writeConversionLog(outputDir, log) {
+  const logPath = path.join(outputDir, 'conversion.log');
+  fs.writeFileSync(logPath, JSON.stringify(log, null, 2), 'utf8');
+}
+
+/**
+ * @param {string} outputDir
+ * @param {object} meta
+ */
+function writeOutputReadme(outputDir, meta) {
+  const readmePath = path.join(outputDir, 'README.md');
+  const content = [
+    '# pptx2js 转换输出',
+    '',
+    `源文件：\`${meta.sourcePath}\``,
+    `生成时间：${meta.generatedAt}`,
+    '',
+    '## 文件说明',
+    '',
+    '- `output.js` — 可直接 `node output.js` 运行的 PptxGenJS 脚本',
+    '- `media/` — 提取的图片等媒体资源',
+    '- `conversion.log` — JSON 格式转换报告',
+    '',
+  ].join('\n');
+  fs.writeFileSync(readmePath, content, 'utf8');
+}
+
+module.exports = { packageMedia, writeConversionLog, writeOutputReadme };

package/lib/placeholder.js

@@ -0,0 +1,258 @@
+/**
+ * 母版 / 版式占位符继承（design.html §4.1）
+ * 优先级：slide → slideLayout → slideMaster
+ */
+const { asArray, attr, child } = require('./xml-utils');
+
+const REL_SLIDE_LAYOUT =
+  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout';
+const REL_SLIDE_MASTER =
+  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster';
+
+/**
+ * @typedef {object} PlaceholderKey
+ * @property {string|undefined} idx
+ * @property {string|undefined} type
+ */
+
+/**
+ * @typedef {object} SlideInheritance
+ * @property {string} slidePath
+ * @property {string|null} layoutPath
+ * @property {string|null} masterPath
+ * @property {object|null} layoutSpTree
+ * @property {object|null} masterSpTree
+ */
+
+/**
+ * @param {Record<string, object>} parsed
+ * @param {import('./rels').RelationIndex} relIndex
+ * @param {string} slidePath
+ * @returns {SlideInheritance}
+ */
+function buildSlideInheritance(parsed, relIndex, slidePath) {
+  const layoutPath = resolveRelByType(relIndex, slidePath, REL_SLIDE_LAYOUT);
+  const masterPath = layoutPath
+    ? resolveRelByType(relIndex, layoutPath, REL_SLIDE_MASTER)
+    : null;
+
+  const layoutSpTree = layoutPath ? getSpTree(parsed, layoutPath) : null;
+  const masterSpTree = masterPath ? getSpTree(parsed, masterPath) : null;
+
+  return {
+    slidePath,
+    layoutPath,
+    masterPath,
+    layoutSpTree,
+    masterSpTree,
+  };
+}
+
+/**
+ * @param {import('./rels').RelationIndex} relIndex
+ * @param {string} sourcePath
+ * @param {string} typeFragment
+ * @returns {string|null}
+ */
+function resolveRelByType(relIndex, sourcePath, typeFragment) {
+  const rel = relIndex
+    .list(sourcePath)
+    .find((r) => r.type && r.type.includes(typeFragment));
+  return rel?.target ?? null;
+}
+
+/**
+ * @param {Record<string, object>} parsed
+ * @param {string} partPath slide / slideLayout / slideMaster
+ * @returns {object|null}
+ */
+function getSpTree(parsed, partPath) {
+  const doc = parsed[partPath];
+  if (!doc) return null;
+  const root =
+    child(doc, 'p:sld') ??
+    child(doc, 'p:sldLayout') ??
+    child(doc, 'p:sldMaster');
+  if (!root) return null;
+  return child(child(root, 'p:cSld'), 'p:spTree');
+}
+
+/**
+ * @param {object} sp
+ * @returns {PlaceholderKey|null}
+ */
+function getPlaceholderKey(sp) {
+  const ph = child(child(child(sp, 'p:nvSpPr'), 'p:nvPr'), 'p:ph');
+  if (!ph) return null;
+  return {
+    idx: attr(ph, 'idx'),
+    type: attr(ph, 'type'),
+  };
+}
+
+/**
+ * @param {object|null} spTree
+ * @param {PlaceholderKey} key
+ * @returns {object|null}
+ */
+function findSpByPlaceholder(spTree, key) {
+  if (!spTree || !key) return null;
+
+  for (const sp of walkAllSp(spTree)) {
+    const ph = getPlaceholderKey(sp);
+    if (!ph) continue;
+    if (key.idx != null && ph.idx === key.idx) return sp;
+    if (key.type && ph.type === key.type) return sp;
+  }
+  return null;
+}
+
+/**
+ * @param {object} spTree
+ * @returns {object[]}
+ */
+function* walkAllSp(spTree) {
+  for (const sp of asArray(spTree['p:sp'])) {
+    yield sp;
+  }
+  for (const grp of asArray(spTree['p:grpSp'])) {
+    const inner = child(grp, 'p:spTree');
+    if (inner) yield* walkAllSp(inner);
+  }
+}
+
+/**
+ * @param {object} slideSp
+ * @param {SlideInheritance} inheritance
+ * @returns {{ layoutSp: object|null, masterSp: object|null }}
+ */
+function resolvePlaceholderSps(slideSp, inheritance) {
+  const key = getPlaceholderKey(slideSp);
+  if (!key) {
+    return { layoutSp: null, masterSp: null };
+  }
+
+  const layoutSp = inheritance.layoutSpTree
+    ? findSpByPlaceholder(inheritance.layoutSpTree, key)
+    : null;
+  const masterSp = inheritance.masterSpTree
+    ? findSpByPlaceholder(inheritance.masterSpTree, key)
+    : null;
+
+  return { layoutSp, masterSp };
+}
+
+/**
+ * 合并 a:xfrm：off 与 ext 各属性独立按 slide → layout → master 继承
+ * @param {object|null|undefined} slideXfrm
+ * @param {object|null|undefined} layoutXfrm
+ * @param {object|null|undefined} masterXfrm
+ * @returns {object|null}
+ */
+function mergeXfrm(slideXfrm, layoutXfrm, masterXfrm) {
+  const layers = [slideXfrm, layoutXfrm, masterXfrm];
+  const off = mergeXfrmPart(
+    layers.map((x) => child(x, 'a:off')),
+    ['x', 'y']
+  );
+  const ext = mergeXfrmPart(
+    layers.map((x) => child(x, 'a:ext')),
+    ['cx', 'cy'],
+    { skipZero: true }
+  );
+
+  if (!off && !ext) return null;
+  return {
+    'a:off': off ?? { $: { x: '0', y: '0' } },
+    'a:ext': ext ?? { $: { cx: '0', cy: '0' } },
+  };
+}
+
+/**
+ * @param {(object|null|undefined)[]} parts
+ * @param {string[]} attrNames
+ * @param {{ skipZero?: boolean }} [opts]
+ * @returns {object|null}
+ */
+function mergeXfrmPart(parts, attrNames, opts = {}) {
+  const values = {};
+  let hasAny = false;
+
+  for (const name of attrNames) {
+    for (const part of parts) {
+      if (!part) continue;
+      const v = attr(part, name);
+      if (v == null || v === '') continue;
+      if (opts.skipZero && (name === 'cx' || name === 'cy')) {
+        if (parseInt(v, 10) <= 0) continue;
+      }
+      values[name] = v;
+      hasAny = true;
+      break;
+    }
+  }
+
+  if (!hasAny) return null;
+  return { $: values };
+}
+
+/**
+ * @param {object} slideSp
+ * @param {SlideInheritance} inheritance
+ * @returns {object|null}
+ */
+function getEffectiveXfrm(slideSp, inheritance) {
+  const slideSpPr = child(slideSp, 'p:spPr');
+  const { layoutSp, masterSp } = resolvePlaceholderSps(slideSp, inheritance);
+
+  return mergeXfrm(
+    child(slideSpPr, 'a:xfrm'),
+    layoutSp && child(child(layoutSp, 'p:spPr'), 'a:xfrm'),
+    masterSp && child(child(masterSp, 'p:spPr'), 'a:xfrm')
+  );
+}
+
+/**
+ * 合并 txBody 默认样式：用 layout/master 的首段/首 run 补全 slide 层缺失的 rPr
+ * @param {object} slideTxBody
+ * @param {object|null} layoutSp
+ * @param {object|null} masterSp
+ * @returns {object}
+ */
+function mergeTxBody(slideTxBody, layoutSp, masterSp) {
+  const slideBody = slideTxBody;
+  const fallbackBody =
+    (layoutSp && child(layoutSp, 'p:txBody')) ||
+    (masterSp && child(masterSp, 'p:txBody'));
+  if (!fallbackBody) return slideBody;
+
+  const slideParas = asArray(slideBody['a:p']);
+  const fallbackPara = asArray(fallbackBody['a:p'])[0];
+  const fallbackRPr = fallbackPara && child(asArray(fallbackPara['a:r'])[0], 'a:rPr');
+
+  if (!fallbackRPr) return slideBody;
+
+  const mergedParas = slideParas.map((p) => {
+    const runs = asArray(p['a:r']).map((r) => {
+      const rPr = child(r, 'a:rPr');
+      if (rPr) return r;
+      return { ...r, 'a:rPr': JSON.parse(JSON.stringify(fallbackRPr)) };
+    });
+    return { ...p, 'a:r': runs.length === 1 ? runs[0] : runs };
+  });
+
+  return { ...slideBody, 'a:p': mergedParas.length === 1 ? mergedParas[0] : mergedParas };
+}
+
+module.exports = {
+  REL_SLIDE_LAYOUT,
+  REL_SLIDE_MASTER,
+  buildSlideInheritance,
+  getPlaceholderKey,
+  findSpByPlaceholder,
+  resolvePlaceholderSps,
+  mergeXfrm,
+  getEffectiveXfrm,
+  mergeTxBody,
+  getSpTree,
+};

package/lib/presentation.js

@@ -0,0 +1,70 @@
+/**
+ * presentation.xml：幻灯片列表与版面尺寸
+ */
+const { asArray, attr, child } = require('./xml-utils');
+const { emuToInch } = require('./utils/emu');
+
+const PRESENTATION_PATH = 'ppt/presentation.xml';
+
+/**
+ * @param {Record<string, object>} parsed
+ * @param {import('./rels').RelationIndex} relIndex
+ * @returns {string[]}
+ */
+function getSlidePaths(parsed, relIndex) {
+  const doc = parsed[PRESENTATION_PATH];
+  const pres = child(doc, 'p:presentation');
+  if (!pres) return [];
+
+  const sldIds = asArray(child(child(pres, 'p:sldIdLst'), 'p:sldId'));
+  const paths = [];
+  for (const sldId of sldIds) {
+    const relId = attr(sldId, 'r:id');
+    if (!relId) continue;
+    const target = relIndex.resolve(PRESENTATION_PATH, relId);
+    if (target) paths.push(target);
+  }
+  return paths;
+}
+
+/**
+ * @param {Record<string, object>} parsed
+ * @returns {{ width: number, height: number }}
+ */
+function getSlideSizeInches(parsed) {
+  const pres = child(parsed[PRESENTATION_PATH], 'p:presentation');
+  const sldSz = child(pres, 'p:sldSz');
+  const cx = parseInt(attr(sldSz, 'cx') ?? '9144000', 10);
+  const cy = parseInt(attr(sldSz, 'cy') ?? '6858000', 10);
+  return {
+    width: round3(emuToInch(cx)),
+    height: round3(emuToInch(cy)),
+  };
+}
+
+/**
+ * @param {Record<string, object>} parsed
+ * @param {import('./rels').RelationIndex} relIndex
+ * @returns {string|null}
+ */
+function getThemePath(parsed, relIndex) {
+  const themeRel = relIndex
+    .list(PRESENTATION_PATH)
+    .find((r) => r.type && r.type.includes('/relationships/theme'));
+  return themeRel?.target ?? null;
+}
+
+/**
+ * @param {number} n
+ * @returns {number}
+ */
+function round3(n) {
+  return Math.round(n * 1000) / 1000;
+}
+
+module.exports = {
+  PRESENTATION_PATH,
+  getSlidePaths,
+  getSlideSizeInches,
+  getThemePath,
+};

package/lib/rels.js

@@ -0,0 +1,117 @@
+/**
+ * OOXML 关系（.rels）解析与路径解析
+ */
+const path = require('path');
+const { asArray, attr } = require('./xml-utils');
+
+/**
+ * @typedef {object} Relationship
+ * @property {string} id
+ * @property {string} type
+ * @property {string} target
+ */
+
+/**
+ * @typedef {object} RelationIndex
+ * @property {(sourcePath: string, relId: string) => string|null} resolve
+ * @property {(sourcePath: string) => Relationship[]} list
+ */
+
+/**
+ * .rels 文件路径 → 所属部件路径
+ * @param {string} relsPath 如 ppt/slides/_rels/slide1.xml.rels
+ * @returns {string}
+ */
+function relsOwnerPath(relsPath) {
+  const normalized = relsPath.replace(/\\/g, '/');
+  // 包根关系：_rels/.rels → owner 为包根（空路径）
+  if (normalized === '_rels/.rels') {
+    return '';
+  }
+
+  const parts = normalized.split('/');
+  const relFile = parts.pop();
+  parts.pop(); // _rels
+  const ownerFile = relFile.replace(/\.rels$/i, '');
+  parts.push(ownerFile);
+  return parts.join('/');
+}
+
+/**
+ * @param {string} ownerPath
+ * @param {string} target
+ * @returns {string}
+ */
+/**
+ * @param {Relationship} rel
+ */
+function isExternalTarget(rel) {
+  if (rel.targetMode === 'External') return true;
+  return /^(https?|mailto|ftp):/i.test(rel.target);
+}
+
+function resolveTargetPath(ownerPath, target) {
+  if (!ownerPath) {
+    return path.posix.normalize(target);
+  }
+  const ownerDir = path.posix.dirname(ownerPath);
+  return path.posix.normalize(path.posix.join(ownerDir, target));
+}
+
+/**
+ * @param {object} relsDoc xml2js 解析结果
+ * @returns {Relationship[]}
+ */
+function parseRelationships(relsDoc) {
+  const root = relsDoc?.Relationships ?? relsDoc;
+  const rels = asArray(root?.Relationship);
+  return rels
+    .map((rel) => ({
+      id: attr(rel, 'Id'),
+      type: attr(rel, 'Type'),
+      target: attr(rel, 'Target'),
+      targetMode: attr(rel, 'TargetMode'),
+    }))
+    .filter((r) => r.id && r.target);
+}
+
+/**
+ * @param {Record<string, object>} parsed
+ * @returns {RelationIndex}
+ */
+function buildRelationIndex(parsed) {
+  /** @type {Map<string, Map<string, Relationship>>} */
+  const bySource = new Map();
+
+  for (const [filePath, doc] of Object.entries(parsed)) {
+    if (!filePath.endsWith('.rels')) continue;
+    const owner = relsOwnerPath(filePath);
+    const relationships = parseRelationships(doc);
+    const map = new Map();
+    for (const rel of relationships) {
+      const target = isExternalTarget(rel)
+        ? rel.target
+        : resolveTargetPath(owner, rel.target);
+      map.set(rel.id, { ...rel, target });
+    }
+    bySource.set(owner, map);
+  }
+
+  return {
+    resolve(sourcePath, relId) {
+      const rel = bySource.get(sourcePath)?.get(relId);
+      return rel?.target ?? null;
+    },
+    list(sourcePath) {
+      const map = bySource.get(sourcePath);
+      return map ? Array.from(map.values()) : [];
+    },
+  };
+}
+
+module.exports = {
+  relsOwnerPath,
+  resolveTargetPath,
+  parseRelationships,
+  buildRelationIndex,
+};

package/lib/smartart.js

@@ -0,0 +1,96 @@
+/**
+ * SmartArt 退化处理（design.html §4.2）
+ */
+const { attr, child, textContent } = require('./xml-utils');
+const { getGraphicXfrm } = require('./graphic');
+const { boundsFromXfrm } = require('./utils/bounds');
+
+/**
+ * @param {object} graphicFrame
+ * @param {object} ctx
+ * @returns {import('./extractor').SlideEntity}
+ */
+function extractSmartArt(graphicFrame, ctx) {
+  const bounds = boundsFromXfrm(getGraphicXfrm(graphicFrame), ctx.offset);
+
+  // 层① 缓存图片：SmartArt 缓存图片的 rels 结构因 PPT 版本差异较大，暂不实现
+  // 直接走层② 文本提取
+
+  const texts = extractSmartArtTexts(graphicFrame, ctx);
+  if (texts.length) {
+    return {
+      slideIndex: ctx.slideIndex,
+      slidePath: ctx.slidePath,
+      decision: 'DEGRADE',
+      kind: 'text',
+      bounds,
+      text: {
+        runs: texts.map((t, i) => ({
+          text: `${i + 1}. ${t}`,
+          options: { fontSize: 12 },
+        })),
+      },
+      degradeReason: 'SmartArt 退化为文本列表',
+    };
+  }
+
+  return {
+    slideIndex: ctx.slideIndex,
+    slidePath: ctx.slidePath,
+    decision: 'DEGRADE',
+    kind: 'text',
+    bounds,
+    text: {
+      runs: [
+        {
+          text: '[SmartArt 无法解析]',
+          options: { fontSize: 12, color: '888888' },
+        },
+      ],
+    },
+    degradeReason: 'SmartArt 无可提取文本',
+  };
+}
+
+/**
+ * @param {object} graphicFrame
+ * @param {object} ctx
+ * @returns {string[]}
+ */
+function extractSmartArtTexts(graphicFrame, ctx) {
+  const graphicData = child(child(graphicFrame, 'a:graphic'), 'a:graphicData');
+  const relIds = child(graphicData, 'dgm:relIds');
+  const dgmRelId = relIds && (attr(relIds, 'r:dm') ?? attr(relIds, 'dm'));
+  const dataPath = dgmRelId && ctx.relIndex.resolve(ctx.slidePath, dgmRelId);
+  if (!dataPath || !ctx.parsed[dataPath]) return [];
+
+  const texts = [];
+  collectTextNodes(ctx.parsed[dataPath], texts);
+  return [...new Set(texts)];
+}
+
+/**
+ * @param {object} node
+ * @param {string[]} out
+ */
+function collectTextNodes(node, out) {
+  if (node == null) return;
+  if (typeof node === 'string') return;
+  if (typeof node !== 'object') return;
+
+  if (node['a:t'] != null) {
+    const t = textContent(node['a:t']);
+    if (t) out.push(t);
+  }
+
+  for (const [key, val] of Object.entries(node)) {
+    if (key === '$') continue;
+    if (Array.isArray(val)) {
+      for (const item of val) collectTextNodes(item, out);
+    } else if (val && typeof val === 'object') {
+      collectTextNodes(val, out);
+    }
+  }
+}
+
+module.exports = { extractSmartArt, extractSmartArtTexts };