如何使用python-docx在.docx文件中设置自定义标题编号？

当使用paragraph.insert_paragraph_before(style='Heading 2', text='heading2')时，Word默认的Heading样式会自动应用内置编号规则。要实现自定义标题编号，需要通过python-docx的底层API操作编号定义（NumberingPart），并将自定义编号规则关联到目标标题样式。以下是具体实现步骤和代码示例：

核心步骤 #

• 访问文档的编号部件（NumberingPart），这是存储所有编号规则的核心载体
• 创建新的编号定义，设置各级标题的编号格式（包括编号样式、起始值、前缀、后缀、缩进等）
• 将自定义编号规则绑定到对应的Heading样式（比如Heading 2）
• 使用绑定了自定义编号的样式插入标题

代码示例 #

以下代码实现为Heading 2设置自定义编号格式（例如："1.1、" "1.2、" 这种带中文顿号的编号）：

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

def add_custom_numbering(doc, style_name):
    # 获取文档的编号部件
    numbering_part = doc.part.numbering_part
    numbering_definitions = numbering_part.numbering_definitions

    # 创建新的编号定义
    num = OxmlElement('w:num')
    num.set(qn('w:numId'), str(numbering_definitions._next_num_id))
    numbering_definitions.append(num)

    # 配置Heading 2对应的编号级别（级别1）
    lvl = OxmlElement('w:lvl')
    lvl.set(qn('w:ilvl'), '1')
    lvl.set(qn('w:start'), '1')  # 编号起始值
    lvl.set(qn('w:numFmt'), 'decimal')  # 十进制数字格式

    # 设置编号显示格式（父级编号.当前级编号+顿号）
    lvl_text = OxmlElement('w:lvlText')
    lvl_text.set(qn('w:val'), '%1.%2、')
    lvl.append(lvl_text)

    # 设置编号对齐方式
    lvl_jc = OxmlElement('w:lvlJc')
    lvl_jc.set(qn('w:val'), 'left')
    lvl.append(lvl_jc)

    # 设置编号与文本的缩进间距
    ppr = OxmlElement('w:pPr')
    ind = OxmlElement('w:ind')
    ind.set(qn('w:left'), '720')  # 左缩进720缇（1缇=1/20磅）
    ind.set(qn('w:hanging'), '360')  # 悬挂缩进360缇
    ppr.append(ind)
    lvl.append(ppr)

    num.append(lvl)

    # 将自定义编号绑定到目标样式
    style = doc.styles[style_name]
    style._element.get_or_add_pPr().get_or_add_numPr().get_or_add_numId().val = num.get(qn('w:numId'))

# 示例调用
doc = Document()

# 为Heading 2绑定自定义编号规则
add_custom_numbering(doc, 'Heading 2')

# 插入标题测试
doc.add_paragraph('主标题', style='Heading 1')
doc.paragraphs[0].insert_paragraph_before(style='Heading 2', text='自定义编号子标题1')
doc.paragraphs[1].insert_paragraph_before(style='Heading 2', text='自定义编号子标题2')

doc.save('自定义标题编号示例.docx')

关键参数说明 #

• w:numFmt：编号格式，可选值包括decimal（十进制）、upperRoman（大写罗马数字）、lowerLetter（小写字母）等
• w:lvlText：编号显示模板，%1代表父级编号，%2代表当前级编号，可自由组合前缀后缀（比如"第%1章第%2节"）
• w:start：编号起始值，默认从1开始
• 缩进参数：left控制整体左缩进，hanging控制编号与文本的间距，单位为缇（1磅=20缇）

内容的提问来源于stack exchange，提问作者王齐龙