如何使用docxtpl为文本添加标题层级？

首先你尝试的rt.add('Headername', level=1)写法无法实现需求，RichText的add方法没有提供level参数，不能直接通过该参数设置标题层级。

正确实现标题层级的三种常用方式 #

1. 模板预定义样式（最简单常用）

直接在你的docx模板文件中插入占位符，给占位符手动设置Word内置的「标题1」「标题2」等标题样式，渲染时直接传值即可：

from docxtpl import DocxTemplate

tpl = DocxTemplate("模板文件路径.docx")
context = {
    "first_level_heading": "这是一级标题",
    "second_level_heading": "这是二级标题"
}
tpl.render(context)
tpl.save("输出文件路径.docx")

2. 动态指定层级用Subdoc实现

如果需要在代码中动态控制标题层级，可通过Subdoc调用python-docx的原生add_heading方法实现：

from docxtpl import DocxTemplate, Subdoc

tpl = DocxTemplate("模板文件路径.docx")
# 创建子文档对象
heading_subdoc = Subdoc(tpl)
# add_heading第二个参数为标题层级，支持1-9级
heading_subdoc.add_heading("动态生成的一级标题", level=1)
heading_subdoc.add_heading("动态生成的二级标题", level=2)

context = {
    "dynamic_headings": heading_subdoc
}
tpl.render(context)
tpl.save("输出文件路径.docx")

通过该方式生成的标题会自动纳入Word的目录索引，后续插入目录可直接识别。

3. 配合RichText使用指定样式

如果确实需要用RichText实现，可给RichText指定模板中已有的标题样式：

from docxtpl import DocxTemplate, RichText

tpl = DocxTemplate("模板文件路径.docx")
# style参数值要和模板里的标题样式名完全匹配，中文Office默认是「标题 1」，英文Office是「Heading 1」
rt = RichText("RichText实现的一级标题", style="标题 1")
context = {
    "rt_heading": rt
}
tpl.render(context)
tpl.save("输出文件路径.docx")

注意事项 #

• 所有涉及样式名的参数，取值必须和Word模板里的样式名称完全一致，大小写、空格都不能有差异，否则样式不会生效。
• 如需自定义标题格式，可提前在模板中修改对应标题样式的字体、段落格式，渲染后会自动继承。

内容的提问来源于stack exchange，提问作者Johs