pptx-slides

PPTX 幻灯片 — 以编程方式生成 PowerPoint

使用 PptxGenJS（Node.js）生成专业、可编辑的 PowerPoint 演示文稿。生成符合 OOXML 标准的 .pptx 文件，提供精准的布局、文本测量和重叠验证。

内置辅助模块

每个 PPTX 生成脚本都会通过 bun 导入内置的 TypeScript 辅助模块：

import pptxgen from 'pptxgenjs';
import * as h from '${CLAUDE_PLUGIN_ROOT}/skills/pptx-slides/scripts/main.ts';
const pptx = new pptxgen();
pptx.layout = 'LAYOUT_16x9'; // 10" × 5.625"

使用 bun 运行生成脚本（无需构建步骤）：

npx -y bun ${CLAUDE_PLUGIN_ROOT}/skills/pptx-slides/scripts/main.ts theme list

依赖项（skia-canvas、fontkit、linebreak、prismjs）会在首次运行时由 bun 自动安装，无需手动安装。

模块概要

模块	主要导出项	用途
text	autoFontSize()、calcTextBoxHeightSimple()、scale()	通过 skia-canvas 测量字体相关文本，进行自适应尺寸调整
theme	createTheme()、PRESETS、sectionBackground()	包含 12 种精心设计预设的设计令牌系统
layout	warnIfSlideHasOverlaps()、alignSlideElements()、distributeSlideElements()	重叠检测、边界检查、位置调整
layout_builders	addFeatureGrid()、addCardRow()、addTimeline()、addMetricsRow()、addComparisonTable()	高级组件构建器
decorative	addStaircase()、addSectionBadge()、addProgressBar()、addSlideNumber()	增添视觉个性的元素
validation	validateDeck()	保存前的综合质量验证
code	codeToRuns()	将 Prism.js 语法高亮转换为 PptxGenJS 文本运行
image	getImageDimensions()、imageSizingCrop()、imageSizingContain()	检测二进制尺寸并按宽高比调整大小
svg	svgToDataUri()	SVG 清理和 Base64 数据 URI 编码
util	safeOuterShadow()、normalizeColor()、inchesToEmu()	阴影效果、颜色/单位转换

主题选择

选择精心设计的预设或创建自定义主题：

// Use a preset
const theme = h.createTheme(h.PRESETS.darkMonospace);

// Or customize
const theme = h.createTheme({
  accent: 'ff6b35',
  font: { heading: 'Poppins', body: 'Inter' },
});

可用预设：darkMonospace、swissModern、boldSignal、darkBotanical、cleanCorporate、neonCyber、warmMinimal、vintageEditorial、terminalGreen、gradientWave、midnightBlue、paperInk。

对于混合背景的演示文稿，可定义分区映射：

const sectionMap = { '0': 'brand', '1-3': 'light', '4-8': 'default' };
const colors = { brand: theme.accent, light: theme.bg.secondary, default: theme.bg.primary };
slide.background = { color: h.sectionBackground(slideIndex, sectionMap, colors) };

自适应字体大小

使用 scale() 代替硬编码的字号——它相当于 CSS 的 clamp()：

const titleSize = h.scale(theme.size.title.min, theme.size.title.max, { bullets: 0, textLength: title.length });
const bodySize = h.scale(theme.size.body.min, theme.size.body.max, { bullets: 5, textLength: 800 });

如需精准适配文本框，请结合 skia-canvas 测量使用 autoFontSize()：

const opts = h.autoFontSize('Long paragraph text...', 'Arial', { w: 8, h: 3, minFontSize: 14, maxFontSize: 28 });
slide.addText(text, { x: 1, y: 1.5, ...opts });

生成工作流

1. 规划布局 — 将内容大纲映射到 references/slide-patterns.md 中的幻灯片类型
2. 选择主题 — 选择预设或定义自定义主题令牌
3. 生成幻灯片 — 使用辅助模块构建，例如 addFeatureGrid()、addCardRow() 等
4. 验证 — 保存前运行 h.validateDeck(pptx)
5. 修复问题 — 根据验证报告进行调整，然后重新验证
6. 交付 — 提供 .pptx 文件，并为每张内容幻灯片添加演讲者备注

核心设计规则

排版

• 正文最小字号：18pt（推荐 24-28pt）。使用 scale() 进行自适应调整。
• 标题字号：36-44pt
• 说明文字/脚注：至少 14-16pt（绝对下限：14pt）
• 字体系列：使用 h.resolveFont(theme, 'heading') 获取适当的回退字体链

布局

• 幻灯片尺寸：10" × 5.625"（宽屏 16:9）
• 安全边距：距所有边缘 0.5"（theme.spacing.margin）
• 留白：每张幻灯片的空白区域占比目标为 40-50%
• 对齐：使用 h.alignSlideElements() 和 h.distributeSlideElements() 实现精准布局

颜色与无障碍性

• 对比度：至少符合 WCAG AA 标准（正文 4.5:1，大号文本 3:1）
• 色盲友好：数据可视化使用 Wong 或 IBM 配色方案
• 主题令牌：始终使用 theme.text.primary、theme.accent，绝不硬编码颜色

验证工作流

每次保存演示文稿前都要运行 h.validateDeck(pptx)。它会检查：

• 每张幻灯片上的元素重叠情况
• 元素是否位于幻灯片边界内
• 字号是否高于 14pt 的最小值
• 每张幻灯片的项目符号数量（最多 6 个）
• 是否存在演讲者备注

反模式

• 任意位置的文本小于 14pt
• 每张幻灯片超过 6 个项目符号
• 元素超出幻灯片边界
• 使用硬编码颜色，而非主题令牌
• 使用硬编码字体大小，而非 scale() 或 autoFontSize()
• 保存前跳过 validateDeck()
• 内容幻灯片缺少演讲者备注
• 使用 PptxGenJS 的 fit 或 autoFit，而非 h.autoFontSize()

可编辑性指南

设计时应考虑可编辑性——接收者必须能够修改演示文稿：

• 原生文本框 — 点击即可直接编辑。切勿将文本扁平化为图像。
• 组合相关元素 — 卡片布局可作为一个整体移动。
• 原生形状 — 尽可能使用圆角矩形、圆形和线条，而非嵌入式 SVG。
• 演讲者备注 — 在每张内容幻灯片上通过 slide.addNotes('...') 添加要点。
• 母版布局 — 对于模板演示文稿，定义幻灯片布局，以便统一创建新幻灯片。

使用形状绘制架构图

使用 PptxGenJS 原生形状而非图像来构建架构图：

• 矩形表示服务/组件：slide.addShape('rect', { ... })
• 线条和箭头表示连接：slide.addShape('line', { ... })
• 颜色编码：活动组件使用 theme.accent，非活动组件使用 theme.text.secondary
• 渐进式呈现：在 2-3 张幻灯片中逐步完善同一张图，逐渐增加复杂度

参考文件

• references/pptxgenjs-helpers.md — 内置辅助模块的完整 API 参考
• references/slide-patterns.md — 详细的幻灯片类型模式，包含尺寸和定位信息

脚本文件

• scripts/main.ts — TypeScript CLI 入口点和库重新导出（通过 npx -y bun 运行）
• scripts/types.ts — 所有辅助模块共用的 TypeScript 接口
• scripts/theme.ts — 12 种精选主题预设，提供 createTheme() 和 resolveFont()
• scripts/text.ts — 通过 skia-canvas 测量字体相关文本，提供 autoFontSize()、scale()
• scripts/layout.ts — 重叠检测、元素对齐、边界检查
• scripts/layout_builders.ts — addFeatureGrid()、addCardRow()、addTimeline() 等
• scripts/decorative.ts — addStaircase()、addSectionBadge()、addProgressBar()
• scripts/validation.ts — 保存前使用 validateDeck() 进行质量验证
• scripts/code.ts — 将 Prism.js 语法高亮转换为 PptxGenJS 文本运行
• scripts/image.ts — 检测二进制文件尺寸并按纵横比调整大小
• scripts/svg.ts — SVG 清理和 base64 数据 URI 编码
• scripts/util.ts — 阴影效果、颜色规范化、单位转换