当前位置：首页 > news >正文

PPT自动化 python-pptx - 8: 文本（text）

news 2025/8/4 4:22:20

在使用 python-pptx 库操作 PowerPoint 文档时，理解文本的结构和处理方式至关重要。本文将深入探讨文本在形状中的组织层级、访问方式以及各级别的格式化选项。

文本容器与层级结构

可容纳文本的形状： 只有自动形状 (Auto shapes) 和表格单元格 (table cells) 可以包含文本。其他类型的形状（如图片、线条）则不能。
统一的处理方式： 无论文本位于哪种容器中，其操作方法都是相同的。
文本的三级层级：
1. Shape.text_frame (形状.文本框架): 这是形状内所有文本的顶级容器。
2. TextFrame.paragraphs (文本框架.段落): 文本框架包含一个或多个段落（Paragraph）。
3. _Paragraph.runs (段落.文本片段): 每个段落包含一个或多个文本片段（Run）。字符级别的格式化应用于此层级。

1. 文本框架 (Text Frame)

所有属于形状的文本都包含在其文本框架中。
一个文本框架具有以下属性：
* 垂直对齐 (vertical_anchor)
* 边距 (margin_top, margin_bottom, margin_left, margin_right)
* 自动换行 (word_wrap)
* 自动调整大小行为 (auto_size)
* 旋转角度
* 某些 3D 视觉效果
* 多列文本格式设置能力
关键特性： 文本框架总是包含至少一个段落，即使该段落是空的。

2. 段落 (Paragraph)

段落具有以下属性：
* 行间距
* 段前间距 (space_before)
* 段后间距 (space_after)
* 项目符号格式设置
* 制表位 (Tabs)
* 大纲/缩进级别 (level)
* 水平对齐 (alignment)
关键特性： 段落可以是空的。但如果段落包含任何文本，这些文本必须包含在一个或多个文本片段 (Run) 中。

3. 文本片段 (Run)

文本片段存在的目的是提供字符级别的格式化：
* 字体 (font.name)
* 字号 (font.size)
* 字体颜色 (font.color)
* 超链接目标 URL (hyperlink.address)
* 粗体 (font.bold), 斜体 (font.italic), 下划线 (font.underline)
* 删除线 (font.strikethrough)
* 字距调整 (Kerning)
* 大写样式（如：全部大写）
字符格式通过访问 Run 的 .font 属性进行设置。

访问和操作段落

文本框架总是至少包含一个段落。

为形状添加多个段落的过程相对繁琐（因为初始就有一个段落）。例如，创建一个包含三个段落的形状：

from pptx import Presentation# 创建一个新的演示文稿
prs = Presentation()# 添加一张空白幻灯片
slide_layout = prs.slide_layouts[5]  # 5 是空白幻灯片的索引
slide = prs.slides.add_slide(slide_layout)# 访问幻灯片中的形状集合
shapes = slide.shapesparagraph_strs = ['Egg, bacon, sausage and spam.','Spam, bacon, sausage and spam.','Spam, egg, spam, spam, bacon and spam.'
]text_frame = shapes.text_frame
text_frame.clear()  # 清除现有段落，只留下一个空段落# 处理第一个段落 (索引 0)
p = text_frame.paragraphs[0]
p.text = paragraph_strs[0]  # 设置第一个段落的文本# 添加并设置后续段落
for para_str in paragraph_strs[1:]:p = text_frame.add_paragraph()  # 添加新段落p.text = para_str  # 设置新段落的文本

添加文本

只有文本片段 (Run) 才能真正包含文本。
直接给形状 (.text)、文本框架 (.text) 或段落 (.text) 的 .text 属性赋值，是一种快捷方式，它会在内部创建一个 Run 并设置其文本。
以下两种方式效果相同：

方式 1 (快捷方式):

shape.text = 'foobar'  # 直接设置形状的文本

方式 2 (显式操作):

text_frame = shape.text_frame
text_frame.clear()  # 清理现有内容
p = text_frame.paragraphs[0]  # 获取第一个段落
run = p.add_run()  # 在该段落中添加一个文本片段 (Run)
run.text = 'foobar'  # 设置 Run 的文本

应用格式化

1. 文本框架级别格式化

设置文本框架的属性影响整个框架内的文本布局：

from pptx.util import Inches
from pptx.enum.text import MSO_ANCHOR, MSO_AUTO_SIZEtext_frame = shape.text_frame
text_frame.text = 'Spam, eggs, and spam'  # 快捷设置文本 (会创建 Run)
text_frame.margin_bottom = Inches(0.08)   # 下边距 0.08 英寸
text_frame.margin_left = 0                # 左边距 0 英寸
text_frame.vertical_anchor = MSO_ANCHOR.TOP  # 垂直对齐：顶部
text_frame.word_wrap = False              # 关闭自动换行
text_frame.auto_size = MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT  # 自动调整形状大小以适应文本# 注意:
# - MSO_AUTO_SIZE 枚举定义了 auto_size 的可能值
# - MSO_ANCHOR 枚举定义了 vertical_anchor 的可能值
# - 水平对齐 (如左对齐、居中) 在段落级别 (Paragraph.alignment) 设置

2. 段落级别格式化

设置段落的属性影响整个段落的外观：

from pptx.enum.text import PP_ALIGNparagraph_strs = ['Egg, bacon, sausage and spam.','Spam, bacon, sausage and spam.','Spam, egg, spam, spam, bacon and spam.'
]text_frame = shape.text_frame
text_frame.clear()  # 清空文本框架# 设置第一个段落
p = text_frame.paragraphs[0]
p.text = paragraph_strs[0]
p.alignment = PP_ALIGN.LEFT  # 段落水平左对齐# 添加并设置后续段落 (缩进一级，类似子项目符号)
for para_str in paragraph_strs[1:]:p = text_frame.add_paragraph()  # 添加新段落p.text = para_strp.alignment = PP_ALIGN.LEFT    # 段落水平左对齐p.level = 1                    # 设置大纲/缩进级别为 1 (缩进)

3. 字符级别格式化 (文本片段 - Run)

字符格式通过 Run 的 .font 属性设置：

from pptx.dml.color import RGBColor
from pptx.enum.dml import MSO_THEME_COLOR
from pptx.util import Pttext_frame = shape.text_frame
text_frame.clear()  # 清空文本框架 (对新创建的形状非必须)p = text_frame.paragraphs[0]  # 获取第一个段落
run = p.add_run()             # 在该段落中添加一个文本片段 (Run)
run.text = 'Spam, eggs, and spam'  # 设置 Run 的文本# 设置 Run 的字体属性
font = run.font
font.name = 'Calibri'               # 字体：Calibri
font.size = Pt(18)                  # 字号：18磅
font.bold = True                    # 粗体：是
font.italic = None                  # 斜体：None 表示继承主题设置
font.color.theme_color = MSO_THEME_COLOR.ACCENT_1  # 字体颜色：主题色 - 强调颜色 1# 或者，使用绝对 RGB 值设置字体颜色 (注意：切换主题时此颜色不会改变)
font.color.rgb = RGBColor(0xFF, 0x7F, 0x50)  # RGB(255, 127, 80) - 珊瑚色# 将 Run 设置为超链接
run.hyperlink.address = 'https://github.com/scanny/python-pptx'  # 超链接目标地址

关键点总结：

层级清晰： 文本框架 > 段落 > 文本片段。格式化选项随层级不同而不同。
访问需谨慎： 使用 shape.has_text_frame 检查形状是否支持文本。
段落管理： 文本框架初始包含一个段落，添加新段落需用 add_paragraph()。
文本归属： 文本内容最终存储在 Run 对象中。.text 属性是创建 Run 的快捷方式。
格式化分离：
- 框架级：整体布局（对齐、边距、换行、自动调整）。
- 段落级：行距、间距、项目符号、缩进、水平对齐。
- 字符级：字体、字号、颜色、样式（粗/斜/下划线）、超链接。
枚举类型： 对齐 (PP_ALIGN), 垂直锚点 (MSO_ANCHOR), 自动调整 (MSO_AUTO_SIZE), 主题颜色 (MSO_THEME_COLOR) 等属性使用库提供的枚举值进行设置。
单位工具： ppt.util 提供了 Inches 和 Pt (磅) 等工具函数方便尺寸设置。
颜色设置： 可使用主题色 (theme_color) 或绝对 RGB 值 (rgb)。主题色会随演示文稿主题变化而变化。