Back to Details

python-docx-style-id-mismatch

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

python-docx Style ID Mismatch (OxmlElement)

python-docx 样式ID不匹配问题（OxmlElement场景）

What This Skill Helps With

本技能适用场景

Use this skill when your low-level 
python-docx
XML edits look correct in code but Word still renders the paragraph as 
Normal
instead of the heading or list style you expected.
当你使用
python-docx
的底层XML编辑代码看起来正确，但Word仍将段落渲染为
Normal
样式，而非你预期的标题或列表样式时，可使用本技能。

Ask for this skill with prompts like

可通过以下提示词调用本技能

  • Use $python-docx-style-id-mismatch to fix why my Heading 2 paragraphs render as Normal.
  • Use $python-docx-style-id-mismatch to explain the difference between style names and style IDs in python-docx.
  • Use $python-docx-style-id-mismatch to review this OxmlElement paragraph insertion code.
  • 使用$python-docx-style-id-mismatch修复我的Heading 2段落显示为Normal样式的问题。
  • 使用$python-docx-style-id-mismatch解释python-docx中样式名称与样式ID的区别。
  • 使用$python-docx-style-id-mismatch检查我的OxmlElement段落插入代码。

Problem

问题描述

When creating Word document paragraphs using python-docx's low-level 
OxmlElement
API, setting 
w:pStyle
with the style's display name (e.g., "Heading 2") causes the paragraph to silently fall back to "Normal" style. No error is raised. The XML requires the style ID (e.g., "Heading2") which differs from the display name.
当使用python-docx的底层
OxmlElement
API创建Word文档段落时，若使用样式的显示名称（例如"Heading 2"）设置
w:pStyle
，会导致段落自动 fallback 到"Normal"样式，且不会抛出任何错误。XML中要求使用的是样式ID（例如"Heading2"），它与显示名称存在差异。

Context / Trigger Conditions

触发场景

  • Creating paragraphs via 
    OxmlElement('w:p')
    instead of 
    doc.add_paragraph()
  • Setting style with 
    pStyle.set(qn('w:val'), 'Heading 2')
    (WITH space)
  • Paragraphs render as Normal/body text instead of the intended style
  • paragraph.style.name
    shows "Normal" even though you set a heading style
  • No error or warning is raised -- complete silent failure
  • Affects all styles with spaces in their display names
  • 通过
    OxmlElement('w:p')
    创建段落，而非
    doc.add_paragraph()
  • 使用
    pStyle.set(qn('w:val'), 'Heading 2')
    （带空格）设置样式
  • 段落显示为Normal/正文文本，而非预期样式
  • 即使你设置了标题样式，
    paragraph.style.name
    仍显示为"Normal"
  • 无任何错误或警告提示——完全静默失败
  • 所有显示名称带空格的样式都会受影响

Root Cause

根本原因

python-docx has two name systems:
  • Display name (
    style.name
    ): Human-readable, e.g., "Heading 2", "List Bullet", "Body Text"
  • XML style ID (
    style.style_id
    ): Used in the XML, e.g., "Heading2", "ListBullet", "BodyText"
When you use 
doc.add_paragraph(style='Heading 2')
, python-docx handles the mapping internally. But when using 
OxmlElement
directly to set 
w:pStyle
, you must provide the XML style ID.
python-docx有两套名称体系：
  • 显示名称（
    style.name
    ）：易于人类阅读，例如"Heading 2"、"List Bullet"、"Body Text"
  • XML样式ID（
    style.style_id
    ）：XML中使用的标识，例如"Heading2"、"ListBullet"、"BodyText"
当你使用
doc.add_paragraph(style='Heading 2')
时，python-docx会在内部自动处理名称映射。但当直接使用
OxmlElement
设置
w:pStyle
时，你必须提供XML样式ID。

Solution

修复方案

Create a mapping dictionary and helper function:
python
STYLE_ID_MAP = {
    'Normal': 'Normal',
    'Heading 1': 'Heading1',
    'Heading 2': 'Heading2',
    'Heading 3': 'Heading3',
    'Heading 4': 'Heading4',
    'List Bullet': 'ListBullet',
    'List Number': 'ListNumber',
    'Caption': 'Caption',
    'table of figures': 'TableofFigures',
    'Body Text': 'BodyText',
    'First Paragraph': 'FirstParagraph',
    'Compact': 'Compact',
}

def get_style_id(style_name):
    """Convert a style display name to its XML style ID."""
    return STYLE_ID_MAP.get(style_name, style_name.replace(' ', ''))
Then use it when setting styles via OxmlElement:
python
undefined
创建一个映射字典和辅助函数：
python
STYLE_ID_MAP = {
    'Normal': 'Normal',
    'Heading 1': 'Heading1',
    'Heading 2': 'Heading2',
    'Heading 3': 'Heading3',
    'Heading 4': 'Heading4',
    'List Bullet': 'ListBullet',
    'List Number': 'ListNumber',
    'Caption': 'Caption',
    'table of figures': 'TableofFigures',
    'Body Text': 'BodyText',
    'First Paragraph': 'FirstParagraph',
    'Compact': 'Compact',
}

def get_style_id(style_name):
    """Convert a style display name to its XML style ID."""
    return STYLE_ID_MAP.get(style_name, style_name.replace(' ', ''))
然后在通过OxmlElement设置样式时使用该函数：
python
undefined

WRONG - silent failure, falls back to Normal

错误写法 - 静默失败， fallback 到Normal样式

pStyle.set(qn('w:val'), 'Heading 2')
pStyle.set(qn('w:val'), 'Heading 2')

CORRECT - uses XML style ID

正确写法 - 使用XML样式ID

pStyle.set(qn('w:val'), get_style_id('Heading 2')) # -> 'Heading2'

The fallback `style_name.replace(' ', '')` handles most cases since Word
typically just removes spaces, but some styles have non-obvious IDs (e.g.,
"table of figures" -> "TableofFigures" with different casing).
pStyle.set(qn('w:val'), get_style_id('Heading 2')) # -> 'Heading2'

默认的`style_name.replace(' ', '')`逻辑可处理大多数场景，因为Word通常只是移除空格，但部分样式的ID不明显（例如"table of figures" -> "TableofFigures"，大小写也不同）。

Verification

验证方法

After applying the fix, verify styles are correctly assigned:
python
for i, p in enumerate(doc.paragraphs):
    if p.style.name.startswith('Heading'):
        print(f"[{i}] style.name='{p.style.name}' text='{p.text[:60]}'")
If headings appear as "Normal" in this output, the style ID is wrong.
To inspect what XML style ID a document actually uses:
python
for style in doc.styles:
    if style.name.startswith('Heading'):
        print(f"Display: '{style.name}' -> ID: '{style.style_id}'")
应用修复后，验证样式是否正确分配：
python
for i, p in enumerate(doc.paragraphs):
    if p.style.name.startswith('Heading'):
        print(f"[{i}] style.name='{p.style.name}' text='{p.text[:60]}'")
如果输出中标题显示为"Normal"，说明样式ID设置错误。
要查看文档实际使用的XML样式ID：
python
for style in doc.styles:
    if style.name.startswith('Heading'):
        print(f"Display: '{style.name}' -> ID: '{style.style_id}'")

Related Issue: Section Breaks Lost During Paragraph Removal

相关问题：段落删除时分节符丢失

When removing paragraphs between chapter boundaries using lxml's 
body.remove(element)
, any 
w:sectPr
elements embedded in paragraph properties (
w:pPr
) are removed along with the paragraphs. This silently destroys section breaks (used for Roman/Arabic page numbering).
Fix: After content replacement operations, verify section count and re-add section breaks if needed:
python
undefined
当使用lxml的
body.remove(element)
删除章节边界之间的段落时，段落属性（
w:pPr
）中嵌入的任何
w:sectPr
元素会随段落一起被删除。这会导致分节符（用于罗马数字/阿拉伯数字页码切换）被静默删除。
修复方法：在内容替换操作后，检查分节符数量，必要时重新添加分节符：
python
undefined

Check sections

检查分节符数量

print(f"Sections: {len(doc.sections)}")
print(f"Sections: {len(doc.sections)}")

Re-add section break before a target paragraph

在目标段落前重新添加分节符

prev_para = doc.paragraphs[target_idx - 1] prev_pPr = prev_para._element.get_or_add_pPr() sectPr = OxmlElement('w:sectPr')
prev_para = doc.paragraphs[target_idx - 1] prev_pPr = prev_para._element.get_or_add_pPr() sectPr = OxmlElement('w:sectPr')

... configure sectPr properties ...

... 配置sectPr属性 ...

prev_pPr.append(sectPr)
undefined
prev_pPr.append(sectPr)
undefined

Example

示例

Full pattern for creating a heading paragraph via OxmlElement:
python
from docx.oxml import OxmlElement
from docx.oxml.ns import qn

def create_heading(doc, ref_element, text, level=2):
    p = OxmlElement('w:p')
    pPr = OxmlElement('w:pPr')
    pStyle = OxmlElement('w:pStyle')
    # Key line: use get_style_id, not raw display name
    pStyle.set(qn('w:val'), get_style_id(f'Heading {level}'))
    pPr.append(pStyle)
    p.append(pPr)

    r = OxmlElement('w:r')
    t = OxmlElement('w:t')
    t.set(qn('xml:space'), 'preserve')
    t.text = text
    r.append(t)
    p.append(r)

    ref_element.addprevious(p)
    return p
通过OxmlElement创建标题段落的完整代码：
python
from docx.oxml import OxmlElement
from docx.oxml.ns import qn

def create_heading(doc, ref_element, text, level=2):
    p = OxmlElement('w:p')
    pPr = OxmlElement('w:pPr')
    pStyle = OxmlElement('w:pStyle')
    # 关键代码：使用get_style_id，而非原始显示名称
    pStyle.set(qn('w:val'), get_style_id(f'Heading {level}'))
    pPr.append(pStyle)
    p.append(pPr)

    r = OxmlElement('w:r')
    t = OxmlElement('w:t')
    t.set(qn('xml:space'), 'preserve')
    t.text = text
    r.append(t)
    p.append(r)

    ref_element.addprevious(p)
    return p

Notes

注意事项

  • This only affects the low-level OxmlElement API. Using 
    doc.add_paragraph(style='Heading 2')
    works correctly because python-docx resolves the name internally.
  • The OxmlElement approach is necessary when inserting paragraphs at specific positions (before a reference element) rather than appending to the end.
  • Custom styles defined in a document may have arbitrary IDs. Always check 
    style.style_id
    for the actual XML ID if unsure.
  • The 
    style_name.replace(' ', '')
    heuristic works for ~95% of built-in Word styles but won't catch casing differences.
  • 此问题仅影响底层OxmlElement API。使用
    doc.add_paragraph(style='Heading 2')
    可正常工作，因为python-docx会在内部解析名称。
  • 当需要在特定位置（参考元素之前）插入段落，而非追加到文档末尾时，必须使用OxmlElement方法。
  • 文档中定义的自定义样式可能有任意ID。若不确定，务必检查
    style.style_id
    获取实际的XML ID。
  • style_name.replace(' ', '')
    的启发式方法对约95%的Word内置样式有效，但无法处理大小写差异的情况。