解决python-docx报错ValueError: WD_COLOR_INDEX无'none'映射问题

使用python-docx处理Word文档时，执行代码bg_color = run.font.highlight_color触发以下报错：

ValueError: WD_COLOR_INDEX has no XML mapping for 'none'

报错回溯信息：

Traceback (most recent call last):
  File "XXX.py", line 377, in <module>
    main()
  ...
    bg_color = run.font.highlight_color
  File "/home/xxx/.local/lib/python3.8/site-packages/docx/text/font.py", line 139, in highlight_color
    return rPr.highlight_val
  File "/home/xxx/.local/lib/python3.8/site-packages/docx/oxml/text/font.py", line 183, in highlight_val
    return highlight.val
  File "/home/xxx/.local/lib/python3.8/site-packages/docx/oxml/xmlchemy.py", line 254, in get_attr_value
    return self._simple_type.from_xml(attr_str_value)
  File "/home/xxx/.local/lib/python3.8/site-packages/docx/enum/base.py", line 64, in from_xml
    raise ValueError(f"{cls.__name__} has no XML mapping for '{xml_value}'")
ValueError: WD_COLOR_INDEX has no XML mapping for 'none'

问题根源是部分Word编辑器会生成w:highlight w:val="none"的节点，但python-docx的WD_COLOR_INDEX枚举未对'none'值做映射，导致解析失败。以下是三种可行的解决方法：

方案1：捕获异常（不修改源码，推荐） #

在获取高亮色的代码处添加异常捕获，遇到报错时直接返回None，模拟无高亮的逻辑：

from docx import Document

doc = Document("your_doc.docx")
for paragraph in doc.paragraphs:
    for run in paragraph.runs:
        try:
            bg_color = run.font.highlight_color
        except ValueError:
            # 处理'none'值的情况，设为None
            bg_color = None
        # 后续业务逻辑
        print(f"高亮色：{bg_color}")

方案2：修改python-docx源码（临时修复） #

找到python-docx安装目录下的docx/enum/base.py文件，修改from_xml方法，添加对'none'值的特殊处理：
原代码：

@classmethod
def from_xml(cls, xml_value):
    """
    Return member of this enum corresponding to *xml_value*, or raise
    ValueError if no such member exists.
    """
    try:
        return cls._xml_to_member_map_[xml_value]
    except KeyError:
        raise ValueError(f"{cls.__name__} has no XML mapping for '{xml_value}'")

修改后：

@classmethod
def from_xml(cls, xml_value):
    """
    Return member of this enum corresponding to *xml_value*, or raise
    ValueError if no such member exists.
    """
    if xml_value == 'none':
        return None
    try:
        return cls._xml_to_member_map_[xml_value]
    except KeyError:
        raise ValueError(f"{cls.__name__} has no XML mapping for '{xml_value}'")

或者更精准地修改WD_COLOR_INDEX枚举：找到docx/enum/text.py中的WD_COLOR_INDEX类，添加NONE成员：

class WD_COLOR_INDEX(XmlEnumeration):
    """
    Specifies a color index value used in a WordprocessingML document.
    """
    __ms_name__ = "WdColorIndex"
    __url__ = "https://learn.microsoft.com/en-us/office/vba/api/word.wdcolorindex"
    __members__ = (
        # ... 保留原有成员 ...
        Member("NONE", 0, "none", "No color"),
    )

方案3：预处理Word文档XML #

通过python-docx的底层XML操作，移除文档中w:highlight w:val="none"的节点：

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

doc = Document("your_doc.docx")
for paragraph in doc.paragraphs:
    for run in paragraph.runs:
        rPr = run._element.get_or_add_rPr()
        highlight = rPr.find(qn('w:highlight'))
        if highlight is not None and highlight.get(qn('w:val')) == 'none':
            rPr.remove(highlight)

doc.save("fixed_doc.docx")

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