名称: pptx 描述: “演示文稿工具包 (.pptx)。创建/编辑幻灯片、布局、内容、演讲者备注、评论,用于程序化演示文稿创建和修改。” 许可证: 专有。LICENSE.txt 包含完整条款
PPTX 创建、编辑和分析
概述
.pptx 文件是一个包含 XML 文件和资源的 ZIP 存档。使用文本提取、原始 XML 访问或 html2pptx 工作流程来创建、编辑或分析 PowerPoint 演示文稿。应用此技能进行程序化演示文稿创建和修改。
使用科学示意图增强视觉效果
使用此技能创建文档时,始终考虑添加科学图表和示意图以增强视觉传达。
如果您的文档尚未包含示意图或图表:
- 使用 scientific-schematics 技能生成 AI 驱动的出版物质量图表
- 只需用自然语言描述您想要的图表
- Nano Banana Pro 将自动生成、审查和完善示意图
对于新文档: 默认应生成科学示意图,以可视化文本中描述的关键概念、工作流程、架构或关系。
如何生成示意图:
python scripts/generate_schematic.py "您的图表描述" -o figures/output.png
AI 将自动:
- 创建具有适当格式的出版物质量图像
- 通过多次迭代审查和完善
- 确保可访问性(色盲友好、高对比度)
- 将输出保存在 figures/ 目录中
何时添加示意图:
- 幻灯片的工作流程图
- 幻灯片设计过程流程图
- 内容组织图
- 系统架构插图
- 过程流可视化
- 任何受益于可视化的复杂概念
有关创建示意图的详细指导,请参阅 scientific-schematics 技能文档。
读取和分析内容
文本提取
要读取演示文稿的文本内容,将文档转换为 markdown:
# 将文档转换为 markdown
python -m markitdown 文件路径.pptx
原始 XML 访问
原始 XML 访问需要用于:评论、演讲者备注、幻灯片布局、动画、设计元素和复杂格式。对于任何这些功能,解包演示文稿并读取其原始 XML 内容。
解包文件
python ooxml/scripts/unpack.py <office文件> <输出目录>
注意:unpack.py 脚本位于项目根目录的 skills/pptx/ooxml/scripts/unpack.py 相对路径下。如果该路径不存在脚本,请使用 find . -name "unpack.py" 定位它。
关键文件结构
ppt/presentation.xml- 主要演示文稿元数据和幻灯片引用ppt/slides/slide{N}.xml- 单个幻灯片内容(slide1.xml、slide2.xml 等)ppt/notesSlides/notesSlide{N}.xml- 每张幻灯片的演讲者备注ppt/comments/modernComment_*.xml- 特定幻灯片的评论ppt/slideLayouts/- 幻灯片布局模板ppt/slideMasters/- 主幻灯片模板ppt/theme/- 主题和样式信息ppt/media/- 图像和其他媒体文件
字体和颜色提取
当给定示例设计以模仿时:始终首先使用以下方法分析演示文稿的字体和颜色:
- 读取主题文件:检查
ppt/theme/theme1.xml以获取颜色(<a:clrScheme>)和字体(<a:fontScheme>) - 示例幻灯片内容:检查
ppt/slides/slide1.xml以获取实际字体使用(<a:rPr>)和颜色 - 搜索模式:使用 grep 在所有 XML 文件中查找颜色(
<a:solidFill>、<a:srgbClr>)和字体引用
创建新的 PowerPoint 演示文稿 无模板
从零开始创建新的 PowerPoint 演示文稿时,使用 html2pptx 工作流程将 HTML 幻灯片转换为具有准确定位的 PowerPoint。
设计原则
关键:在创建任何演示文稿之前,分析内容并选择适当的设计元素:
- 考虑主题:此演示文稿是关于什么的?它暗示了什么语气、行业或情绪?
- 检查品牌:如果用户提到公司/组织,考虑其品牌颜色和标识
- 匹配调色板到内容:选择反映主题的颜色
- 陈述您的方法:在编写代码之前解释您的设计选择
要求:
- ✅ 在编写代码之前陈述您基于内容的设计方法
- ✅ 仅使用网络安全字体:Arial、Helvetica、Times New Roman、Georgia、Courier New、Verdana、Tahoma、Trebuchet MS、Impact
- ✅ 通过大小、重量和颜色创建清晰的视觉层次
- ✅ 确保可读性:强烈对比、适当大小的文本、清洁对齐
- ✅ 保持一致:跨幻灯片重复模式、间距和视觉语言
调色板选择
创造性选择颜色:
- 超越默认:哪些颜色真正匹配这个特定主题?避免自动选择。
- 考虑多个角度:主题、行业、情绪、能量水平、目标受众、品牌标识(如果提到)
- 敢于冒险:尝试意想不到的组合——医疗保健演示文稿不一定是绿色,金融不一定是海军蓝
- 构建您的调色板:选择 3-5 种搭配的颜色(主色 + 辅助色调 + 强调色)
- 确保对比度:文本在背景上必须清晰可读
示例调色板(使用这些激发创造力——选择一个、调整它或创建自己的):
- 经典蓝:深海军蓝 (#1C2833)、板岩灰 (#2E4053)、银色 (#AAB7B8)、米白色 (#F4F6F6)
- 青绿色与珊瑚色:青绿色 (#5EA8A7)、深青绿色 (#277884)、珊瑚色 (#FE4447)、白色 (#FFFFFF)
- 大胆红:红色 (#C0392B)、亮红色 (#E74C3C)、橙色 (#F39C12)、黄色 (#F1C40F)、绿色 (#2ECC71)
- 温暖腮红:淡紫色 (#A49393)、腮红 (#EED6D3)、玫瑰色 (#E8B4B8)、奶油色 (#FAF7F2)
- 勃艮第奢华:勃艮第 (#5D1D2E)、深红色 (#951233)、锈色 (#C15937)、金色 (#997929)
- 深紫色与翡翠绿:紫色 (#B165FB)、深蓝色 (#181B24)、翡翠绿 (#40695B)、白色 (#FFFFFF)
- 奶油色与森林绿:奶油色 (#FFE1C7)、森林绿 (#40695B)、白色 (#FCFCFC)
- 粉色与紫色:粉色 (#F8275B)、珊瑚色 (#FF574A)、玫瑰色 (#FF737D)、紫色 (#3D2F68)
- 酸橙色与李子色:酸橙色 (#C5DE82)、李子色 (#7C3A5F)、珊瑚色 (#FD8C6E)、蓝灰色 (#98ACB5)
- 黑色与金色:金色 (#BF9A4A)、黑色 (#000000)、奶油色 (#F4F6F6)
- 鼠尾草绿与赤陶色:鼠尾草绿 (#87A96B)、赤陶色 (#E07A5F)、奶油色 (#F4F1DE)、炭灰色 (#2C2C2C)
- 炭灰色与红色:炭灰色 (#292929)、红色 (#E33737)、浅灰色 (#CCCBCB)
- 鲜艳橙色:橙色 (#F96D00)、浅灰色 (#F2F2F2)、炭灰色 (#222831)
- 森林绿:黑色 (#191A19)、绿色 (#4E9F3D)、深绿色 (#1E5128)、白色 (#FFFFFF)
- 复古彩虹:紫色 (#722880)、粉色 (#D72D51)、橙色 (#EB5C18)、琥珀色 (#F08800)、金色 (#DEB600)
- 复古大地色:芥末色 (#E3B448)、鼠尾草绿 (#CBD18F)、森林绿 (#3A6B35)、奶油色 (#F4F1DE)
- 海岸玫瑰色:旧玫瑰色 (#AD7670)、海狸色 (#B49886)、蛋壳色 (#F3ECDC)、灰灰色 (#BFD5BE)
- 橙色与绿松石色:浅橙色 (#FC993E)、灰绿松石色 (#667C6F)、白色 (#FCFCFC)
视觉细节选项
几何图案:
- 对角线分隔线代替水平线
- 非对称列宽(30/70、40/60、25/75)
- 旋转文本标题在 90° 或 270°
- 图像的圆形/六边形框架
- 角落的三角形强调形状
- 重叠形状以增加深度
边框与框架处理:
- 仅在单侧使用厚单色边框(10-20pt)
- 具有对比色的双线边框
- 角落支架代替完整框架
- L 形边框(顶部+左侧或底部+右侧)
- 标题下方的下划线强调(3-5pt 厚)
字体处理:
- 极端大小对比(72pt 标题 vs 11pt 正文)
- 大间距的全大写标题
- 超大显示类型的编号部分
- 单间距字体(Courier New)用于数据/统计/技术内容
- 压缩字体(Arial Narrow)用于密集信息
- 轮廓文本以强调
图表与数据样式:
- 单色图表,关键数据使用单强调色
- 水平条形图代替垂直条形图
- 点图代替条形图
- 最少网格线或完全无网格线
- 直接在元素上添加数据标签(无图例)
- 关键指标的 oversized 数字
布局创新:
- 全出血图像,文本叠加
- 侧边栏列(20-30% 宽度)用于导航/上下文
- 模块化网格系统(3×3、4×4 块)
- Z 模式或 F 模式内容流
- 彩色形状上的浮动文本框
- 杂志风格多列布局
背景处理:
- 实色块占用幻灯片的 40-60%
- 渐变填充(仅垂直或对角线)
- 分割背景(两种颜色,对角线或垂直)
- 边到边的色带
- 负空间作为设计元素
布局技巧
对于有图表或表格的幻灯片:
- 两列布局(首选):使用跨全宽的标题,然后下方两列——一列用于文本/项目符号,另一列用于特色内容(图表/表格)。这提供更好的平衡,并使图表/表格更易读。使用具有不等列宽(例如,40%/60% 分割)的 flexbox 以优化每种内容类型的空间。
- 全幻灯片布局:让特色内容(图表/表格)占据整个幻灯片,以获得最大影响力和可读性
- 切勿垂直堆叠:不要将图表/表格放在单列文本下方——这会导致可读性差和布局问题
工作流程
- 必读——读取整个文件:从头到尾完整阅读
html2pptx.md。切勿在读取此文件时设置任何范围限制。 在继续演示文稿创建之前,阅读完整文件内容以获取详细语法、关键格式规则和最佳实践。 - 为每张幻灯片创建具有适当尺寸的 HTML 文件(例如,16:9 的 720pt × 405pt)
- 对所有文本内容使用
<p>、<h1>-<h6>、<ul>、<ol> - 使用
class="placeholder"用于将添加图表/表格的区域(用灰色背景渲染以可见) - 关键:首先使用 Sharp 将渐变和图标栅格化为 PNG 图像,然后在 HTML 中引用
- 布局:对于有图表/表格/图像的幻灯片,使用全幻灯片布局或两列布局以提高可读性
- 对所有文本内容使用
- 使用
html2pptx.js库创建并运行 JavaScript 文件,将 HTML 幻灯片转换为 PowerPoint 并保存演示文稿- 使用
html2pptx()函数处理每个 HTML 文件 - 使用 PptxGenJS API 将图表和表格添加到占位符区域
- 使用
pptx.writeFile()保存演示文稿
- 使用
- 视觉验证:生成缩略图并检查布局问题
- 创建缩略图网格:
python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4 - 读取并仔细检查缩略图图像:
- 文本截断:文本被标题栏、形状或幻灯片边缘截断
- 文本重叠:文本与其他文本或形状重叠
- 定位问题:内容太靠近幻灯片边界或其他元素
- 对比度问题:文本与背景之间的对比度不足
- 如果发现问题,调整 HTML 边距/间距/颜色并重新生成演示文稿
- 重复直到所有幻灯片视觉正确
- 创建缩略图网格:
编辑现有的 PowerPoint 演示文稿
要编辑现有 PowerPoint 演示文稿中的幻灯片,请使用原始 Office Open XML (OOXML) 格式。这涉及解包 .pptx 文件、编辑 XML 内容并重新打包。
工作流程
- 必读——读取整个文件:从头到尾完整阅读
ooxml.md(约 500 行)。切勿在读取此文件时设置任何范围限制。 在任何演示文稿编辑之前,阅读完整文件内容以获取 OOXML 结构和编辑工作流程的详细指导。 - 解包演示文稿:
python ooxml/scripts/unpack.py <office文件> <输出目录> - 编辑 XML 文件(主要是
ppt/slides/slide{N}.xml和相关文件) - 关键:每次编辑后立即验证,并在继续之前修复任何验证错误:
python ooxml/scripts/validate.py <目录> --original <文件> - 打包最终演示文稿:
python ooxml/scripts/pack.py <输入目录> <office文件>
创建新的 PowerPoint 演示文稿 使用模板
要创建遵循现有模板设计的演示文稿,请复制和重新排列模板幻灯片,然后替换占位符内容。
工作流程
-
提取模板文本并创建视觉缩略图网格:
- 提取文本:
python -m markitdown template.pptx > template-content.md - 读取
template-content.md:读取整个文件以了解模板演示文稿的内容。切勿在读取此文件时设置任何范围限制。 - 创建缩略图网格:
python scripts/thumbnail.py template.pptx - 更多详情,请参阅 创建缩略图网格 部分
- 提取文本:
-
分析模板并将清单保存到文件:
- 视觉分析:审查缩略图网格以理解幻灯片布局、设计模式和视觉结构
- 在
template-inventory.md处创建并保存模板清单文件,包含:# 模板清单分析 **总幻灯片数:[数量]** **重要:幻灯片是 0 索引(第一张幻灯片 = 0,最后一张幻灯片 = 数量-1)** ## [类别名称] - 幻灯片 0: [布局代码(如果可用)] - 描述/用途 - 幻灯片 1: [布局代码] - 描述/用途 - 幻灯片 2: [布局代码] - 描述/用途 [... 必须单独列出每张幻灯片及其索引 ...] - 使用缩略图网格:参考视觉缩略图以识别:
- 布局模式(标题幻灯片、内容布局、部分分隔符)
- 图像占位符位置和数量
- 跨幻灯片组的设计一致性
- 视觉层次和结构
- 此清单文件是下一步选择适当模板所必需的
-
基于模板清单创建演示文稿大纲:
- 从步骤 2 审查可用模板。
- 为第一张幻灯片选择介绍或标题模板。这应该是第一个模板之一。
- 为其他幻灯片选择安全、基于文本的布局。
- 关键:匹配布局结构到实际内容:
- 单列布局:用于统一叙述或单一主题
- 两列布局:仅当恰好有 2 个不同项目/概念时使用
- 三列布局:仅当恰好有 3 个不同项目/概念时使用
- 图像+文本布局:仅当有实际图像可插入时使用
- 引用布局:仅用于实际人物引用(带归属),切勿用于强调
- 切勿使用占位符多于可用内容的布局
- 如果有 2 个项目,不要将它们强行塞入 3 列布局
- 如果有 4+ 个项目,考虑分成多张幻灯片或使用列表格式
- 在选择布局之前计算实际内容片段的数量
- 验证所选布局中的每个占位符将被填充有意义的内容
- 为每个内容部分选择代表最佳布局的一个选项。
- 保存
outline.md,包含内容和利用可用设计的模板映射 - 示例模板映射:
# 要使用的模板幻灯片(0-based 索引) # 警告:验证索引在范围内!具有 73 张幻灯片的模板有索引 0-72 # 映射:大纲中的幻灯片编号 -> 模板幻灯片索引 template_mapping = [ 0, # 使用幻灯片 0(标题/封面) 34, # 使用幻灯片 34(B1: 标题和正文) 34, # 再次使用幻灯片 34(为第二个 B1 复制) 50, # 使用幻灯片 50(E1: 引用) 54, # 使用幻灯片 54(F2: 结束 + 文本) ]
-
使用
rearrange.py复制、重新排序和删除幻灯片:- 使用
scripts/rearrange.py脚本创建具有所需顺序幻灯片的新演示文稿:python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52 - 该脚本处理复制重复幻灯片、删除未使用幻灯片和自动重新排序
- 幻灯片索引是 0-based(第一张幻灯片是 0,第二张是 1,等等)
- 同一幻灯片索引可以出现多次以复制该幻灯片
- 使用
-
使用
inventory.py脚本提取所有文本:-
运行清单提取:
python scripts/inventory.py working.pptx text-inventory.json -
读取 text-inventory.json:读取整个 text-inventory.json 文件以了解所有形状及其属性。切勿在读取此文件时设置任何范围限制。
-
清单 JSON 结构:
{ "slide-0": { "shape-0": { "placeholder_type": "TITLE", // 或 null 表示非占位符 "left": 1.5, // 位置,英寸 "top": 2.0, "width": 7.5, "height": 1.2, "paragraphs": [ { "text": "段落文本", // 可选属性(仅在非默认时包括): "bullet": true, // 检测到显式项目符号 "level": 0, // 仅当 bullet 为 true 时包括 "alignment": "CENTER", // CENTER, RIGHT(不是 LEFT) "space_before": 10.0, // 段落前间距,点 "space_after": 6.0, // 段落后间距,点 "line_spacing": 22.4, // 行间距,点 "font_name": "Arial", // 从第一个运行 "font_size": 14.0, // 点 "bold": true, "italic": false, "underline": false, "color": "FF0000" // RGB 颜色 } ] } } } -
关键特征:
- 幻灯片:命名为 “slide-0”、“slide-1” 等
- 形状:按视觉位置(从上到下,从左到右)排序为 “shape-0”、“shape-1” 等
- 占位符类型:TITLE、CENTER_TITLE、SUBTITLE、BODY、OBJECT 或 null
- 默认字体大小:从布局占位符提取的
default_font_size点(如果可用) - 幻灯片编号被过滤:具有 SLIDE_NUMBER 占位符类型的形状自动从清单中排除
- 项目符号:当
bullet: true时,level总是包括(即使是 0) - 间距:点中的
space_before、space_after和line_spacing(仅在设置时包括) - 颜色:RGB 的
color(例如 “FF0000”),主题颜色的theme_color(例如 “DARK_1”) - 属性:仅非默认值包括在输出中
-
-
生成替换文本并将数据保存到 JSON 文件 基于上一步的文本清单:
- 关键:首先验证清单中存在哪些形状——仅引用实际存在的形状
- 验证:replace.py 脚本将验证替换 JSON 中的所有形状是否存在于清单中
- 如果引用不存在的形状,错误将显示可用形状
- 如果引用不存在的幻灯片,错误将指示幻灯片不存在
- 所有验证错误在脚本退出前显示一次
- 重要:replace.py 脚本在内部使用 inventory.py 来识别所有文本形状
- 自动清除:来自清单的所有文本形状将被清除,除非您为它们提供 “paragraphs”
- 为需要内容的形状添加 “paragraphs” 字段(不是 “replacement_paragraphs”)
- 替换 JSON 中没有 “paragraphs” 的形状将自动清除其文本
- 具有项目符号的段落将自动左对齐。当
"bullet": true时,不要设置alignment属性 - 为占位符文本生成适当的替换内容
- 使用形状大小确定适当的内容长度
- 关键:包括原始清单中的段落属性——不要只提供文本
- 重要:当 bullet: true 时,不要在文本中包括项目符号符号(•、-、*)——它们自动添加
- 基本格式规则:
- 标题/标题通常应有
"bold": true - 列表项应有
"bullet": true, "level": 0(当 bullet 为 true 时,level 是必需的) - 保留任何对齐属性(例如,居中文本的
"alignment": "CENTER") - 当与默认不同时,包括字体属性(例如
"font_size": 14.0、"font_name": "Lora") - 颜色:使用
"color": "FF0000"表示 RGB 或"theme_color": "DARK_1"表示主题颜色 - 替换脚本期望正确格式化的段落,不仅仅是文本字符串
- 重叠形状:优选具有更大 default_font_size 或更合适 placeholder_type 的形状
- 标题/标题通常应有
- 将带有替换的更新清单保存到
replacement-text.json - 警告:不同模板布局具有不同的形状计数——在创建替换之前始终检查实际清单
示例 paragraphs 字段显示正确格式:
"paragraphs": [ { "text": "新演示文稿标题文本", "alignment": "CENTER", "bold": true }, { "text": "部分标题", "bold": true }, { "text": "第一项项目符号点,无项目符号符号", "bullet": true, "level": 0 }, { "text": "红色文本", "color": "FF0000" }, { "text": "主题色文本", "theme_color": "DARK_1" }, { "text": "无特殊格式的常规段落文本" } ]未列在替换 JSON 中的形状自动清除:
{ "slide-0": { "shape-0": { "paragraphs": [...] // 此形状获得新文本 } // 清单中的 shape-1 和 shape-2 将自动清除 } }演示文稿的常见格式模式:
- 标题幻灯片:粗体文本,有时居中
- 幻灯片内的部分标题:粗体文本
- 项目符号列表:每个项目需要
"bullet": true, "level": 0 - 正文文本:通常无需特殊属性
- 引用:可能有特殊对齐或字体属性
-
使用
replace.py脚本应用替换python scripts/replace.py working.pptx replacement-text.json output.pptx脚本将:
- 首先使用 inventory.py 的函数提取所有文本形状的清单
- 验证替换 JSON 中的所有形状是否存在于清单中
- 清除清单中识别的所有形状的文本
- 仅将新文本应用于替换 JSON 中定义了 “paragraphs” 的形状
- 通过从 JSON 应用段落属性来保留格式
- 自动处理项目符号、对齐、字体属性和颜色
- 保存更新后的演示文稿
示例验证错误:
错误:替换 JSON 中的无效形状: - 形状 'shape-99' 在 'slide-0' 上未找到。可用形状:shape-0, shape-1, shape-4 - 清单中未找到幻灯片 'slide-999'错误:替换文本在这些形状中使溢出恶化: - slide-0/shape-2: 溢出恶化 1.25"(原来是 0.00",现在是 1.25")
创建缩略图网格
要创建 PowerPoint 幻灯片的视觉缩略图网格以进行快速分析和参考:
python scripts/thumbnail.py template.pptx [输出前缀]
特征:
- 创建:
thumbnails.jpg(或大型幻灯片的thumbnails-1.jpg、thumbnails-2.jpg等) - 默认:5 列,每网格最多 30 张幻灯片(5×6)
- 自定义前缀:
python scripts/thumbnail.py template.pptx my-grid- 注意:如果您希望输出在特定目录中,输出前缀应包括路径(例如
workspace/my-grid)
- 注意:如果您希望输出在特定目录中,输出前缀应包括路径(例如
- 调整列:
--cols 4(范围:3-6,影响每网格幻灯片数) - 网格限制:3 列 = 12 张幻灯片/网格,4 列 = 20,5 列 = 30,6 列 = 42
- 幻灯片是 0 索引(幻灯片 0、幻灯片 1 等)
用例:
- 模板分析:快速理解幻灯片布局和设计模式
- 内容审查:整个演示文稿的视觉概述
- 导航参考:通过视觉外观查找特定幻灯片
- 质量检查:验证所有幻灯片格式正确
示例:
# 基本用法
python scripts/thumbnail.py presentation.pptx
# 组合选项:自定义名称、列
python scripts/thumbnail.py template.pptx analysis --cols 4
将幻灯片转换为图像
要视觉分析 PowerPoint 幻灯片,使用两步过程将它们转换为图像:
-
将 PPTX 转换为 PDF:
soffice --headless --convert-to pdf template.pptx -
将 PDF 页面转换为 JPEG 图像:
pdftoppm -jpeg -r 150 template.pdf slide创建文件如
slide-1.jpg、slide-2.jpg等。
选项:
-r 150:设置分辨率为 150 DPI(调整质量和大小平衡)-jpeg:输出 JPEG 格式(如果偏好 PNG,使用-png)-f N:要转换的第一页(例如-f 2从第 2 页开始)-l N:要转换的最后一页(例如-l 5在第 5 页停止)slide:输出文件的前缀
特定范围的示例:
pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide # 仅转换页面 2-5
代码风格指南
重要:当生成 PPTX 操作的代码时:
- 编写简洁代码
- 避免冗长变量名和冗余操作
- 避免不必要的打印语句
依赖项
必需的依赖项(应已安装):
- markitdown:
pip install "markitdown[pptx]"(用于从演示文稿提取文本) - pptxgenjs:
npm install -g pptxgenjs(用于通过 html2pptx 创建演示文稿) - playwright:
npm install -g playwright(用于 html2pptx 中的 HTML 渲染) - react-icons:
npm install -g react-icons react react-dom(用于图标) - sharp:
npm install -g sharp(用于 SVG 栅格化和图像处理) - LibreOffice:
sudo apt-get install libreoffice(用于 PDF 转换) - Poppler:
sudo apt-get install poppler-utils(用于 pdftoppm 将 PDF 转换为图像) - defusedxml:
pip install defusedxml(用于安全 XML 解析)