PPT Win32COM Editor

定位

本 skill 使用 win32com（PowerPoint COM 接口） 直接打开并修改已有 PPT 文件，完整保留所有原始元素：布局、图片、形状、渐变背景、阴影、箭头连线、FREEFORM 自由形状、SmartArt 等。

绝不从零重建 PPT（新建 PPT 请使用 pptx-generator skill）。

何时使用本 Skill

核心原则

1. 永远在原文件上就地修改，绝不重建
2. 保留所有形状/图片/连接线/特效（python-pptx 会丢弃这些）
3. 先备份：修改前复制原文件为 *_backup.pptx
4. 需要本地安装 Microsoft PowerPoint（win32com 依赖）

环境要求

• Windows 操作系统
• 已安装 Microsoft PowerPoint（2016 或更高版本）
• Python 包：pywin32（通常已随环境安装）
• 操作时 PowerPoint 不可在前台被用户同时使用（COM 独占）

基本工作流

Step 1：备份原文件

import shutil
src = r"C:\path\to\file.pptx"
dst = src.replace(".pptx", "_backup.pptx")
shutil.copy2(src, dst)

Step 2：用 win32com 打开 PPT

import win32com.client

ppt = win32com.client.Dispatch("PowerPoint.Application")
ppt.Visible = True   # 必须设为 True（win32com 限制）
pres = ppt.Presentations.Open(
    r"C:\path\to\file.pptx",
    WithWindow=False,
    ReadOnly=False,
    Untitled=False
)

Step 3：执行修改（见下方常见操作）

Step 4：保存并关闭

pres.Save()
pres.Close()
ppt.Quit()

常见操作速查

详见 references/win32com-ppt-guide.md，以下是最常用操作：

全文替换字体

def replace_font(pptx_path, new_font="Microsoft YaHei", new_size=None):
    import win32com.client
    ppt = win32com.client.Dispatch("PowerPoint.Application")
    ppt.Visible = True
    pres = ppt.Presentations.Open(pptx_path, WithWindow=False, ReadOnly=False, Untitled=False)
    for i in range(1, pres.Slides.Count + 1):
        slide = pres.Slides(i)
        for shape in slide.Shapes:
            if shape.HasTextFrame == -1:
                tr = shape.TextFrame.TextRange
                tr.Font.Name = new_font
                if new_size:
                    tr.Font.Size = new_size
    pres.Save()
    pres.Close()
    ppt.Quit()

全文替换文字颜色

def replace_text_color(pptx_path, hex_color):
    import win32com.client
    # hex_color: "#7CBD3E" 格式，自动转换为 BGR
    r, g, b = int(hex_color[1:3], 16), int(hex_color[3:5], 16), int(hex_color[5:7], 16)
    bgr = (b << 16) | (g << 8) | r
    ppt = win32com.client.Dispatch("PowerPoint.Application")
    ppt.Visible = True
    pres = ppt.Presentations.Open(pptx_path, WithWindow=False, ReadOnly=False, Untitled=False)
    for i in range(1, pres.Slides.Count + 1):
        slide = pres.Slides(i)
        for shape in slide.Shapes:
            if shape.HasTextFrame == -1:
                shape.TextFrame.TextRange.Font.Color.RGB = bgr
    pres.Save()
    pres.Close()
    ppt.Quit()

调整全文段落间距

def adjust_paragraph_spacing(pptx_path, space_before=4, space_after=6, line_spacing=1.5):
    import win32com.client
    ppt = win32com.client.Dispatch("PowerPoint.Application")
    ppt.Visible = True
    pres = ppt.Presentations.Open(pptx_path, WithWindow=False, ReadOnly=False, Untitled=False)
    for i in range(1, pres.Slides.Count + 1):
        slide = pres.Slides(i)
        for shape in slide.Shapes:
            if shape.HasTextFrame == -1:
                tr = shape.TextFrame.TextRange
                for p in range(1, tr.Paragraphs().Count + 1):
                    para = tr.Paragraphs(p)
                    para.ParagraphFormat.SpaceBefore = space_before
                    para.ParagraphFormat.SpaceAfter = space_after
                    para.ParagraphFormat.LineSpacing = line_spacing
    pres.Save()
    pres.Close()
    ppt.Quit()

遍历所有幻灯片的所有文字框

for i in range(1, pres.Slides.Count + 1):
    slide = pres.Slides(i)
    for shape in slide.Shapes:
        if shape.HasTextFrame == -1:
            tf = shape.TextFrame
            tr = tf.TextRange
            print(f"Slide {i}: {tr.Text}")

⚠️ 关键陷阱

1. RGB 颜色是 BGR 顺序！

PowerPoint COM 的 .RGB 属性是 BGR（蓝-绿-红），不是 RGB：

必须转换：bgr = (b << 16) | (g << 8) | r

本 skill 中所有涉及颜色的操作已内置转换函数。

2. COM 索引从 1 开始

Slides(1) 是第一张幻灯片，不是 Slides[0]。

3. Visible 必须设为 True

ppt.Visible = True 是强制要求，win32com 的限制。

4. 不要同时打开同一个文件

PowerPoint 打开文件后会锁定文件，确保之前的操作已调用 Close()。

与 python-pptx / PptxGenJS 的对比

结论：修改已有 PPT → 用本 skill（win32com）；新建 PPT → 用 pptx-generator skill（PptxGenJS）。

参考资料

完整 API 操作指南：references/win32com-ppt-guide.md