Python: docx庫的add_heading() 和 add_paragraph() 都創建段落,有何差別?

by 儲蓄保險王 · 2025-09-23

add_heading() 和 add_paragraph() 確實都創建段落，但有重要區別。

🔍 深入比較兩個方法

def compare_heading_vs_paragraph():
    """比較 add_heading 和 add_paragraph 的差異"""
    from docx import Document
    from docx.enum.style import WD_STYLE_TYPE
    
    doc = Document()
    
    # 創建標題和段落
    heading = doc.add_heading('這是標題', level=1)
    paragraph = doc.add_paragraph('這是段落')
    
    print("📊 基本比較：\n")
    print(f"兩者類型相同？ {type(heading) == type(paragraph)}")
    print(f"heading 類型: {type(heading)}")
    print(f"paragraph 類型: {type(paragraph)}")
    
    print("\n📋 樣式差異：")
    print(f"heading 樣式: {heading.style.name}")
    print(f"paragraph 樣式: {paragraph.style.name}")
    
    # XML 層級檢查
    print("\n🔍 XML 層級：")
    print(f"heading XML tag: {heading._element.tag}")
    print(f"paragraph XML tag: {paragraph._element.tag}")
    
    return doc

doc = compare_heading_vs_paragraph()

def compare_heading_vs_paragraph():
    """比較 add_heading 和 add_paragraph 的差異"""
    from docx import Document
    from docx.enum.style import WD_STYLE_TYPE
    
    doc = Document()
    
    # 創建標題和段落
    heading = doc.add_heading('這是標題', level=1)
    paragraph = doc.add_paragraph('這是段落')
    
    print("📊 基本比較：\n")
    print(f"兩者類型相同？ {type(heading) == type(paragraph)}")
    print(f"heading 類型: {type(heading)}")
    print(f"paragraph 類型: {type(paragraph)}")
    
    print("\n📋 樣式差異：")
    print(f"heading 樣式: {heading.style.name}")
    print(f"paragraph 樣式: {paragraph.style.name}")
    
    # XML 層級檢查
    print("\n🔍 XML 層級：")
    print(f"heading XML tag: {heading._element.tag}")
    print(f"paragraph XML tag: {paragraph._element.tag}")
    
    return doc

doc = compare_heading_vs_paragraph()

輸出:

Python: docx庫的add_heading() 和 add_paragraph() 都創建段落,有何差別? - 儲蓄保險王

🎯 主要差異

1. 樣式自動應用

def demonstrate_style_differences():
    """展示樣式差異"""
    doc = Document()
    
    print("📝 樣式應用比較：\n")
    
    # add_heading 自動應用標題樣式
    for level in range(0, 4):
        h = doc.add_heading(f'標題層級 {level}', level=level)
        print(f"Level {level}: 樣式 = {h.style.name}")
    
    # add_paragraph 使用普通樣式
    p = doc.add_paragraph('普通段落')
    print(f"\n普通段落: 樣式 = {p.style.name}")
    
    # 手動設置段落為標題樣式
    p2 = doc.add_paragraph('手動設置的標題')
    p2.style = 'Heading 1'
    print(f"手動設置: 樣式 = {p2.style.name}")
    
    doc.save('style_comparison.docx')

demonstrate_style_differences()

def demonstrate_style_differences():
    """展示樣式差異"""
    doc = Document()
    
    print("📝 樣式應用比較：\n")
    
    # add_heading 自動應用標題樣式
    for level in range(0, 4):
        h = doc.add_heading(f'標題層級 {level}', level=level)
        print(f"Level {level}: 樣式 = {h.style.name}")
    
    # add_paragraph 使用普通樣式
    p = doc.add_paragraph('普通段落')
    print(f"\n普通段落: 樣式 = {p.style.name}")
    
    # 手動設置段落為標題樣式
    p2 = doc.add_paragraph('手動設置的標題')
    p2.style = 'Heading 1'
    print(f"手動設置: 樣式 = {p2.style.name}")
    
    doc.save('style_comparison.docx')

demonstrate_style_differences()

輸出:

style_comparison.docx:

2. 方法源碼分析

def analyze_method_implementation():
    """分析兩個方法的實現差異"""
    
    print("🔧 方法實現分析：\n")
    
    # add_heading 的簡化實現
    print("add_heading 大致實現：")
    print("""
    def add_heading(self, text='', level=1):
        # 1. 創建段落
        paragraph = self.add_paragraph(text)
        
        # 2. 根據 level 設置樣式
        if level == 0:
            paragraph.style = 'Title'
        elif 1 <= level <= 9:
            paragraph.style = f'Heading {level}'
        
        return paragraph
    """)
    
    print("\nadd_paragraph 大致實現：")
    print("""
    def add_paragraph(self, text='', style=None):
        # 1. 創建段落元素
        paragraph = self._body.add_p()
        
        # 2. 設置樣式（如果提供）
        if style:
            paragraph.style = style
        
        # 3. 添加文字
        if text:
            paragraph.add_run(text)
        
        return paragraph
    """)

analyze_method_implementation()

def analyze_method_implementation():
    """分析兩個方法的實現差異"""
    
    print("🔧 方法實現分析：\n")
    
    # add_heading 的簡化實現
    print("add_heading 大致實現：")
    print("""
    def add_heading(self, text='', level=1):
        # 1. 創建段落
        paragraph = self.add_paragraph(text)
        
        # 2. 根據 level 設置樣式
        if level == 0:
            paragraph.style = 'Title'
        elif 1 <= level <= 9:
            paragraph.style = f'Heading {level}'
        
        return paragraph
    """)
    
    print("\nadd_paragraph 大致實現：")
    print("""
    def add_paragraph(self, text='', style=None):
        # 1. 創建段落元素
        paragraph = self._body.add_p()
        
        # 2. 設置樣式（如果提供）
        if style:
            paragraph.style = style
        
        # 3. 添加文字
        if text:
            paragraph.add_run(text)
        
        return paragraph
    """)

analyze_method_implementation()

輸出:

📊 實際效果展示

def demonstrate_practical_differences():
    """展示實際使用中的差異"""
    doc = Document()
    
    # 使用 add_heading
    doc.add_heading('第一章：引言', level=1)
    doc.add_heading('1.1 背景介紹', level=2)
    doc.add_paragraph('這是正文內容...')
    
    # 等效的 add_paragraph 方式
    doc.add_paragraph('第二章：主體', style='Heading 1')
    doc.add_paragraph('2.1 詳細說明', style='Heading 2')
    doc.add_paragraph('這是正文內容...')
    
    # 檢查結果
    print("📄 文檔結構分析：\n")
    for i, para in enumerate(doc.paragraphs):
        style = para.style.name
        text = para.text[:30] + '...' if len(para.text) > 30 else para.text
        print(f"{i}: [{style}] {text}")
    
    doc.save('heading_vs_paragraph.docx')

demonstrate_practical_differences()

def demonstrate_practical_differences():
    """展示實際使用中的差異"""
    doc = Document()
    
    # 使用 add_heading
    doc.add_heading('第一章：引言', level=1)
    doc.add_heading('1.1 背景介紹', level=2)
    doc.add_paragraph('這是正文內容...')
    
    # 等效的 add_paragraph 方式
    doc.add_paragraph('第二章：主體', style='Heading 1')
    doc.add_paragraph('2.1 詳細說明', style='Heading 2')
    doc.add_paragraph('這是正文內容...')
    
    # 檢查結果
    print("📄 文檔結構分析：\n")
    for i, para in enumerate(doc.paragraphs):
        style = para.style.name
        text = para.text[:30] + '...' if len(para.text) > 30 else para.text
        print(f"{i}: [{style}] {text}")
    
    doc.save('heading_vs_paragraph.docx')

demonstrate_practical_differences()

輸出:

heading_vs_paragraph.docx

🎨 樣式屬性差異

def compare_style_properties():
    """比較標題和段落的樣式屬性"""
    doc = Document()
    
    heading1 = doc.add_heading('一級標題', level=1)
    heading2 = doc.add_heading('二級標題', level=2)
    normal = doc.add_paragraph('普通段落')
    
    print("🎨 樣式屬性比較：\n")
    
    def print_style_info(para, name):
        style = para.style
        print(f"{name}:")
        print(f"  樣式名: {style.name}")
        print(f"  字體大小: {style.font.size}")
        print(f"  粗體: {style.font.bold}")
        print(f"  段前間距: {style.paragraph_format.space_before}")
        print(f"  段後間距: {style.paragraph_format.space_after}")
        print()
    
    print_style_info(heading1, "一級標題")
    print_style_info(heading2, "二級標題")
    print_style_info(normal, "普通段落")

compare_style_properties()

def compare_style_properties():
    """比較標題和段落的樣式屬性"""
    doc = Document()
    
    heading1 = doc.add_heading('一級標題', level=1)
    heading2 = doc.add_heading('二級標題', level=2)
    normal = doc.add_paragraph('普通段落')
    
    print("🎨 樣式屬性比較：\n")
    
    def print_style_info(para, name):
        style = para.style
        print(f"{name}:")
        print(f"  樣式名: {style.name}")
        print(f"  字體大小: {style.font.size}")
        print(f"  粗體: {style.font.bold}")
        print(f"  段前間距: {style.paragraph_format.space_before}")
        print(f"  段後間距: {style.paragraph_format.space_after}")
        print()
    
    print_style_info(heading1, "一級標題")
    print_style_info(heading2, "二級標題")
    print_style_info(normal, "普通段落")

compare_style_properties()

輸出:

🔄 相互轉換

def demonstrate_conversion():
    """展示標題和段落的相互轉換"""
    doc = Document()
    
    # 創建一個標題
    heading = doc.add_heading('原本是標題', level=1)
    
    # 轉換為普通段落
    heading.style = 'Normal'
    print(f"轉換後樣式: {heading.style.name}")
    
    # 創建一個段落
    para = doc.add_paragraph('原本是段落')
    
    # 轉換為標題
    para.style = 'Heading 2'
    print(f"轉換後樣式: {para.style.name}")
    
    # 都是同樣的段落對象
    print(f"\n本質相同: {type(heading) == type(para)}")

demonstrate_conversion()

def demonstrate_conversion():
    """展示標題和段落的相互轉換"""
    doc = Document()
    
    # 創建一個標題
    heading = doc.add_heading('原本是標題', level=1)
    
    # 轉換為普通段落
    heading.style = 'Normal'
    print(f"轉換後樣式: {heading.style.name}")
    
    # 創建一個段落
    para = doc.add_paragraph('原本是段落')
    
    # 轉換為標題
    para.style = 'Heading 2'
    print(f"轉換後樣式: {para.style.name}")
    
    # 都是同樣的段落對象
    print(f"\n本質相同: {type(heading) == type(para)}")

demonstrate_conversion()

輸出:

💡 使用建議

何時使用 `add_heading()`:

# ✅ 創建文檔大綱結構
doc.add_heading('第一章', level=1)
doc.add_heading('1.1 節', level=2)

# ✅ 快速應用標題樣式
doc.add_heading('摘要', level=0)  # Title 樣式

# ✅ 創建文檔大綱結構
doc.add_heading('第一章', level=1)
doc.add_heading('1.1 節', level=2)

# ✅ 快速應用標題樣式
doc.add_heading('摘要', level=0)  # Title 樣式

何時使用 add_paragraph():

# ✅ 創建正文內容
doc.add_paragraph('這是正文...')

# ✅ 需要自定義樣式
doc.add_paragraph('特殊格式文字', style='Quote')

# ✅ 需要更多控制
para = doc.add_paragraph()
para.add_run('粗體').bold = True
para.add_run(' 普通文字')

# ✅ 創建正文內容
doc.add_paragraph('這是正文...')

# ✅ 需要自定義樣式
doc.add_paragraph('特殊格式文字', style='Quote')

# ✅ 需要更多控制
para = doc.add_paragraph()
para.add_run('粗體').bold = True
para.add_run(' 普通文字')