能否用python-docx创建转PDF后仍有效的书签超链接？

需求与问题背景 #

• 需生成Word格式报告并转为PDF，要求首页汇总数据可跳转至文档后续详情，计划用python-docx库添加书签与超链接
• 尝试两种方案均遇问题：
  • 方案1：生成的超链接转PDF后可点击，但为外部链接；修改part.relate_to()的is_external为False时触发ValueError
  • 方案2：可创建书签与超链接，但转PDF后无法跳转；加入方案1的get_or_create_hyperlink_style(d)函数后XML结构更接近，但仍无效，对比发现无效链接缺少<w:p w14:paraId="2318C920" w14:textId="19560908" w:rsidR="001E33CA" w:rsidRDefault="001E33CA">相关段落属性内容

解决建议 #

1. 修正内部超链接的关系注册逻辑 #

方案1报错是因为内部链接不能直接修改is_external，需要关联书签的内部引用而非外部URL：

• 先给目标位置添加书签，确保书签名称唯一
• 注册关系时，将target设为#书签名称的格式，同时使用正确的内部链接关系类型
• 示例代码片段：

  def add_internal_hyperlink(paragraph, text, bookmark_name):
      part = paragraph.part
      # 注册内部超链接关系
      r_id = part.relate_to(
          f"#{bookmark_name}",
          docx.opc.constants.RELATIONSHIP_TYPE.HYPERLINK,
          is_external=False
      )
      # 添加带超链接样式的文本
      hyperlink_run = paragraph.add_run(text)
      hyperlink_run.style = get_or_create_hyperlink_style(part.document)
      # 绑定超链接关系ID
      hyperlink_run._r.get_or_add_hyperlink().set("r:id", r_id)
  

2. 确保书签与超链接的XML结构合规 #

缺少的<w:p>节点是段落的必要属性，转PDF时依赖这些标识：

• 给书签和超链接所在段落补充rsid（修订ID）、paraId等属性，可通过python-docx的底层XML操作添加
• 检查书签结构：必须由<w:bookmarkStart>和<w:bookmarkEnd>包裹目标内容，且这两个节点要放在同一个段落内

3. 调用本地Word程序转PDF #

第三方PDF转换工具可能丢失内部链接，用win32com.client调用Word原生转换能更好保留跳转功能：

import win32com.client as win32

word = win32.Dispatch("Word.Application")
doc = word.Documents.Open("your_report.docx")
# 17是Word中PDF格式的对应编号
doc.SaveAs("your_report.pdf", FileFormat=17)
doc.Close()
word.Quit()

内容的提问来源于stack exchange，提问作者Ian.m.r.g