docx-manipulation

DOCX 操作技能

概述

此技能可讓您使用 python-docx 程式庫，以程式方式建立、編輯和操作 Microsoft Word (.docx) 文件。無需手動編輯，即可建立具備適當格式、樣式、表格和圖片的專業文件。

使用方式

1. 描述您想建立或修改的 Word 文件內容
2. 提供任何來源內容（文字、資料、圖片）
3. 我將產生 python-docx 程式碼並執行

範例提示：

• "建立一份包含標題、章節標題和表格的專業報告"
• "在此文件中加入頁首和頁尾"
• "產生一份含預留位置的合約文件"
• "將此 Markdown 內容轉換為有樣式的 Word 文件"

領域知識

python-docx 基礎

from docx import Document
from docx.shared import Inches, Pt, Cm
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.style import WD_STYLE_TYPE

# 建立新文件
doc = Document()

# 或開啟現有文件
doc = Document('existing.docx')

文件結構

Document
├── sections（邊界、方向、大小）
├── paragraphs（含格式的文字）
├── tables（列、儲存格、合併儲存格）
├── pictures（內嵌圖片）
└── styles（預定義格式）

新增內容

段落與標題

# 新增標題（層級 0-9）
doc.add_heading('主標題', level=0)
doc.add_heading('章節標題', level=1)

# 新增段落
para = doc.add_paragraph('一般文字')

# 新增有樣式的段落
doc.add_paragraph('注意：重要！', style='Intense Quote')

# 新增內嵌格式
para = doc.add_paragraph()
para.add_run('粗體文字').bold = True
para.add_run(' 和 ')
para.add_run('斜體文字').italic = True

表格

# 建立表格
table = doc.add_table(rows=3, cols=3)
table.style = 'Table Grid'

# 新增內容
table.cell(0, 0).text = '標題 1'
table.rows[0].cells[1].text = '標題 2'

# 動態新增列
row = table.add_row()
row.cells[0].text = '新資料'

# 合併儲存格
a = table.cell(0, 0)
b = table.cell(0, 2)
a.merge(b)

圖片

# 新增圖片並設定大小
doc.add_picture('image.png', width=Inches(4))

# 新增到特定段落
para = doc.add_paragraph()
run = para.add_run()
run.add_picture('logo.png', width=Inches(1.5))

格式設定

段落格式

from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.shared import Pt, Inches

para = doc.add_paragraph('格式化文字')
para.alignment = WD_ALIGN_PARAGRAPH.CENTER
para.paragraph_format.line_spacing = 1.5
para.paragraph_format.space_after = Pt(12)
para.paragraph_format.first_line_indent = Inches(0.5)

字元格式

run = para.add_run('樣式文字')
run.bold = True
run.italic = True
run.underline = True
run.font.name = 'Arial'
run.font.size = Pt(14)
run.font.color.rgb = RGBColor(0x00, 0x00, 0xFF)  # 藍色

頁面設定

from docx.enum.section import WD_ORIENT
from docx.shared import Inches

section = doc.sections[0]
section.page_width = Inches(11)
section.page_height = Inches(8.5)
section.orientation = WD_ORIENT.LANDSCAPE
section.left_margin = Inches(1)
section.right_margin = Inches(1)

頁首與頁尾

section = doc.sections[0]

# 頁首
header = section.header
header.paragraphs[0].text = "公司名稱"
header.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER

# 頁尾含頁碼
footer = section.footer
para = footer.paragraphs[0]
para.text = "第 "
# 新增頁碼欄位
run = para.add_run()
fldChar1 = OxmlElement('w:fldChar')
fldChar1.set(qn('w:fldCharType'), 'begin')
run._r.append(fldChar1)
# ...（頁碼欄位程式碼）

樣式

# 使用內建樣式
doc.add_paragraph('標題', style='Heading 1')
doc.add_paragraph('引言', style='Quote')
doc.add_paragraph('清單項目', style='List Bullet')

# 常用樣式：
# - 'Normal', 'Heading 1-9', 'Title', 'Subtitle'
# - 'Quote', 'Intense Quote', 'List Bullet', 'List Number'
# - 'Table Grid', 'Light Shading', 'Medium Grid 1'

最佳實務

1. 先規劃結構：在編寫程式碼前先規劃文件層次
2. 使用樣式：透過樣式保持格式一致，而非手動設定
3. 經常儲存：大型文件請定期呼叫 doc.save()
4. 處理錯誤：開啟前檢查檔案是否存在
5. 清理工作：填入資料後移除範本中的預留位置

常見模式

報告範本

def create_report(title, sections):
    doc = Document()
    doc.add_heading(title, 0)
    doc.add_paragraph(f'產生日期：{datetime.now()}')
    
    for section_title, content in sections.items():
        doc.add_heading(section_title, 1)
        doc.add_paragraph(content)
    
    return doc

從資料建立表格

def add_data_table(doc, headers, rows):
    table = doc.add_table(rows=1, cols=len(headers))
    table.style = 'Table Grid'
    
    # 標題列
    for i, header in enumerate(headers):
        table.rows[0].cells[i].text = header
        table.rows[0].cells[i].paragraphs[0].runs[0].bold = True
    
    # 資料列
    for row_data in rows:
        row = table.add_row()
        for i, value in enumerate(row_data):
            row.cells[i].text = str(value)
    
    return table

合併列印模式

def fill_template(template_path, replacements):
    doc = Document(template_path)
    
    for para in doc.paragraphs:
        for key, value in replacements.items():
            if f'{{{key}}}' in para.text:
                para.text = para.text.replace(f'{{{key}}}', value)
    
    return doc

範例

範例 1：建立商業書信

from docx import Document
from docx.shared import Inches, Pt
from docx.enum.text import WD_ALIGN_PARAGRAPH
from datetime import datetime

doc = Document()

# 信頭
doc.add_paragraph('ACME Corporation')
doc.add_paragraph('123 Business Ave, Suite 100')
doc.add_paragraph('New York, NY 10001')
doc.add_paragraph()

# 日期
doc.add_paragraph(datetime.now().strftime('%Y 年 %m 月 %d 日'))
doc.add_paragraph()

# 收件人
doc.add_paragraph('Mr. John Smith')
doc.add_paragraph('XYZ Company')
doc.add_paragraph('456 Industry Blvd')
doc.add_paragraph('Chicago, IL 60601')
doc.add_paragraph()

# 稱呼
doc.add_paragraph('親愛的 Smith 先生：')
doc.add_paragraph()

# 內文
body = """我們很高興通知您，您的提案已獲接受...

[信件內文繼續...]

感謝您持續的合作。"""

for para_text in body.split('\n\n'):
    doc.add_paragraph(para_text)

doc.add_paragraph()
doc.add_paragraph('誠摯地，')
doc.add_paragraph()
doc.add_paragraph()
doc.add_paragraph('Jane Doe')
doc.add_paragraph('執行長，ACME Corporation')

doc.save('business_letter.docx')

範例 2：建立含表格的報告

from docx import Document
from docx.shared import Inches

doc = Document()
doc.add_heading('第四季銷售報告', 0)

# 執行摘要
doc.add_heading('執行摘要', 1)
doc.add_paragraph('2024 年第四季在所有區域均展現強勁成長...')

# 銷售表格
doc.add_heading('區域表現', 1)

table = doc.add_table(rows=1, cols=4)
table.style = 'Medium Grid 1 Accent 1'

headers = ['區域', '第三季銷售', '第四季銷售', '成長率']
for i, header in enumerate(headers):
    table.rows[0].cells[i].text = header

data = [
    ['北美', '$1.2M', '$1.5M', '+25%'],
    ['歐洲', '$800K', '$950K', '+18%'],
    ['亞太', '$600K', '$750K', '+25%'],
]

for row_data in data:
    row = table.add_row()
    for i, value in enumerate(row_data):
        row.cells[i].text = value

doc.save('sales_report.docx')

限制

• 無法執行巨集或 VBA 程式碼
• 複雜的範本可能會遺失部分格式
• 對進階功能（SmartArt、圖表）支援有限
• 無直接 PDF 轉換功能（需使用其他工具）
• 追蹤修訂的讀取功能有限

安裝

pip install python-docx

資源

• python-docx 文件
• GitHub 儲存庫
• Office Open XML 規格