在使用?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_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)。主題色會隨演示文稿主題變化而變化。

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