使用python-docx在段落后插入标题却变为段落，该如何修正？

问题出在你先通过document.add_heading()把标题添加到了文档末尾，再移动XML节点的方式会导致文档内部的段落管理结构混乱，最终标题样式无法正确生效。

直接在目标位置创建标题段落即可解决，具体方案如下：

推荐方法：直接构造标题节点插入 #

from docx.oxml.shared import OxmlElement
from docx.oxml.ns import qn

def insert_heading_after(text, level, target_paragraph):
    doc = target_paragraph.document
    # 对应级别的标题样式ID，比如Heading 2
    style_id = f"Heading {level}"
    
    # 创建新的段落XML节点
    p_node = OxmlElement('w:p')
    
    # 设置段落样式为对应标题级别
    p_pr = OxmlElement('w:pPr')
    p_style = OxmlElement('w:pStyle')
    p_style.set(qn('w:val'), style_id)
    p_pr.append(p_style)
    p_node.append(p_pr)
    
    # 添加标题文本内容
    r_node = OxmlElement('w:r')
    t_node = OxmlElement('w:t')
    t_node.text = text
    r_node.append(t_node)
    p_node.append(r_node)
    
    # 将新标题段落插入到目标段落之后
    target_paragraph._p.addnext(p_node)
    
    # 将新段落加入文档的段落管理列表，方便后续操作
    new_para = doc._body._add_paragraph(p_node)
    return new_para

调用示例：

paraIndex = 20
insert_heading_after(f"Title {i+1} :", 2, document.paragraphs[paraIndex])

备选方法：调整原移动逻辑（不推荐） #

如果坚持使用移动节点的方式，需要同步更新文档的段落管理列表，否则会出现结构不一致的问题：

def insert_element_after_paragraph(element, paragraph):
    p = paragraph._p
    p.addnext(element)
    # 手动将新段落加入文档的段落列表
    doc = paragraph.document
    new_para = doc._body._add_paragraph(element)
    return new_para

# 调用逻辑
paraIndex = 20
# 创建标题（此时会被添加到文档末尾）
personPara = document.add_heading(f"Title {i+1} :", 2)
# 移动节点并更新文档段落列表
insert_element_after_paragraph(personPara._p, document.paragraphs[paraIndex])
# 删除原末尾的无效段落对象
document._body._paragraphs.remove(personPara)

这种方式容易引发后续文档操作的异常，因此更推荐第一种直接在目标位置创建标题的方案。

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