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

在使用 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
  from pptx.util import Inches
  
  # 创建一个新的演示文稿
  prs = Presentation()
  
  # 添加一张空白幻灯片
  slide_layout = prs.slide_layouts[5]  # 5 是空白幻灯片的索引
  slide = prs.slides.add_slide(slide_layout)
  
  paragraph_strs = [
      'Egg, bacon, sausage and spam.',
      'Spam, bacon, sausage and spam.',
      'Spam, egg, spam, spam, bacon and spam.'
  ]
  
  left = Inches(2)
  top = width = height = Inches(3)  # You can adjust these values
  text_box = slide.shapes.add_textbox(left, top, width, height)
  text_frame = text_box.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  # 设置新段落的文本
  
  if __name__ == "__main__":
      prs.save('presentation_text.potx')

  

添加文本

• 只有文本片段 (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_SIZE

text_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_ALIGN

paragraph_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_str
    p.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 Pt

text_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)。主题色会随演示文稿主题变化而变化。

掌握这些核心概念和方法，你就能在 Python 中高效、精准地操控 PowerPoint 文档中的文本内容和格式了。