1. 什么是 python-pptx？ #

python-pptx 是一个专门用于读写 .pptx 格式（PowerPoint 2007 及以上版本）文件的 Python 库。它可以帮助你通过编写 Python 代码来自动创建、修改 PowerPoint 演示文稿，非常适合批量生成报告、标准化会议材料、数据分析结果可视化等场景。

核心特点：

• 面向对象的 API 设计，结构清晰：演示文稿（Presentation）→ 幻灯片（Slide）→ 形状（Shape）→ 文本框/图片/表格等
• 支持创建新演示文稿，也支持读取和修改现有演示文稿
• 可以控制文本格式、插入图片、创建表格和图表等

适用场景：

• 定期生成销售报告、财务报告等标准化文档
• 批量处理多个演示文稿
• 将数据分析结果自动转换为 PPT 展示
• 根据模板快速生成个性化演示文稿

学习前提：

• 需要掌握基础 Python 语法（变量、函数、列表、字典等）
• 了解 PowerPoint 的基本概念（幻灯片、文本框、布局等）会更容易上手
• 不需要深入了解 PowerPoint 的高级功能，本教程会从零开始讲解

2. 安装 python-pptx #

在开始使用之前，需要先安装 python-pptx 库。同时建议安装 pillow 库，用于处理图片操作。

2.1 Windows 系统安装步骤 #

在 Windows 系统中，打开 PowerShell 或命令提示符（CMD），执行以下命令：

# 首先升级 pip 到最新版本（可选，但推荐）
python -m pip install --upgrade pip

# 安装 python-pptx 和 pillow
python -m pip install python-pptx pillow

注意事项：

• 如果系统中有多个 Python 版本，可能需要使用 python3 代替 python
• 如果提示权限不足，可以在命令前加上 --user 参数，例如：python -m pip install --user python-pptx pillow

2.2 macOS 系统安装步骤 #

在 macOS 系统中，打开终端（Terminal），执行以下命令：

# 首先升级 pip 到最新版本（可选，但推荐）
python3 -m pip install --upgrade pip

# 安装 python-pptx 和 pillow
python3 -m pip install python-pptx pillow

注意事项：

• macOS 系统通常需要使用 python3 命令
• 如果提示找不到 python3，可能需要先安装 Python，推荐从 python.org 下载安装

2.3 验证安装 #

安装完成后，可以通过以下方式验证是否安装成功：

# 导入库，如果没有报错说明安装成功
from pptx import Presentation
print("python-pptx 安装成功！")

3. 前置知识补充 #

在深入学习之前，我们先了解一些基础概念，这些知识会帮助你更好地理解后续内容。

3.1 PowerPoint 基本概念 #

演示文稿（Presentation）： 整个 PPT 文件，包含多张幻灯片。

幻灯片（Slide）： 演示文稿中的一页，类似于 Word 文档中的一页。

布局（Layout）： 幻灯片的模板样式，比如"标题幻灯片"、"标题和内容"、"空白"等。不同的布局有不同的占位符位置。

占位符（Placeholder）： 幻灯片上预留的位置，用于放置标题、文本、图片等内容。每个布局都有固定的占位符。

形状（Shape）： 幻灯片上的所有元素都称为形状，包括文本框、图片、表格、图表等。

3.2 Python 基础回顾 #

如果你对以下 Python 概念不熟悉，建议先学习：

• 导入模块： from pptx import Presentation 表示从 pptx 库中导入 Presentation 类
• 对象和方法： prs.slides.add_slide() 表示调用 prs 对象的 slides 属性的 add_slide 方法
• 列表和字典： 用于存储和组织数据
• 循环： for 循环用于批量处理数据

4. 创建最简单的 PPT #

让我们从一个最简单的例子开始，创建一个只有一张标题幻灯片的演示文稿。这个例子会帮助你理解 python-pptx 的基本工作流程。

工作流程：

1. 导入必要的类
2. 创建一个空的演示文稿对象
3. 选择布局并添加幻灯片
4. 填充内容（标题和副标题）
5. 保存文件

# 从 pptx 库中导入 Presentation 类，这是创建和操作 PPT 的核心类
from pptx import Presentation

# 创建一个空白的演示文稿对象，相当于创建了一个新的 PPT 文件
prs = Presentation()

# 获取演示文稿中的第一个布局（索引为 0），这是"标题幻灯片"布局
slide_layout = prs.slide_layouts[0]

# 使用选定的布局添加一张新幻灯片到演示文稿中
slide = prs.slides.add_slide(slide_layout)

# 设置幻灯片的标题文本
slide.shapes.title.text = "Python 自动化PPT"

# 设置幻灯片的副标题文本（placeholders[1] 表示第二个占位符，通常是副标题）
slide.placeholders[1].text = "基于 python-pptx 的快速示例"

# 将演示文稿保存为 .pptx 文件，文件名可以自定义
prs.save("quick_start.pptx")

# 打印提示信息，告知用户文件已生成
print("演示文稿已生成：quick_start.pptx")

运行说明：

• 将上述代码保存为 first_ppt.py 文件
• 在终端或命令行中运行：python first_ppt.py（Windows）或 python3 first_ppt.py（macOS）
• 运行后会在当前目录生成 quick_start.pptx 文件，用 PowerPoint 打开即可查看

代码解释：

• Presentation() 创建一个新的演示文稿对象
• slide_layouts[0] 表示使用第一个布局（通常是标题幻灯片）
• add_slide() 方法添加新幻灯片
• shapes.title 访问标题占位符
• placeholders[1] 访问第二个占位符（通常是副标题）
• save() 方法保存文件

5. 了解幻灯片布局 #

PowerPoint 提供了多种预设布局，不同的布局适合不同的内容类型。了解这些布局有助于选择合适的样式。

常见布局类型：

• 布局 0：标题幻灯片（Title Slide）- 用于封面
• 布局 1：标题和内容（Title and Content）- 最常用的内容页
• 布局 2：节标题（Section Header）- 用于分章节
• 布局 3：两栏内容（Two Content）- 左右分栏
• 布局 6：空白（Blank）- 完全空白，自由设计

下面的代码会列出所有可用的布局，并演示如何使用不同的布局创建幻灯片。

# 导入 Presentation 类
from pptx import Presentation

# 创建一个新的演示文稿对象
prs = Presentation()

# 遍历并打印所有可用的布局信息，帮助了解每个布局的名称
print("可用的幻灯片布局：")
for idx, layout in enumerate(prs.slide_layouts):
    print(f"布局 {idx}: {layout.name}")

# 定义要创建的幻灯片计划，每个元组包含（标题, 布局编号）
slides_plan = [
    ("执行摘要", 1),    # 使用布局 1（标题和内容）
    ("业务亮点", 1),    # 使用布局 1（标题和内容）
    ("市场分析", 3),    # 使用布局 3（两栏内容）
    ("财务数据", 1)     # 使用布局 1（标题和内容）
]

# 根据计划批量创建幻灯片
for title, layout_idx in slides_plan:
    # 获取指定索引的布局
    slide_layout = prs.slide_layouts[layout_idx]
    # 使用该布局添加新幻灯片
    slide = prs.slides.add_slide(slide_layout)
    # 设置幻灯片的标题
    slide.shapes.title.text = title

# 保存演示文稿
prs.save("slides_layout_demo.pptx")

# 打印提示信息
print("\n演示文稿已生成：slides_layout_demo.pptx")
print(f"共创建了 {len(prs.slides)} 张幻灯片")

运行说明：

• 保存代码并运行，会生成包含 4 张幻灯片的演示文稿
• 运行时会先打印所有可用布局的信息，方便你了解有哪些布局可以选择

布局选择建议：

• 封面页：使用布局 0（标题幻灯片）
• 普通内容页：使用布局 1（标题和内容）
• 需要左右对比：使用布局 3（两栏内容）
• 需要完全自定义：使用布局 6（空白）

6. 读取现有演示文稿 #

有时候我们需要在已有的 PPT 文件基础上进行修改，或者查看现有文件的内容结构。python-pptx 可以读取现有的演示文稿文件。

常见用途：

• 查看现有 PPT 的结构和内容
• 在模板基础上添加新内容
• 批量修改现有演示文稿

下面的代码演示如何读取并查看现有演示文稿的信息。

# 导入 Presentation 类
from pptx import Presentation

# 定义一个函数，用于查看演示文稿的详细信息
def inspect_ppt(path: str):
    """
    读取并查看 PPT 文件的信息
    参数 path: PPT 文件的路径
    """
    # 打开指定的演示文稿文件
    prs = Presentation(path)

    # 打印幻灯片总数
    print(f"幻灯片数量：{len(prs.slides)}")
    print("-" * 50)

    # 遍历每一张幻灯片
    for idx, slide in enumerate(prs.slides, start=1):
        # 尝试获取标题，如果没有标题则显示"（无标题）"
        if slide.shapes.title:
            title = slide.shapes.title.text
        else:
            title = "（无标题）"

        # 打印幻灯片编号和标题
        print(f"第 {idx} 页标题：{title}")

        # 遍历幻灯片中的所有形状（文本框、图片等）
        for shape in slide.shapes:
            # 检查形状是否有 text 属性（即是否为文本框）
            if hasattr(shape, "text") and shape.text.strip():
                # 打印文本内容的前 30 个字符
                text_preview = shape.text[:30] + "..." if len(shape.text) > 30 else shape.text
                print(f"  - 文本内容：{text_preview}")

        print("-" * 50)

# 示例：读取之前生成的 quick_start.pptx 文件
# 注意：如果文件不存在，会报错，所以先用 try-except 处理
try:
    inspect_ppt("quick_start.pptx")
except FileNotFoundError:
    print("错误：找不到 quick_start.pptx 文件")
    print("请先运行第一个示例生成该文件")
except Exception as e:
    print(f"读取文件时出错：{e}")

运行说明：

• 如果之前已经运行过第一个示例并生成了 quick_start.pptx，可以直接运行此代码
• 如果文件不存在，代码会给出友好的错误提示

扩展应用：

• 可以修改函数，提取所有文本内容保存到文件
• 可以统计每张幻灯片的元素数量
• 可以批量修改现有 PPT 中的文本内容

7. 文本格式设置 #

文本是 PPT 的核心内容，掌握文本格式设置非常重要。本节学习如何添加文本框、设置字体大小、颜色、对齐方式等。

文本格式包括：

• 字体大小（size）
• 字体颜色（color）
• 粗体/斜体（bold/italic）
• 对齐方式（左对齐、居中、右对齐）
• 项目符号（bullet points）

下面的代码演示如何创建格式化的文本内容。

# 导入 Presentation 类
from pptx import Presentation

# 导入尺寸单位工具，Inches 用于指定英寸，Pt 用于指定磅（字体大小单位）
from pptx.util import Inches, Pt

# 导入文本对齐方式枚举
from pptx.enum.text import PP_ALIGN

# 导入颜色工具，用于设置 RGB 颜色
from pptx.dml.color import RGBColor

# 创建新的演示文稿对象
prs = Presentation()

# 添加一张空白幻灯片（布局 6 是空白布局）
slide = prs.slides.add_slide(prs.slide_layouts[6])

# 在幻灯片上添加一个文本框
# 参数：左边距、上边距、宽度、高度（单位都是英寸）
textbox = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(8), Inches(3))

# 获取文本框的文本框架对象，用于操作文本内容
tf = textbox.text_frame

# 设置第一个段落（默认存在的段落）的文本内容
p1 = tf.paragraphs[0]
p1.text = "文本格式示例"

# 设置段落对齐方式为居中
p1.alignment = PP_ALIGN.CENTER

# 获取段落中第一个文本运行（run）的字体对象
font1 = p1.runs[0].font

# 设置字体大小为 28 磅
font1.size = Pt(28)

# 设置字体为粗体
font1.bold = True

# 设置字体颜色为蓝色（RGB 值：0, 102, 204）
font1.color.rgb = RGBColor(0, 102, 204)

# 添加第二个段落
p2 = tf.add_paragraph()
p2.text = "python-pptx 支持调节字体、颜色、对齐、项目符号等格式。"

# 设置段落级别为 0（顶级，无缩进）
p2.level = 0

# 添加第三个段落（带项目符号）
p3 = tf.add_paragraph()
p3.text = "支持多级项目符号"
p3.level = 0  # 一级项目符号

# 添加第四个段落（二级项目符号）
p4 = tf.add_paragraph()
p4.text = "例如这里是二级项目"
p4.level = 1  # 二级项目符号（会有缩进）

# 保存演示文稿
prs.save("text_format_demo.pptx")

# 打印提示信息
print("演示文稿已生成：text_format_demo.pptx")

运行说明：

• 运行后会生成一个包含格式化文本的演示文稿
• 可以打开文件查看效果，包括居中的蓝色标题、普通正文和多级项目符号

常用格式设置：

• Pt(12) 表示 12 磅字体（常用正文大小）
• Pt(18) 表示 18 磅字体（小标题）
• Pt(24) 表示 24 磅字体（标题）
• RGBColor(255, 0, 0) 表示红色
• RGBColor(0, 255, 0) 表示绿色
• RGBColor(0, 0, 255) 表示蓝色

8. 插入图片和形状 #

除了文本，PPT 中经常需要插入图片和绘制形状（如矩形、圆形、箭头等）。本节学习如何添加这些元素。

图片操作：

• 插入本地图片文件
• 调整图片大小和位置
• 处理图片不存在的情况

形状操作：

• 绘制矩形、圆形等基本形状
• 设置形状的填充颜色和边框
• 在形状中添加文本

下面的代码演示如何插入图片和创建形状。

# 导入 Presentation 类
from pptx import Presentation

# 导入尺寸单位工具
from pptx.util import Inches, Pt

# 导入颜色工具
from pptx.dml.color import RGBColor

# 创建新的演示文稿对象
prs = Presentation()

# 添加一张空白幻灯片
slide = prs.slides.add_slide(prs.slide_layouts[6])

# 尝试插入图片
# 注意：需要将 "sample.jpg" 替换为你实际的图片路径
img_path = "sample.jpg"

try:
    # 添加图片到幻灯片
    # 参数：图片路径、左边距、上边距、宽度（高度会自动按比例缩放）
    slide.shapes.add_picture(img_path, Inches(1), Inches(1), width=Inches(4))
    print("图片插入成功")
except FileNotFoundError:
    # 如果图片文件不存在，创建一个占位形状
    print("图片文件不存在，创建占位符")

    # 添加一个矩形形状作为占位符
    # 参数：形状类型（1=矩形）、左边距、上边距、宽度、高度
    placeholder = slide.shapes.add_shape(1, Inches(1), Inches(1), Inches(4), Inches(3))

    # 在占位符中添加文本
    placeholder.text = "图片占位符\n（请替换为实际图片）"

    # 设置填充为纯色
    placeholder.fill.solid()

    # 设置填充颜色为浅灰色
    placeholder.fill.fore_color.rgb = RGBColor(200, 200, 200)

# 添加一个彩色矩形形状
rect = slide.shapes.add_shape(1, Inches(6), Inches(1), Inches(2), Inches(1))

# 在矩形中添加文本
rect.text = "矩形"

# 设置填充为纯色
rect.fill.solid()

# 设置填充颜色为蓝色
rect.fill.fore_color.rgb = RGBColor(0, 176, 240)

# 设置边框宽度为 2 磅
rect.line.width = Pt(2)

# 保存演示文稿
prs.save("image_shape_demo.pptx")

# 打印提示信息
print("演示文稿已生成：image_shape_demo.pptx")

运行说明：

• 如果有图片文件，将 img_path 改为实际路径
• 如果没有图片，代码会创建占位符，不会报错
• 运行后会生成包含形状的演示文稿

常用形状类型：

• 1：矩形（MSO_SHAPE.RECTANGLE）
• 5：椭圆/圆形（MSO_SHAPE.OVAL）
• 10：箭头（MSO_SHAPE.RIGHT_ARROW）

图片格式支持：

• 支持常见图片格式：JPG、PNG、GIF、BMP 等
• 建议使用 JPG 或 PNG 格式以获得最佳兼容性

9. 创建表格 #

表格是展示结构化数据的最佳方式，比如销售数据、统计数据等。本节学习如何创建表格并设置样式。

表格操作包括：

• 创建指定行数和列数的表格
• 填充表格数据
• 设置表头样式（背景色、文字颜色等）
• 设置单元格对齐方式

下面的代码演示如何创建一个季度销售数据表格。

# 导入 Presentation 类
from pptx import Presentation

# 导入尺寸单位工具
from pptx.util import Inches, Pt

# 导入颜色工具
from pptx.dml.color import RGBColor

# 导入文本对齐方式枚举
from pptx.enum.text import PP_ALIGN

# 准备表格数据（二维列表）
# 第一行是表头，后续行是数据
rows = [
    ["产品", "Q1", "Q2", "Q3", "Q4"],
    ["A", "120", "150", "180", "210"],
    ["B", "90", "110", "140", "160"],
    ["C", "200", "220", "240", "260"]
]

# 创建新的演示文稿对象
prs = Presentation()

# 添加一张空白幻灯片
slide = prs.slides.add_slide(prs.slide_layouts[6])

# 添加表格到幻灯片
# 参数：行数、列数、左边距、上边距、宽度、高度
table_shape = slide.shapes.add_table(
    len(rows),           # 行数
    len(rows[0]),        # 列数（使用第一行的列数）
    Inches(0.5),         # 左边距
    Inches(1),           # 上边距
    Inches(9),           # 表格宽度
    Inches(3)            # 表格高度
)

# 获取表格对象
table = table_shape.table

# 遍历数据，填充表格
for r_idx, row in enumerate(rows):
    # 遍历每一行的每个单元格
    for c_idx, value in enumerate(row):
        # 获取指定位置的单元格
        cell = table.cell(r_idx, c_idx)

        # 设置单元格的文本内容
        cell.text = value

        # 设置单元格内所有段落的格式
        for paragraph in cell.text_frame.paragraphs:
            # 设置对齐方式为居中
            paragraph.alignment = PP_ALIGN.CENTER

            # 设置字体大小为 14 磅
            paragraph.font.size = Pt(14)

        # 如果是第一行（表头），设置特殊样式
        if r_idx == 0:
            # 设置填充为纯色
            cell.fill.solid()

            # 设置背景颜色为深蓝色
            cell.fill.fore_color.rgb = RGBColor(0, 51, 102)

            # 设置文字颜色为白色
            cell.text_frame.paragraphs[0].font.color.rgb = RGBColor(255, 255, 255)

            # 设置表头文字为粗体
            cell.text_frame.paragraphs[0].font.bold = True

# 保存演示文稿
prs.save("table_demo.pptx")

# 打印提示信息
print("演示文稿已生成：table_demo.pptx")
print(f"表格大小：{len(rows)} 行 × {len(rows[0])} 列")

运行说明：

• 运行后会生成一个包含销售数据表格的演示文稿
• 表头会有深蓝色背景和白色文字，数据行是普通样式

表格设计建议：

• 表头使用深色背景和浅色文字，提高可读性
• 数据行使用浅色背景，避免视觉疲劳
• 数字列建议右对齐，文本列建议左对齐
• 表格不要太大，建议不超过 10 行，否则需要分页

10. 插入图表 #

图表是数据可视化的重要工具。python-pptx 支持创建基础图表，如柱状图、折线图、饼图等。本节以柱状图为例进行讲解。

图表类型：

• 柱状图（Column Chart）- 用于对比不同类别的数据
• 折线图（Line Chart）- 用于显示趋势
• 饼图（Pie Chart）- 用于显示比例关系

下面的代码演示如何创建一个季度销量对比的柱状图。

# 导入 Presentation 类
from pptx import Presentation

# 导入尺寸单位工具
from pptx.util import Inches

# 导入图表数据类
from pptx.chart.data import ChartData

# 导入图表类型和图例位置枚举
from pptx.enum.chart import XL_CHART_TYPE, XL_LEGEND_POSITION

# 创建图表数据对象
chart_data = ChartData()

# 设置图表的分类（X 轴标签）
chart_data.categories = ["产品A", "产品B", "产品C"]

# 添加数据系列（每个系列对应一组数据）
# 参数：系列名称、数据元组
chart_data.add_series("Q1", (120, 80, 150))
chart_data.add_series("Q2", (150, 95, 180))
chart_data.add_series("Q3", (180, 110, 210))
chart_data.add_series("Q4", (210, 140, 230))

# 创建新的演示文稿对象
prs = Presentation()

# 添加一张空白幻灯片
slide = prs.slides.add_slide(prs.slide_layouts[6])

# 在幻灯片上添加图表
chart_frame = slide.shapes.add_chart(
    XL_CHART_TYPE.COLUMN_CLUSTERED,  # 图表类型：簇状柱形图
    Inches(0.5),                      # 左边距
    Inches(1),                        # 上边距
    Inches(9),                        # 图表宽度
    Inches(5),                        # 图表高度
    chart_data                        # 图表数据
)

# 获取图表对象
chart = chart_frame.chart

# 启用图表标题
chart.has_title = True

# 设置图表标题文本
chart.chart_title.text_frame.text = "季度销量对比"

# 启用图例
chart.has_legend = True

# 设置图例位置为底部
chart.legend.position = XL_LEGEND_POSITION.BOTTOM

# 保存演示文稿
prs.save("chart_demo.pptx")

# 打印提示信息
print("演示文稿已生成：chart_demo.pptx")

运行说明：

• 运行后会生成一个包含柱状图的演示文稿
• 图表会显示三个产品在四个季度的销量对比

常用图表类型：

• XL_CHART_TYPE.COLUMN_CLUSTERED：簇状柱形图（最常用）
• XL_CHART_TYPE.COLUMN_STACKED：堆积柱形图
• XL_CHART_TYPE.LINE：折线图
• XL_CHART_TYPE.PIE：饼图

图表设计建议：

• 图表标题要清晰说明图表内容
• 图例位置可以根据空间选择：顶部、底部、左侧、右侧
• 数据系列不要太多，建议不超过 5 个，否则图表会显得拥挤

11. 综合示例：自动化报告生成器 #

前面学习了各种功能，现在我们将它们组合起来，创建一个完整的自动化报告生成器。这个示例会生成一个包含标题页、摘要页、数据表格页和图表页的完整报告。

报告结构：

1. 标题页：报告标题和副标题
2. 摘要页：关键信息要点
3. 数据表格页：详细数据表格
4. 图表页：数据可视化图表

下面的代码是一个完整的报告生成器类，可以复用。

# 导入所需模块
from pptx import Presentation
from pptx.util import Inches, Pt
from pptx.chart.data import ChartData
from pptx.enum.chart import XL_CHART_TYPE

# 定义报告生成器类
class SalesReport:
    """销售报告生成器类"""

    def __init__(self):
        """初始化，创建新的演示文稿对象"""
        self.prs = Presentation()

    def build(self, data: dict, output: str):
        """
        构建完整的报告
        参数 data: 包含报告数据的字典
        参数 output: 输出文件名
        """
        # 添加标题页
        self._add_title_slide(data["title"], data["subtitle"])

        # 添加摘要页
        self._add_summary_slide(data["summary"])

        # 添加数据表格页
        self._add_table_slide(data["table"])

        # 添加图表页
        self._add_chart_slide(data["chart"])

        # 保存文件
        self.prs.save(output)

        # 打印提示信息
        print(f"报告已生成：{output}")
        print(f"共 {len(self.prs.slides)} 张幻灯片")

    def _add_title_slide(self, title, subtitle):
        """添加标题页"""
        # 使用布局 0（标题幻灯片）
        slide = self.prs.slides.add_slide(self.prs.slide_layouts[0])

        # 设置标题
        slide.shapes.title.text = title

        # 设置副标题（第二个占位符）
        slide.placeholders[1].text = subtitle

    def _add_summary_slide(self, points):
        """添加摘要页"""
        # 使用布局 1（标题和内容）
        slide = self.prs.slides.add_slide(self.prs.slide_layouts[1])

        # 设置标题
        slide.shapes.title.text = "执行摘要"

        # 获取内容占位符的文本框架
        tf = slide.placeholders[1].text_frame

        # 设置第一段文本
        tf.text = points[0]

        # 添加后续要点
        for pt in points[1:]:
            p = tf.add_paragraph()
            p.text = pt

    def _add_table_slide(self, table_rows):
        """添加数据表格页"""
        # 使用布局 6（空白）
        slide = self.prs.slides.add_slide(self.prs.slide_layouts[6])

        # 添加标题文本框
        title_shape = slide.shapes.add_textbox(Inches(0.5), Inches(0.3), Inches(9), Inches(0.5))
        title_shape.text_frame.text = "季度销售数据"
        title_shape.text_frame.paragraphs[0].font.size = Pt(24)
        title_shape.text_frame.paragraphs[0].font.bold = True

        # 添加表格
        table_shape = slide.shapes.add_table(
            len(table_rows),
            len(table_rows[0]),
            Inches(0.5),
            Inches(1.5),
            Inches(9),
            Inches(3)
        )

        # 获取表格对象
        table = table_shape.table

        # 填充数据
        for r_idx, row in enumerate(table_rows):
            for c_idx, value in enumerate(row):
                table.cell(r_idx, c_idx).text = str(value)

    def _add_chart_slide(self, chart_info):
        """添加图表页"""
        # 使用布局 6（空白）
        slide = self.prs.slides.add_slide(self.prs.slide_layouts[6])

        # 添加标题文本框
        title_shape = slide.shapes.add_textbox(Inches(0.5), Inches(0.3), Inches(9), Inches(0.5))
        title_shape.text_frame.text = "季度对比图"
        title_shape.text_frame.paragraphs[0].font.size = Pt(24)
        title_shape.text_frame.paragraphs[0].font.bold = True

        # 创建图表数据
        data = ChartData()
        data.categories = chart_info["categories"]

        # 添加数据系列
        for series_name, values in chart_info["series"]:
            data.add_series(series_name, values)

        # 添加图表
        slide.shapes.add_chart(
            XL_CHART_TYPE.COLUMN_CLUSTERED,
            Inches(0.5),
            Inches(1.5),
            Inches(9),
            Inches(4.5),
            data
        )

# 准备示例数据
sample = {
    "title": "2024 Q1 销售报告",
    "subtitle": "自动生成示例",
    "summary": [
        "收入同比 +18%",
        "新客户 +25%",
        "重点产品：A 系列"
    ],
    "table": [
        ["产品", "Q1", "Q2", "Q3", "Q4"],
        ["A", 120, 150, 180, 210],
        ["B", 80, 100, 130, 150],
        ["C", 200, 220, 240, 260]
    ],
    "chart": {
        "categories": ["Q1", "Q2", "Q3", "Q4"],
        "series": [
            ("A 系列", (120, 150, 180, 210)),
            ("B 系列", (80, 100, 130, 150))
        ]
    }
}

# 创建报告生成器实例
report = SalesReport()

# 生成报告
report.build(sample, "sales_report_demo.pptx")

运行说明：

• 运行后会生成一个完整的 4 页销售报告
• 可以修改 sample 字典中的数据来生成不同的报告

扩展建议：

• 可以从 Excel 文件或数据库读取数据
• 可以添加更多页面类型（如趋势分析页）
• 可以支持自定义模板样式
• 可以批量生成多个报告

12. 常见问题与解决方案 #

在使用 python-pptx 的过程中，可能会遇到一些问题。这里列出常见问题及解决方法。

12.1 问题 1：无法删除幻灯片 #

问题描述： python-pptx 没有提供直接删除幻灯片的 API。

解决方案：

• 推荐方法：重新创建演示文稿，只添加需要的幻灯片
• 如果必须删除，可以使用第三方库或直接操作 XML（不推荐，复杂且容易出错）

12.2 问题 2：图表功能受限 #

问题描述： python-pptx 只支持基础图表类型，不支持复杂的自定义图表。

解决方案：

• 对于复杂图表，可以使用 matplotlib 生成图片，然后插入到 PPT 中
• 或者先在 Excel 中创建图表，然后复制到 PPT

12.3 问题 3：字体显示不正确 #

问题描述： 设置了特定字体，但显示时变成了默认字体。

解决方案：

• 确保系统中已安装目标字体
• 如果字体不存在，系统会自动使用默认字体
• 建议使用系统常见字体（如微软雅黑、Arial 等）以确保兼容性

12.4 问题 4：布局编号不一致 #

问题描述： 在不同模板中，相同布局的编号可能不同。

解决方案：

• 使用布局名称而不是编号来选择布局
• 或者先打印所有布局信息，确认编号后再使用
• 建议使用空白布局（布局 6）然后手动添加元素，这样更可控

12.5 问题 5：性能问题 #

问题描述： 生成大量 PPT 时速度较慢。

解决方案：

• 将公共结构封装为函数，避免重复代码
• 复用同一个 Presentation 对象，而不是每次都创建新的
• 对于大量数据，考虑分批处理

12.6 问题 6：文件路径问题 #

问题描述： Windows 和 macOS 的路径格式不同。

解决方案：

• 使用相对路径（如 "report.pptx"）最简单
• 使用绝对路径时，Windows 用 "C:\\Users\\..."，macOS 用 "/Users/..."
• 可以使用 os.path.join() 来构建跨平台路径