如何用Python-docx处理Word文档中的表格与段落

在自动化办公场景中，我们经常需要批量生成或修改Word文档。Python凭借其丰富的生态库，成为处理这类任务的首选语言。其中，python-docx 是操作 .docx 文件最主流的开源库。它不仅能读取文档内容，还能精确控制段落、表格、样式等元素。对于开发者而言，掌握其核心机制，尤其是对段落与表格的解析与构建逻辑，是实现高质量自动写文脚本的基础。

理解Document对象的结构层级

要高效使用 python-docx，必须先理解其对象模型。一个 .docx 文档本质上是一个由多个结构化组件组成的树形结构。顶层是 Document 对象，它包含一个段落（Paragraph）列表和一个表格（Table）列表。每个 Paragraph 又由一个或多个运行（Run）组成，而 Run 是文本格式的最小单位。这意味着，同一段落中不同字体、颜色或加粗状态的文本，会被划分为不同的 Run。

这种设计虽然增加了复杂性，但也带来了极高的灵活性。例如，你可以在一个段落中，让前半部分为宋体，后半部分为微软雅黑，这在生成报告或合同类文档时非常实用。理解这一点，能避免在读取或生成文档时，因忽略格式断点而导致内容错乱。

从零开始构建一个可复用的文档解析器

自动写文章的第一步往往是“读取模板”或“分析现有文档”。我们可以通过封装一个通用的解析函数，来提取文档中的所有文本与表格数据。以下是一个经过优化的实现，避免了原始代码中潜在的死循环和索引错误：

import docx
from typing import List, Dict, Tuple

def extract_text_and_tables(doc_path: str) -> Tuple[List[str], Dict[str, Dict]]:
    """
    提取Word文档中的段落文本和表格内容
    :param doc_path: .docx文件路径
    :return: 段落列表和表格字典
    """
    doc = docx.Document(doc_path)
    
     提取所有段落文本
    paragraphs = [para.text for para in doc.paragraphs if para.text.strip()]
    
     提取所有表格数据
    tables_data = {}
    for table_idx, table in enumerate(doc.tables):
        table_content = []
        for row_idx, row in enumerate(table.rows):
            row_data = [cell.text.strip() for cell in row.cells]
            table_content.append(row_data)
        tables_data[f"table_{table_idx}"] = {
            "rows": len(table.rows),
            "columns": len(table.columns),
            "data": table_content
        }
    
    return paragraphs, tables_data

这个函数返回两个结构化数据：一个是纯净的段落文本列表，另一个是包含表格元信息和单元格内容的字典。你可以将这些数据作为“知识库”，用于后续的文本生成或模板填充。

基于模板的智能内容填充策略

真正的“自动写文章”并非无中生有，而是基于规则和数据的智能重组。假设你有一个报告模板，其中包含“{公司名称}”、“{营收增长率}”等占位符。我们可以编写一个填充函数：

def fill_template(doc_path: str, output_path: str, data: Dict[str, str]):
    """
    填充模板文档中的占位符
    :param doc_path: 模板路径
    :param output_path: 输出路径
    :param data: 替换数据字典
    """
    doc = docx.Document(doc_path)
    
     遍历所有段落
    for para in doc.paragraphs:
        for key, value in data.items():
            if key in para.text:
                para.text = para.text.replace(key, value)
    
     遍历所有表格
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for key, value in data.items():
                    if key in cell.text:
                        cell.text = cell.text.replace(key, value)
    
    doc.save(output_path)

这种方法的优势在于，它完全保留了原始文档的格式和布局，只需替换关键字段，即可生成一份专业外观的报告。这对于需要频繁生成财务摘要、项目进度更新的团队来说，能极大提升效率。

表格数据的动态生成与样式控制

除了填充，我们还可以动态创建表格。例如，从CSV或数据库中读取数据，并将其渲染为带样式的Word表格。以下代码展示了如何创建一个带标题行和边框的表格：

def add_styled_table(doc, data: List[List[str]]):
    """
    向文档添加带样式的表格
    :param doc: Document对象
    :param data: 二维数据列表
    """
    table = doc.add_table(rows=0, cols=len(data[0]), style='Table Grid')
    
    for i, row_data in enumerate(data):
        row_cells = table.add_row().cells
        for j, text in enumerate(row_data):
            row_cells[j].text = text
        
         设置第一行为标题样式
        if i == 0:
            for cell in row_cells:
                for paragraph in cell.paragraphs:
                    for run in paragraph.runs:
                        run.bold = True

通过 style='Table Grid' 参数，我们直接应用了Word内置的“网格表”样式，省去了手动设置边框的繁琐步骤。你也可以自定义样式，但需确保模板文档中已定义该样式名称。

常见问题