Python-docx制作Word教程详解

本文深入解析了使用python-docx库安全、精准地实现Word模板变量替换的核心难点与实战方案：它明确指出该库不支持开箱即用的变量填充（如Jinja2式语法），必须手动遍历run粒度进行占位符（推荐单层花括号{key}）的查找、拆分与替换，同时严格保留原有字体、加粗、字号等格式；特别强调中文显示异常的根源在于新run默认缺失中文字体，需显式设置如"SimSun"并调用底层XML接口确保生效；对于复杂场景（表格、页眉页脚、混合字体），文章也坦诚其局限性，并自然引出向更专业的docxtpl库迁移的合理建议——既授人以鱼，更授人以渔。

python-docx 能不能直接替换模板里的变量

不能。python-docx 没有内置的「变量替换」功能，它只提供底层文档对象操作能力。所谓“填充模板”，本质是遍历段落、表格、文本框中的 run 或 paragraph.text，手动查找并替换占位符（比如 {name}、{{phone}}）。如果你期待像 Jinja2 那样写 {{ user.name }} 自动渲染，得自己封装逻辑或换库。

为什么推荐用 {key} 而不是 {{key}} 作为占位符

因为 {{key}} 容易和 python-docx 内部使用的 docx2python 或某些解析器冲突，更关键的是：Word 的查找替换 API（包括 python-docx 的 paragraph.text.replace()）对花括号敏感——如果段落里有加粗、颜色、超链接等格式，直接 replace 会破坏 run 结构，导致格式错乱甚至丢失。

• 用 {name} 更安全：单层花括号在 Word 中极少原生出现，误匹配概率低
• 替换时必须按 run 粒度操作，不能只改 paragraph.text —— 否则加粗字变普通、中文后多空格、项目符号消失
• 如果模板里已有 { 或 } 字符（比如代码片段），需提前转义或改用其他分隔符如 [[name]]

如何安全地替换段落中带格式的 {xxx} 占位符

核心是「不破坏 run 链」：找到包含占位符的 run，拆分它，插入新文本 run，保留原格式。下面是最简可行逻辑：

def replace_in_paragraph(paragraph, key, value):
    full_text = paragraph.text
    if f"{{{key}}}" not in full_text:
        return
    for run in paragraph.runs:
        if f"{{{key}}}" in run.text:
            # 拆分 run：前缀 + 占位符 + 后缀
            parts = run.text.split(f"{{{key}}}")
            run.text = parts[0]  # 前缀
            new_run = paragraph.add_run(str(value))
            new_run.bold = run.bold
            new_run.italic = run.italic
            new_run.font.size = run.font.size
            if len(parts) > 1:
                paragraph.add_run(parts[1])  # 后缀
            break

• 这个函数只处理第一个匹配项；多次出现需循环调用或改用正则 + 多次 split
• 没处理表格单元格（cell.paragraphs）、页眉页脚（section.header.paragraphs）、文本框（需遍历 shape.text_frame.paragraphs）
• 值为 None 或数字时，str(value) 是必须的，否则 paragraph.add_run(None) 会报错

遇到「替换后中文显示为方框」或「字体变了」怎么办

这是最常被忽略的坑：python-docx 默认不继承模板字体，新插入的 run 会使用默认西文字体（通常是 Calibri），而中文需要显式指定中文字体（如 "SimSun" 或 "Microsoft YaHei"）。

• 替换时务必复制原 run.font.name，但注意：中英文字体常不同，run.font.name 可能返回 None 或英文名
• 稳妥做法是统一设置：new_run.font.name = "SimSun"，再补一句 new_run._element.rPr.rFonts.set(qn("w:eastAsia"), "SimSun")（需导入 from docx.oxml.shared import qn）
• 如果模板用了主题字体（Theme Fonts），新 run 不会自动继承，只能硬编码字体名

复杂点在于：一个段落可能混合宋体、微软雅黑、加粗标题，真正健壮的填充需分析每个 run 的实际生效字体，而不是简单拷贝 run.font.name。这已经超出轻量填充范畴，建议此时转向 docxtpl 库——它内建字体继承和复杂结构支持，但代价是模板语法要迁移到 {% for ... %} 风格。

到这里，我们也就讲完了《Python-docx制作Word教程详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！