python-docx新建docx使用List Bullet样式报错的自动化解决方案问询

使用python-docx搭建Excel读取-业务逻辑处理-Word生成全自动化流程时，在新建的空白文档中尝试调用List Bullet样式添加带项目符号的段落，执行代码：

import docx
Bullet1 = "This text is for Bullet 1."
doc.add_paragraph(Bullet1, style='List Bullet')

触发报错：

KeyError: "no style with name 'List Bullet'"

排查发现python-docx从零创建的空白文档默认仅加载4种基础样式，未加载可用的列表类样式。按照Word样式调用规则，样式需要至少在文档内被使用过一次才可被程序识别，但手动创建文档、插入项目符号再清空内容的模板预处理方案，完全不符合全流程自动化的需求。

不需要手动预处理模板，以下两种方案均可实现全代码流程下的项目符号添加，无人工介入步骤：

方案1：自动激活内置List Bullet样式（支持样式复用） #

通过操作文档底层XML，直接将内置的List Bullet样式定义写入文档样式表，激活后即可像调用普通内置样式一样正常使用，兼容所有Word版本：

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

def activate_bullet_style(doc):
    # 样式已存在时直接跳过，避免重复写入
    try:
        doc.styles['List Bullet']
        return
    except KeyError:
        pass
    # 构造内置List Bullet样式的标准XML结构
    style_elem = OxmlElement('w:style')
    style_elem.set(qn('w:type'), 'paragraph')
    style_elem.set(qn('w:styleId'), 'ListBullet')
    # 配置样式基础属性
    name_elem = OxmlElement('w:name')
    name_elem.set(qn('w:val'), 'List Bullet')
    style_elem.append(name_elem)

    base_elem = OxmlElement('w:basedOn')
    base_elem.set(qn('w:val'), 'Normal')
    style_elem.append(base_elem)

    next_elem = OxmlElement('w:next')
    next_elem.set(qn('w:val'), 'Normal')
    style_elem.append(next_elem)
    # 绑定一级圆点项目符号格式
    p_pr = OxmlElement('w:pPr')
    num_pr = OxmlElement('w:numPr')
    ilvl = OxmlElement('w:ilvl')
    ilvl.set(qn('w:val'), '0')
    num_id = OxmlElement('w:numId')
    num_id.set(qn('w:val'), '1')
    num_pr.append(ilvl)
    num_pr.append(num_id)
    p_pr.append(num_pr)
    style_elem.append(p_pr)
    # 将样式写入文档样式表
    doc.styles.element.append(style_elem)

# 调用示例
doc = Document()
activate_bullet_style(doc)
Bullet1 = "This text is for Bullet 1."
doc.add_paragraph(Bullet1, style='List Bullet')
doc.save("output.docx")

方案2：直接给段落绑定项目符号格式（轻量无样式依赖） #

如果不需要复用列表样式，可以直接给目标段落添加项目符号属性，不需要提前激活任何样式，代码更简洁：

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

def add_bullet_paragraph(doc, text):
    para = doc.add_paragraph(text)
    p_pr = para._p.get_or_add_pPr()
    num_pr = OxmlElement('w:numPr')
    # 配置为一级圆点项目符号
    ilvl = OxmlElement('w:ilvl')
    ilvl.set(qn('w:val'), '0')
    num_id = OxmlElement('w:numId')
    num_id.set(qn('w:val'), '1')
    num_pr.append(ilvl)
    num_pr.append(num_id)
    p_pr.append(num_pr)
    return para

# 调用示例
doc = Document()
add_bullet_paragraph(doc, "This text is for Bullet 1.")
add_bullet_paragraph(doc, "This text is for Bullet 2.")
doc.save("output.docx")

• 两种方案均从文档创建环节开始全代码实现，不需要任何手动操作模板的步骤，可直接嵌入自动化流程
• 如果需要使用多级列表、方形/对勾等特殊项目符号，只需要调整w:ilvl的层级值、w:numId绑定的编号规则即可
• 不建议依赖不同语言、不同版本Word自带的默认样式集合，通过XML显式写入格式的方式兼容性最好，不会出现因环境差异导致的样式丢失问题

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