Python: 如何使用docx套件,在word文件中插入一個帶有超連結的文字? from docx.oxml.shared import OxmlElement, qn

code:

# -*- coding: utf-8 -*-
"""
Created on Tue Oct 21 19:24:17 2024

@author: SavingKing
"""

from docx import Document  # 導入Document類用於創建Word文檔
from docx.oxml.shared import OxmlElement, qn  # 導入OxmlElement用於創建XML元素，qn用於格式化XML標簽
from docx.opc.constants import RELATIONSHIP_TYPE as RT  # 導入關系類型常量
from docx.shared import RGBColor  # 導入RGBColor用於設置顏色
from docx.enum.text import WD_UNDERLINE  # 導入WD_UNDERLINE用於設置下劃線樣式

document = Document()  # 創建一個新的Word文檔對象
document_part = document.part  # 獲取文檔的主要部分
# <docx.parts.document.DocumentPart at 0x21c5f513d10>

url = "http://google.com"  # 超鏈接目標URL
rId = document_part.relate_to(target=url, reltype=RT.HYPERLINK, is_external=True)  
# 關聯外部超鏈接並獲取關系ID
# 'rId9' #str
# RT.HYPERLINK
# 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink'

# 創建超鏈接元素
hyperlink = OxmlElement('w:hyperlink')  # 創建一個超鏈接XML元素
hyperlink.set(key=qn('r:id'), value=rId)  # 設置超鏈接的關系ID
# <CT_Hyperlink '<w:hyperlink>' at 0x21c5d47b4d0>
# qn('r:id') #qualified name
# '{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id'

#創建一個運行 (w:r) 並附加到超鏈接
run = OxmlElement('w:r')  # 創建一個文本運行XML元素
# <CT_R '<w:r>' at 0x21c57341950>
hyperlink.append(run)  # 將運行附加到超鏈接元素中

# 設置運行的樣式
run_properties = OxmlElement('w:rPr')  # 創建運行屬性元素

color = OxmlElement('w:color')  # 創建顏色元素
color.set(key=qn('w:val'), value='0000FF')  # 設置顏色為藍色
# qn('w:val')
# '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}val'

u = OxmlElement('w:u')  # 創建下劃線元素
u.set(key=qn('w:val'), value='single')  # 設置下劃線為 單下劃線

#run_properties先append顏色跟下劃線
run_properties.append(color)  # 將顏色元素添加到運行屬性中
run_properties.append(u)  # 將下劃線元素添加到運行屬性中

#run元素再append run_properties
run.append(run_properties)  # 將運行屬性添加到運行中

# 創建文本元素 (w:t) 並附加到運行
text = OxmlElement('w:t')  # 創建文本元素
text.text = "點擊這裡"  #  設置文本內容
run.append(text)  # 將文本元素附加到運行中

# 創建段落並將超鏈接添加到段落
paragraph = document.add_paragraph()  # 創建一個新段落
paragraph._p.append(hyperlink)  #  將超鏈接添加到段落中
#paragraph._p
# <CT_P '<w:p>' at 0x21c57343f20>

# 保存文檔
document.save('path_to_save_document.docx')  # 保存文檔到指定路徑

生成的word文件:

階層關係:

Document
└── DocumentPart
    └── Hyperlink (w:hyperlink)
        ├── r:id (關聯到外部URL的關系標識符)
        └── Run (w:r)
            ├── RunProperties (w:rPr)
            │   ├── Color (w:color)
            │   │   └── val (颜色值)
            │   └── Underline (w:u)
            │       └── val (下劃線類型)
            └── Text (w:t)
                └── "點擊這裡" (文本内容)
    └── Paragraph
        └── Hyperlink (引用上面構建的超鏈接)

Document:
頂層對象，代表整個Word文檔。
DocumentPart:
文檔的主要組件，用於管理文檔的內容和結構。
Hyperlink:
XML元素 w:hyperlink，用於創建一個超鏈接。
屬性 r:id 與外部URL關聯。
Run (w:r):
用於包含文本和文本的樣式設置。
包含運行屬性和實際文本內容。
RunProperties (w:rPr):
包含所有文本的樣式屬性，如顏色和下劃線。
Color (w:color) 和 Underline (w:u):
具體的樣式設置，例如文本顏色和下劃線類型。
Text (w:t):
包含實際要顯示的文本，如“點擊這里”。
Paragraph:
文檔中的一個段落，可以包含文本、圖片、超鏈接等。
這里用於包含一個超鏈接元素。
通過這種方式，每個元素通過XML結構層次被精確定義和組織，使得最終的文檔可以呈現出設計的內容和格式。

Document
│
├── Section
│
├── Paragraph
│   ├── Run
│   │   └── Font
│   │       ├── size
│   │       ├── bold
│   │       ├── italic
│   │       ├── underline
│   │       ├── color
│   │       └── other text attributes...
│   └── InlineShape
│
└── Table
    ├── Row
    │   └── Cell
    │       ├── Paragraph (可以包含更多的 Run、Text)
    │       └── Table (嵌套表格)
    └── Column (对所有行的一个视图，不是一个容器)

Document
Word 文檔的頂層容器。
Section
文檔的不同部分，每個部分可以有自己的頁眉、頁腳和頁面設置。
Paragraph
文檔中的一個段落，是文本的主要組織單元。
Run
段落中具有相同格式的文本序列。
Font
size: 字體大小。
bold: 是否加粗。
italic: 是否斜體。
underline: 是否有下劃線。
color: 字體顏色。
other text attributes: 其他文本屬性，如字體類型、字符間距等。
InlineShape
段落中的內聯圖形，如圖片或圖表。
Table
文檔中的表格，由行和列組成。
Row
表格的一行。
Cell
行中的一個單元格。
Paragraph: 單元格內的段落。
Table: 嵌套表格。
Column
對所有行中相同位置的單元格的一個視圖，主要用於批量處理，不是一個實際的容器。

document_part.relate_to?

hyperlink.set?

qn() #qualified name

qn('r:id')
Out[105]: '{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id'


qn('w:val')
Out[107]: '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}val'

在OpenXML標準中，qn 函數用於生成限定名稱（qualified name），這些名稱通常用於XML中以確保名稱空間的唯一性和準確性。下面是對 r:id 和 w:val 的解釋：

r:id:
r 是一個前綴，代表 “relationships”（關系）。
在OpenXML中，關系（relationships）用於鏈接各種文檔組件，如鏈接到外部資源（如超鏈接）、文檔內圖像等。
{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id 是該屬性的全限定名稱，包括命名空間URL，用以區分不同類型的 id。
w:val:
w 是一個前綴，代表 “wordprocessingML”（Word處理標記語言,ML:Markup Language），這是Word文檔的XML實現。
w:val 通常用於指定某個屬性的值，如樣式屬性（顏色、對齊、字體等）。
{http://schemas.openxmlformats.org/wordprocessingml/2006/main}val 是該屬性的全限定名稱，指明了具體屬於Word處理ML的屬性值。
這些前綴和命名空間的使用是為了避免在XML文檔中的名稱沖突，並確保XML元素能夠被準確識別和處理。每個元素和屬性通過這種方式明確地指向其定義的標準，使得處理這些元素的軟件（如文檔閱讀器或編輯器）能夠正確解析和呈現文檔內容。

改寫為function:


from docx import Document  # 導入Document類用於創建Word文檔
from docx.oxml.shared import OxmlElement, qn  # 導入OxmlElement用於創建XML元素，qn用於格式化XML標簽
from docx.opc.constants import RELATIONSHIP_TYPE as RT  # 導入關系類型常量
from docx.shared import RGBColor  # 導入RGBColor用於設置顏色
from docx.enum.text import WD_UNDERLINE  # 導入WD_UNDERLINE用於設置下劃線樣式


def add_hyperlink(doc, url, link_text, color='0000FF', underline=True):
    document_part = doc.part
    rId = document_part.relate_to(target=url, reltype=RT.HYPERLINK, is_external=True)

    # 创建超链接元素
    hyperlink = OxmlElement('w:hyperlink')
    hyperlink.set(qn('r:id'), rId)

    # 创建运行（w:r）并附加到超链接
    run = OxmlElement('w:r')
    hyperlink.append(run)

    # 设置运行的样式
    run_properties = OxmlElement('w:rPr')

    # 设置颜色
    color_elem = OxmlElement('w:color')
    color_elem.set(qn('w:val'), color)
    run_properties.append(color_elem)

    # 设置下划线
    if underline:
        u = OxmlElement('w:u')
        u.set(qn('w:val'), 'single')
        run_properties.append(u)

    run.append(run_properties)

    # 创建文本元素（w:t）并设置文本
    text = OxmlElement('w:t')
    text.text = link_text
    run.append(text)

    # 创建段落并将超链接添加到段落
    paragraph = doc.add_paragraph()
    paragraph._p.append(hyperlink)

    # 返回包含超链接的段落元素
    return paragraph._p

# 使用函数的示例
doc = Document()
url = "http://google.com"
link_text = "点击这里"
add_hyperlink(doc, url, link_text)
doc.save('path_to_save_document.docx')