Keywords
PowerPoint, pptx, 幻灯片, 演示文稿, 模板, PPT生成, PPT编辑, 幻灯片设计
Summary
markitdown读取内容，pptxgenjs从头创建，解包→编辑→打包修改模板。
Strategy
- 读取内容：markitdown或thumbnail.py
- 从头创建：pptxgenjs（见pptxgenjs.md）
- 编辑模板：unpack→编辑→pack（见editing.md）
- 视觉检查：转图片后检查问题
AVOID
设计禁忌：
- AVOID 纯文字幻灯片，必须有视觉元素
- AVOID 标题下加装饰线，AI生成的标志
- AVOID 默认蓝色（#0070C0），选择匹配主题的颜色
- AVOID 重复相同布局，每张应有变化
- AVOID 居中正文，只标题居中
- AVOID 低对比度，确保文字/图标与背景对比明显
层次禁忌：
- AVOID 所有文字同样大小，必须有层次
- AVOID 所有文字同样颜色，主次不分
- AVOID 标题字号 < 正文字号 × 1.5
留白禁忌：
- AVOID 内容占比 > 70%，必须留白
- AVOID 边距 < 0.5 英寸，太挤
- AVOID 元素间距不均匀，显得乱
配色禁忌：
- AVOID 单页颜色 > 4 种，变成彩虹糖
- AVOID 高饱和度大面积使用，刺眼
- AVOID 文字与背景对比度不足，看不清
字体禁忌：
- AVOID 使用宋体/楷体，这是文档味
- AVOID 字号 < 12pt，投影看不清
- AVOID 中英文混用不同风格字体
快速参考
| 任务 | 方法 |
|---|
| 读取内容 | python -m markitdown presentation.pptx |
| 视觉预览 | python scripts/thumbnail.py presentation.pptx |
| 从头创建 | pptxgenjs（见pptxgenjs.md） |
| 编辑模板 | unpack→编辑→pack（见editing.md） |
前置依赖
# Python 依赖（用于读取和预览）
pip install markitdown[pptx] Pillow
# Node.js 依赖（用于生成 PPT）
npm install -g pptxgenjs
# html2pptx 工作流依赖
npm install pptxgenjs playwright sharp
npx playwright install chromium # 首次运行必需！
# LibreOffice (soffice) 用于转PDF
# pdftoppm (poppler-utils) 用于转图片
注意：npx playwright install chromium 是首次使用 html2pptx 的必需步骤，否则会报错 "Executable doesn't exist"。
设计原则
⚠️ 核心铁律：代码生成 ≠ 好看
pptxgenjs 是工具，不是设计师。 代码只能控制位置和颜色，无法保证美感。
推荐优先级：
- 模板编辑（首选）→ 基于专业设计的模板修改内容
- 代码生成（次选）→ 仅用于简单/批量场景，且必须严格遵循设计规范
一、PPT设计四大原则（CPRA）
基于《写给大家看的设计书》的四大核心原则：
1. 对比（Contrast）
目的：建立视觉层次，突出重点
| 对比类型 | 应用方法 | 具体数值 |
|---|
| 字号对比 | 标题 ≥ 正文 × 2 | 主标题 44-60pt，正文 16-20pt |
| 字重对比 | 标题 Bold，正文 Regular | 至少两级字重差 |
| 色彩对比 | 主色 vs 辅色 vs 背景 | 对比度 ≥ 4.5:1 |
| 空间对比 | 密集 vs 留白 | 关键内容周围留白 30% |
禁忌：
- 所有文字同样大小 → 无层次
- 所有元素同样粗细 → 无重点
- 颜色过于接近 → 看不清
2. 重复（Repetition）
目的：建立视觉统一性，形成品牌识别
| 重复元素 | 应用方法 |
|---|
| 色彩 | 全篇使用同一套配色（主色+辅色+强调色） |
| 字体 | 不超过 2 种字体，建立严格层级 |
| 图形 | 统一图标风格、分隔线样式 |
| 布局 | 同类页面保持结构一致 |
80/20法则：80% 严格重复，20% 适度变化
3. 对齐（Alignment）
目的：创造秩序感和专业感
| 对齐类型 | 适用场景 |
|---|
| 左对齐 | 正文、列表（最常用） |
| 居中对齐 | 封面、标题页、短句 |
| 右对齐 | 数字、日期、价格 |
网格系统：
- 使用 4、6 或 12 列网格
- 所有元素沿网格线对齐
- 元素间距保持一致
4. 亲密性（Proximity）
目的：通过空间关系表现信息关联
| 应用方法 | 具体数值 |
|---|
| 相关元素间距 | 0.2-0.3 英寸 |
| 不相关元素间距 | ≥ 0.5 英寸 |
| 组内间距 | 组间距的 1/4 到 1/2 |
| 留白占比 | 30%-40% |
原则：相关内容靠近，不相关内容远离
二、视觉层次（最重要！）
每页必须有清晰的层次结构：
| 层次 | 字号 | 颜色 | 粗细 | 用途 |
|---|
| 主标题 | 44-60pt | 主色/深色 | Bold | 封面标题、核心观点 |
| 副标题 | 24-32pt | 主色 | Bold | 章节标题、关键信息 |
| 正文 | 16-20pt | 深灰(#333) | Regular | 内容描述 |
| 辅助说明 | 12-14pt | 浅灰(#666) | Light | 注释、来源 |
⚠️ 禁止：所有文字用同样大小、同样颜色 → 没有层次感
三、留白黄金比例
留白是设计的灵魂，不是浪费空间。
2024年极简设计趋势：
- 留白占比：40%-50%（比以往更多）
- 内容聚焦：每页只传达一个核心信息
- 呼吸感：元素周围必须有足够的空白
安全边距（16:9 幻灯片）：
- 左右边距：0.8-1.0 英寸
- 上下边距：0.6-0.8 英寸
- 内容占比：不超过 60%，留出 40% 空白
元素间距：
- 标题与正文：0.4-0.6 英寸
- 段落之间：0.3-0.4 英寸
- 卡片之间：0.4-0.5 英寸
- 组内元素：0.2-0.3 英寸
⚠️ 禁止：把内容塞满整个页面 → 拥挤感，让人窒息
四、配色心理学
一套配色 = 主色 + 辅色 + 强调色 + 背景色
| 主题 | 主色 | 辅色 | 强调色 | 背景 | 适用场景 |
|---|
| 森林绿 | #2C5F2D | #97BC62 | #F5F5F5 | #FFFFFF | 教育、环保 |
| 午夜商务 | #1E2761 | #CADCFC | #FFFFFF | #F8F9FA | 商务、科技 |
| 珊瑚活力 | #F96167 | #F9E795 | #2F3C7E | #FFF5F5 | 创意、营销 |
| 暖陶土 | #B85042 | #E7E8D1 | #A7BEAE | #FAFAF0 | 艺术、生活 |
| 极简黑白 | #000000 | #666666 | #FFFFFF | #FFFFFF | 设计、时尚 |
配色铁律：
- 主色占比：10-20%（标题、重点）
- 辅色占比：20-30%（卡片、图标）
- 强调色占比：5-10%（按钮、高亮）
- 背景色占比：40-60%（页面底色）
⚠️ 禁止：
- 使用默认蓝色（#0070C0）→ "PPT味"
- 一页超过 4 种颜色 → "彩虹糖"
- 高饱和度大面积使用 → "刺眼"
四、字体规范
中文字体：思源黑体 > 微软雅黑 > 方正兰亭黑
英文字体：Helvetica > Arial > Calibri
字号规范：
| 元素 | 字号 | 行距 |
|---|
| 封面主标题 | 48-60pt | 1.2 |
| 页面标题 | 32-44pt | 1.2 |
| 副标题 | 20-28pt | 1.3 |
| 正文 | 16-20pt | 1.5 |
| 辅助说明 | 12-14pt | 1.4 |
⚠️ 禁止：使用宋体/楷体 → "文档味"
五、布局模板库
封面页
┌─────────────────────────────────────┐
│ │
│ 【大标题居中】 │
│ 【副标题】 │
│ │
│ 【Logo/装饰】 │
│ │
└─────────────────────────────────────┘
标题+列表页
┌─────────────────────────────────────┐
│ 【页面标题】 │
│ ───────────────────────────────── │
│ • 要点1 │
│ • 要点2 │
│ • 要点3 │
│ │
└─────────────────────────────────────┘
双栏对比页
┌─────────────────────────────────────┐
│ 【页面标题】 │
│ ┌──────────┐ ┌──────────┐ │
│ │ 左栏 │ │ 右栏 │ │
│ │ 内容 │ │ 内容 │ │
│ └──────────┘ └──────────┘ │
└─────────────────────────────────────┘
三列卡片页
┌─────────────────────────────────────┐
│ 【页面标题】 │
│ ┌────┐ ┌────┐ ┌────┐ │
│ │卡1 │ │卡2 │ │卡3 │ │
│ └────┘ └────┘ └────┘ │
└─────────────────────────────────────┘
数据展示页
┌─────────────────────────────────────┐
│ 【页面标题】 │
│ ┌─────────┐ ┌─────────┐ │
│ │ 大数字 │ │ 大数字 │ │
│ │ 说明 │ │ 说明 │ │
│ └─────────┘ └─────────┘ │
└─────────────────────────────────────┘
六、AI 审美检查清单
生成 PPT 后，必须逐项检查：
视觉层次：
留白：
配色：
字体：
布局：
七、设计迭代方法论
从 V1 到 V4 的专业设计进化路径：
V1 - 基础原型：
- 确定内容结构和信息架构
- 选择基础配色方案
- 完成基本布局
V2 - 内容优化：
V3 - 布局修复：
- 精确计算元素位置
- 调整卡片尺寸和间距
- 优化配色细节
V4 - 专业重构：
- 统一视觉语言（如三色顶栏、章节编号、页码系统）
- 建立清晰的信息层级（颜色、大小、位置区分重要性）
- 添加装饰元素增强设计感
- 确保呼吸感（适当留白，避免拥挤）
统一视觉语言示例：
/* 三色顶栏系统 */
.top-bar { background: #ff6b6b; width: 240pt; }
.top-bar2 { background: #4ecdc4; width: 240pt; left: 240pt; }
.top-bar3 { background: #a855f7; width: 240pt; left: 480pt; }
/* 章节编号系统 */
.section-num { font-size: 14pt; color: #666; }
信息层级设计：
- 主标题：最大字号 + 主色 + Bold
- 副标题：中等字号 + 主色/辅色
- 正文：标准字号 + 深灰色
- 辅助信息：小字号 + 浅灰色
颜色选择（旧版保留）
不要默认蓝色，选择匹配主题的调色板：
| 主题 | 主色 | 辅色 | 强调色 |
|---|
| 午夜商务 | 1E2761 | CADCFC | FFFFFF |
| 森林绿 | 2C5F2D | 97BC62 | F5F5F5 |
| 珊瑚活力 | F96167 | F9E795 | 2F3C7E |
| 暖陶土 | B85042 | E7E8D1 | A7BEAE |
字体搭配
| 标题字体 | 正文字体 |
|---|
| Georgia | Calibri |
| Arial Black | Arial |
| Calibri | Calibri Light |
| Impact | Arial |
字号规范
| 元素 | 字号 |
|---|
| 幻灯标题 | 36-44pt 粗体 |
| 章节标题 | 20-24pt 粗体 |
| 正文 | 14-16pt |
| 说明文字 | 10-12pt |
间距规范
- 最小边距：0.5英寸
- 内容块间距：0.3-0.5英寸
- 留白，不要填满
布局变化
每张幻灯片应有不同的布局：
- 双栏（左文字右图）
- 图标+文字行
- 2x2或2x3网格
- 半出血图片+内容叠加
- 大数字统计
- 对比列（前后/优缺点）
常见错误
一般错误
| 错误 | 正确做法 |
|---|
| 纯文字幻灯片 | 添加图片/图标/图表 |
| 标题下装饰线 | 用留白或背景色 |
| 默认蓝色 | 选择匹配主题的颜色 |
| 重复相同布局 | 每张变化布局 |
| 居中正文 | 左对齐，只标题居中 |
| 低对比度 | 确保文字/图标与背景对比明显 |
html2pptx 特定错误
当使用 html2pptx 工作流（HTML/CSS → Playwright → PPTX）时，可能遇到以下错误：
| 错误信息 | 原因 | 解决方案 |
|---|
Cannot find module 'pptxgenjs' | node_modules 不在当前目录 | 运行 npm install pptxgenjs playwright sharp |
Executable doesn't exist at ...chromium | Playwright 浏览器未安装 | 运行 npx playwright install chromium |
CSS gradients are not supported | html2pptx 不支持 CSS 渐变 | 使用纯色背景或预渲染的渐变图片 |
Text element <p> has border | 文本元素不支持 border 属性 | 将 border 移到单独的 <div> 元素 |
HTML content overflows body by XXpt horizontally | 内容总宽度超过 720pt | 精确计算：边距 + (卡片宽 × 数量) + (间距 × (数量-1)) < 720 |
Text box ... ends too close to bottom edge | 内容太靠近边缘 | 减小 padding、调整 font-size、确保 36pt 安全边距 |
| 中文文件名读取失败 | Windows 路径编码问题 | 重命名为英文文件名 |
| 图片位置不准 | 坐标计算错误 | 使用公式：英寸 = 点数 / 72 |
调试技巧
- 逐页测试：先单独测试每页，确认无误后再批量生成
- 浏览器预览：直接在浏览器中打开 HTML 文件预览效果
- 控制台日志：在脚本中添加详细日志追踪问题
- 检查依赖：确保
npm install 和 npx playwright install chromium 已执行
QA检查（必须执行）
内容检查
python -m markitdown output.pptx
# 检查缺失内容、错别字、顺序错误
检查占位符残留
python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum"
视觉检查
转图片后检查：
python scripts/office/soffice.py --headless --convert-to pdf output.pptx
pdftoppm -jpeg -r 150 output.pdf slide
检查项目：
- 元素重叠
- 文字溢出/被裁切
- 间距不均匀
- 边距不足(<0.5")
- 对齐不一致
- 低对比度
验证循环
- 生成→转图片→检查
- 列出问题（没找到就是检查不够仔细）
- 修复问题
- 重新验证受影响的幻灯片
- 重复直到无新问题
完整示例：从零创建产品介绍PPT
需求
创建一个5页的产品介绍PPT，主题是"智能家居系统"。
Step 1: 初始化项目
const pptxgen = require("pptxgenjs");
let pres = new pptxgen();
pres.layout = 'LAYOUT_16x9';
pres.author = '智国学堂';
pres.title = '智能家居系统介绍';
Step 2: 设计配色方案
选择"森林绿"主题：
- 主色：#2C5F2D（深绿）
- 辅色：#97BC62（浅绿）
- 强调色：#F5F5F5（浅灰）
Step 3: 创建幻灯片
// 第1页：封面（大标题+副标题）
let slide1 = pres.addSlide();
slide1.addShape(pres.ShapeType.rect, { x: 0, y: 0, w: '100%', h: '100%', fill: { color: '2C5F2D' } });
slide1.addText("智能家居系统", { x: 0.5, y: 2, w: 9, h: 1.5, fontSize: 44, color: "FFFFFF", bold: true, align: "center" });
slide1.addText("让生活更智能、更便捷", { x: 0.5, y: 3.5, w: 9, h: 0.5, fontSize: 20, color: "97BC62", align: "center" });
// 第2页：产品特点（图标+文字行布局）
let slide2 = pres.addSlide();
slide2.addText("核心特点", { x: 0.5, y: 0.3, w: 9, h: 0.8, fontSize: 32, color: "2C5F2D", bold: true });
slide2.addText([
{ text: "🏠 远程控制", options: { breakLine: true } },
{ text: "📱 语音交互", options: { breakLine: true } },
{ text: "🔒 安全防护", options: { breakLine: true } },
{ text: "⚡ 节能环保", options: { breakLine: true } }
], { x: 0.5, y: 1.5, w: 9, h: 3.5, fontSize: 24, color: "363636" });
// 第3页：数据统计（大数字+说明）
let slide3 = pres.addSlide();
slide3.addText("市场数据", { x: 0.5, y: 0.3, w: 9, h: 0.8, fontSize: 32, color: "2C5F2D", bold: true });
slide3.addText("100万+", { x: 1, y: 1.5, w: 3, h: 1, fontSize: 48, color: "2C5F2D", bold: true });
slide3.addText("活跃用户", { x: 1, y: 2.5, w: 3, h: 0.5, fontSize: 16, color: "666666" });
slide3.addText("99.9%", { x: 5, y: 1.5, w: 3, h: 1, fontSize: 48, color: "2C5F2D", bold: true });
slide3.addText("系统稳定性", { x: 5, y: 2.5, w: 3, h: 0.5, fontSize: 16, color: "666666" });
// 第4页：对比优势（双栏布局）
let slide4 = pres.addSlide();
slide4.addText("传统 vs 智能", { x: 0.5, y: 0.3, w: 9, h: 0.8, fontSize: 32, color: "2C5F2D", bold: true });
slide4.addText("传统家居", { x: 0.5, y: 1.3, w: 4, h: 0.5, fontSize: 20, color: "666666", bold: true });
slide4.addText("手动操作\n效率低\n能耗高", { x: 0.5, y: 1.8, w: 4, h: 2, fontSize: 16, color: "666666" });
slide4.addText("智能家居", { x: 5.5, y: 1.3, w: 4, h: 0.5, fontSize: 20, color: "2C5F2D", bold: true });
slide4.addText("自动控制\n高效便捷\n节能环保", { x: 5.5, y: 1.8, w: 4, h: 2, fontSize: 16, color: "2C5F2D" });
// 第5页：联系方式（简洁收尾）
let slide5 = pres.addSlide();
slide5.addShape(pres.ShapeType.rect, { x: 0, y: 0, w: '100%', h: '100%', fill: { color: '2C5F2D' } });
slide5.addText("联系我们", { x: 0.5, y: 1.5, w: 9, h: 1, fontSize: 36, color: "FFFFFF", bold: true, align: "center" });
slide5.addText("www.example.com\n400-123-4567", { x: 0.5, y: 2.8, w: 9, h: 1, fontSize: 18, color: "97BC62", align: "center" });
Step 4: 保存文件
pres.writeFile({ fileName: "智能家居系统介绍.pptx" });
Step 5: QA检查
# 内容检查
python -m markitdown 智能家居系统介绍.pptx
# 视觉检查
python scripts/thumbnail.py 智能家居系统介绍.pptx
# 检查占位符残留
python -m markitdown 智能家居系统介绍.pptx | grep -iE "xxxx|lorem|ipsum"
检查清单
