Python docxtpl 模板规范生成Word文档渲染实战(规避路径与兼容坑)

pip install docxtpl python-docx
# 若安装后仍报错，建议指定兼容版本（规避版本冲突）
pip install docxtpl==0.16.4 python-docx==0.8.11

import os
from docxtpl import DocxTemplate
# 1. 先校验模板文件存在性，避免路径问题
template_file_path = "你的模板路径.docx"  # 替换为实际模板路径（相对/绝对路径均可）
result_file_path = "输出路径.docx"        # 替换为目标文档输出路径
# 校验模板路径，不存在则直接抛出异常，明确提示问题
if not os.path.exists(template_file_path):
    raise FileNotFoundError("模板文件不存在，请检查路径是否正确！")
# 2. 加载模板+渲染+保存，简洁写法，规避隐性兼容问题
try:
    # 加载Word模板，创建模板对象
    tpl = DocxTemplate(template_file_path)
    # 渲染前可校验result_dict，确保无缺失key（可选，RPA交接时更规范）
    # 核心逻辑：获取模板中所有未声明的占位符，判断是否与result_dict的key完全匹配
    # placeholder_keys = tpl.get_undeclared_template_variables()  # 获模板所有占位符
    # if not all(key in result_dict for key in placeholder_keys):
    #     raise KeyError("result_dict 缺失模板所需的占位符，请检查数据字典！")
    # 传入数据字典渲染模板（result_dict需提前定义，key与模板占位符一致）
    tpl.render(result_dict)
    # 保存渲染后的目标文档
    tpl.save(result_file_path)
    print(f"文档保存成功：{result_file_path}")
except AttributeError as e:
    # 捕获模板格式/版本兼容问题（最常见隐性错误）
    print(f"模板格式/版本问题：{e}，建议重建模板（保存为.docx格式）或更新依赖包")
except Exception as e:
    # 捕获其他所有异常（如权限不足、路径非法等），避免程序崩溃
    print(f"其他报错：{e}")

if not os.path.exists(template_file_path):
    raise FileNotFoundError("模板文件不存在，请检查路径是否正确！")

tpl = DocxTemplate(template_file_path)
tpl.render(result_dict)
tpl.save(result_file_path)

placeholder_keys = tpl.get_undeclared_template_variables()
if not all(key in result_dict for key in placeholder_keys):
    raise KeyError("result_dict 缺失模板所需的占位符，请检查数据字典！")

def render_docx_template(template_path, result_path, data_dict):
    """
    批量渲染Word模板函数
    :param template_path: 模板文件路径（.docx）
    :param result_path: 目标文档输出路径
    :param data_dict: 渲染数据字典（key与模板占位符一致）
    :return: True（成功）/False（失败）
    """
    if not os.path.exists(template_path):
        print(f"模板文件不存在：{template_path}")
        return False
    try:
        tpl = DocxTemplate(template_path)
        placeholder_keys = tpl.get_undeclared_template_variables()
        if not all(key in data_dict for key in placeholder_keys):
            print("数据字典缺失占位符")
            return False
        tpl.render(data_dict)
        tpl.save(result_path)
        print(f"生成成功：{result_path}")
        return True
    except AttributeError as e:
        print(f"模板兼容问题：{e}")