使用python-docx生成的Word文档超链接失效，提示不可读内容

问题描述 #

我使用python-docx库生成Word文档，设置了可跳转至网页的文本链接。该文档在Apple Pages中打开时，超链接可正常点击跳转；但在Microsoft Word中打开时，链接仅显示为普通文本，无法跳转，且打开时提示“Word发现文档中存在不可读内容”。

相关代码 #

生成超链接的函数：

def add_hyperlink_to_paragraph(paragraph, url, text):
    part = paragraph.part
    r_id = part.relate_to(url, qn('r:hyperlink'), is_external=True)
    hyperlink = OxmlElement('w:hyperlink')
    hyperlink.set(qn('r:id'), r_id)
    
    new_run = OxmlElement('w:r')
    rPr = OxmlElement('w:rPr')
    
    rStyle = OxmlElement('w:rStyle')
    rStyle.set(qn('w:val'), 'Hyperlink')
    rPr.append(rStyle)
    new_run.append(rPr)
    
    text_element = OxmlElement('w:t')
    text_element.text = text
    new_run.append(text_element)
    hyperlink.append(new_run)
    paragraph._element.append(hyperlink)
    return hyperlink

调用示例：

add_hyperlink_to_paragraph(link_paragraph, f"https://www...com/{id}", id)

问题原因 #

• 命名空间缺失：创建w:hyperlink元素时，未显式指定w命名空间的完整声明。Microsoft Word对OOXML格式的语法校验远严于Apple Pages，缺失命名空间会导致Word无法识别超链接节点，将其当作普通文本处理。
• 未预定义Hyperlink样式：代码中直接引用了Hyperlink样式，但默认情况下python-docx生成的空白文档并不包含该内置样式。Word无法解析不存在的样式引用，从而触发“不可读内容”提示。
• XML节点结构不规范：Word要求超链接内的文本运行节点（w:r）需包含符合标准的格式属性，仅添加rStyle不足以满足Word的解析要求，缺少下划线、字体颜色等默认超链接格式属性，也会导致解析异常。

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