用途:当使用 python-docx 的底层 OxmlElement API 创建 Word 段落、设置样式后段落却显示为 Normal,或 paragraph.style.name 返回 Normal 时,用此技能定位并修复样式名与样式 ID 不匹配的问题。
主要能力与要点:python-docx 存在两套名称——显示名 style.name(如 Heading 2、List Bullet、Body Text)和 XML 样式 ID style.style_id(如 Heading2、ListBullet、BodyText)。通过 doc.add_paragraph(style='Heading 2') 时库内部自动映射;但直接设置 w:pStyle 时须传 XML 样式 ID,传显示名不会报错,而是静默回退到 Normal。所有显示名含空格的样式都会受影响。
使用方式:建立显示名到样式 ID 的映射字典与辅助函数,设置时改为 pStyle.set(qn('w:val'), get_style_id('Heading 2'));兜底策略为把显示名中的空格去除。文档中自定义样式的 ID 可能任意,需用 style.style_id 实际查询确认。验证时遍历 doc.paragraphs 打印 style.name 与文本,若标题显示为 Normal 说明 ID 有误。
相关限制与提醒:仅影响底层 OxmlElement API,使用 doc.add_paragraph(style=...) 正常;需要插入到指定位置(如参考元素之前)时才必须用 OxmlElement。去除章节间段落时,w:pPr 中的 w:sectPr 会被一并删除,导致分节符静默丢失(影响罗马/阿拉伯页码),需检查 doc.sections 数量并按需重新添加 sectPr。空格去除的启发式对约 95% 内置样式有效,但无法处理大小写差异(如 table of figures 对应 TableofFigures)。本技能未提供收费或平台相关信息,暂未提供。