python-docx Skill

概述

本Skill提供使用python-docx生成專業Word文件的標準方法和最佳實踐。

適用場景

• 生成安全服務方案文件
• 生成技術架構設計文件
• 生成任何需要專業排版的Word文件

技術棧

• 核心庫: python-docx
• 輔助庫: docx.shared, docx.enum, docx.oxml.ns

標準程式碼模板

1. 文件初始化

from docx import Document
from docx.shared import Inches, Pt, RGBColor, Cm
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.table import WD_TABLE_ALIGNMENT
from docx.oxml.ns import qn

def create_document():
    """建立標準文件"""
    doc = Document()

    # 設定預設字型（關鍵！）
    style = doc.styles['Normal']
    style.font.name = 'Microsoft YaHei'
    style._element.rPr.rFonts.set(qn('w:eastAsia'), 'Microsoft YaHei')

    return doc

2. 字型設定（必須！）

def set_font(run, font_name='Microsoft YaHei'):
    """設定字型"""
    run.font.name = font_name
    run._element.rPr.rFonts.set(qn('w:eastAsia'), font_name)

3. 標題新增

def add_heading_custom(doc, text, level=1):
    """
    新增標準標題

    Args:
        doc: Document物件
        text: 標題文本
        level: 1=一級, 2=二級, 3=三級

    Returns:
        標題段落物件
    """
    heading = doc.add_heading(level=level)
    run = heading.add_run(text)
    set_font(run)

    if level == 1:
        run.font.size = Pt(16)
        run.font.color.rgb = RGBColor(0, 51, 102)
        run.font.bold = True
    elif level == 2:
        run.font.size = Pt(14)
        run.font.color.rgb = RGBColor(0, 51, 102)
        run.font.bold = True
    else:
        run.font.size = Pt(12)
        run.font.color.rgb = RGBColor(0, 0, 0)
        run.font.bold = True

    return heading

4. 段落新增

def add_para_custom(doc, text, bold=False, indent=0, color=None):
    """
    新增標準段落

    Args:
        doc: Document物件
        text: 段落文本
        bold: 是否加粗
        indent: 首行縮排（釐米）
        color: RGBColor顏色物件

    Returns:
        段落物件
    """
    p = doc.add_paragraph()
    p.paragraph_format.first_line_indent = Cm(indent)

    run = p.add_run(text)
    run.font.size = Pt(11)
    set_font(run)

    if bold:
        run.font.bold = True
    if color:
        run.font.color.rgb = color

    return p

5. 專案符號列表

def add_bullet_custom(doc, text, level=0):
    """
    新增專案符號段落

    Args:
        doc: Document物件
        text: 列表項文本
        level: 縮排級別（0=一級, 1=二級）

    Returns:
        段落物件
    """
    p = doc.add_paragraph(style='List Bullet')
    p.paragraph_format.left_indent = Cm(0.5 + level * 0.5)

    run = p.add_run(text)
    run.font.size = Pt(11)
    set_font(run)

    return p
發現更多技能外掛，請訪問7w4.net。

6. 編號列表

def add_numbered_custom(doc, text, level=0):
    """
    新增編號列表段落

    Args:
        doc: Document物件
        text: 列表項文本
        level: 縮排級別

    Returns:
        段落物件
    """
    p = doc.add_paragraph(style='List Number')
    p.paragraph_format.left_indent = Cm(0.5 + level * 0.5)

    run = p.add_run(text)
    run.font.size = Pt(11)
    set_font(run)

    return p

7. 表格建立

def create_table(doc, headers, data):
    """
    建立標準表格

    Args:
        doc: Document物件
        headers: 表頭列表
        data: 二維列表，每行是一個列表

    Returns:
        表格物件
    """
    table = doc.add_table(rows=1+len(data), cols=len(headers))
    table.style = 'Light Grid Accent 1'
    table.alignment = WD_TABLE_ALIGNMENT.CENTER

    # 表頭
    for i, header in enumerate(headers):
        cell = table.rows[0].cells[i]
        cell.text = header
        for paragraph in cell.paragraphs:
            for run in paragraph.runs:
                run.font.bold = True
                run.font.size = Pt(10)
                set_font(run)

    # 資料
    for row_idx, row_data in enumerate(data, 1):
        for col_idx, cell_data in enumerate(row_data):
            cell = table.rows[row_idx].cells[col_idx]
            cell.text = str(cell_data)
            for paragraph in cell.paragraphs:
                for run in paragraph.runs:
                    run.font.size = Pt(9)
                    set_font(run)

    return table

8. 圖片插入

def insert_image(doc, image_path, width=Inches(6), caption=None):
    """
    插入標準圖片

    Args:
        doc: Document物件
        image_path: 圖片路徑
        width: 圖片寬度
        caption: 圖片標題（可選）

    Returns:
        段落物件
    """
    # 插入圖片
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = p.add_run()
    run.add_picture(image_path, width=width)

    # 新增標題
    if caption:
        p = doc.add_paragraph()
        p.alignment = WD_ALIGN_PARAGRAPH.CENTER
        run = p.add_run(caption)
        run.font.size = Pt(10)
        run.font.color.rgb = RGBColor(102, 102, 102)
        set_font(run)

    return p

9. 分頁

def add_page_break(doc):
    """新增分頁符"""
    doc.add_page_break()

10. 封面建立

def create_cover(doc, title, subtitle=None, customer=None, date=None, version=None):
    """
    建立標準封面

    Args:
        doc: Document物件
        title: 主標題
        subtitle: 副標題（可選）
        customer: 客戶名稱（可選）
        date: 日期（可選）
        version: 版本號（可選）
    """
    # 空行佔位
    for _ in range(6):
        doc.add_paragraph()

    # 主標題
    p = doc.add_paragraph()
    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = p.add_run(title)
    run.font.size = Pt(28)
    run.font.bold = True
    run.font.color.rgb = RGBColor(0, 51, 102)
    set_font(run)

    # 副標題
    if subtitle:
        p = doc.add_paragraph()
        p.alignment = WD_ALIGN_PARAGRAPH.CENTER
        run = p.add_run(subtitle)
        run.font.size = Pt(16)
        run.font.color.rgb = RGBColor(102, 102, 102)
        set_font(run)

    # 空行
    for _ in range(4):
        doc.add_paragraph()

    # 資訊
    info = doc.add_paragraph()
    info.alignment = WD_ALIGN_PARAGRAPH.CENTER

    if customer:
        run = info.add_run(f'客戶：{customer}\n')
        run.font.size = Pt(14)
        set_font(run)

    if date:
        run = info.add_run(f'日期：{date}\n')
        run.font.size = Pt(14)
        set_font(run)

    if version:
        run = info.add_run(f'版本：{version}')
        run.font.size = Pt(14)
        set_font(run)

完整示例

# 建立文件
doc = create_document()

# 新增封面
create_cover(doc, 
    title='安全服務方案',
    subtitle='Security Service Proposal',
    customer='某某公司',
    date='2026-03-23',
    version='V1.0'
)

# 分頁
doc.add_page_break()

# 新增一級標題
add_heading_custom(doc, '一、 服務概述', level=1)

# 新增二級標題
add_heading_custom(doc, '1.1 服務背景', level=2)

# 新增正文
add_para_custom(doc, '這是正文內容，首行縮排兩字元。', indent=0.5)

# 新增專案符號
add_bullet_custom(doc, '專案符號內容')

# 新增編號列表
add_numbered_custom(doc, '編號列表內容')

# 新增表格
headers = ['列1', '列2', '列3']
data = [['A', 'B', 'C'], ['D', 'E', 'F']]
create_table(doc, headers, data)

# 儲存
doc.save('output.docx')

常見問題

Q: 中文顯示為方框？
A: 確保每個run都呼叫set_font()設定字型

Q: 表格樣式不統一？
A: 設定table.style = 'Light Grid Accent 1'

Q: 圖片無法顯示？
A: 檢查圖片路徑是否正確，使用絕對路徑

Q: 文件格式錯亂？
A: 確保所有文本都設定了字型和大小

參考

• python-docx官方文件: https://python-docx.readthedocs.io/

這個技能質量中等偏上，程式碼寫得清晰規範，容易看懂和使用，基本覆蓋了Word文件常用的文字、表格、圖片等元素。對於需要生成格式化文件的新手來說比較友好。不足之處是功能比較基礎，缺少目錄、頁首頁尾等實用功能，而且常見問題解答比較少，遇到特殊需求可能找不到答案。適合作為入門參考，但複雜場景可能不太夠用。