Python-docx 進階手術室：從底層 XML 到超連結混合技; from docx.opc.constants import RELATIONSHIP_TYPE as RT ; part = doc.part ; r_id = part.relate_to(url, RT.HYPERLINK, is_external=True)

from docx import Document
import os

# 確保目錄存在
os.makedirs(r'D:\Temp', exist_ok=True)

def create_demo_doc():
    doc = Document()
    doc.add_heading('原始文件標題', 0)
    doc.add_paragraph('這是原始文件的第一段內容。')
    doc.add_paragraph('這是原始文件的第二段內容。')
    doc.save(r'D:\Temp\demo_origin.docx')
    print("測試檔案 'demo_origin.docx' 已生成！")

if __name__ == "__main__":
    create_demo_doc()

from docx import Document
from docx.oxml import OxmlElement
from docx.oxml.ns import qn
from docx.opc.constants import RELATIONSHIP_TYPE as RT

def run_advanced_demo():
    # 讀取剛剛生成的檔案
    doc = Document(r'D:\Temp\demo_origin.docx')
    body = doc.element.body  # 取得 XML 的 Body 元素

    # =====================================================
    # 方法一：高階 API (High-Level)
    # =====================================================
    print("--- 執行方法一：標準加入 ---")
    # 限制：只能 Append 到文件「最後面」
    doc.add_paragraph('方法一：我是高階 API 產生的段落 (在最後面)')


    # =====================================================
    # 方法二：底層 XML (Low-Level) - 絕對位置插入
    # =====================================================
    print("--- 執行方法二：底層 XML 組裝 ---")
    # 手動組裝 XML 結構： <w:p> -> <w:r> -> <w:t>
    
    p_elem = OxmlElement('w:p') # 1. 段落
    r_elem = OxmlElement('w:r') # 2. 樣式片段
    t_elem = OxmlElement('w:t') # 3. 文字
    t_elem.text = '方法二：我是底層 XML 組裝的段落 (插在最前面)'
    
    r_elem.append(t_elem)  # 裝箱
    p_elem.append(r_elem)  # 裝箱
    
    # 插入到 Body 的 Index 0 (最前面)
    body.insert(0, p_elem)


    # =====================================================
    # 方法三：混合技 (Hybrid) - 先建後移 (絕對位置)
    # =====================================================
    print("--- 執行方法三：混合技 (Insert) ---")
    # 1. 用高階 API 快速建立 (預設在最後)
    new_p = doc.add_paragraph('方法三：我是混合技產生的段落 (原本在後，被移到前)')
    new_p.runs[0].bold = True 

    # 2. 取得底層 XML 元素
    p_element = new_p._p

    # 3. 安全移除 (找爸爸刪除自己)
    if p_element.getparent() is not None:
        p_element.getparent().remove(p_element)
        
    # 4. 插在 Index 1 (剛好在方法二的後面)
    body.insert(1, p_element)


    # =====================================================
    # 方法四：相對定位法 (Relative) - 使用 addnext 插隊
    # =====================================================
    print("--- 執行方法四：相對定位 (addnext) ---")
    # 情境：我想要插在「原始文件標題」的後面
    
    # 1. 建立段落
    p4 = doc.add_paragraph('方法四：我是用 addnext 插隊的段落 (在標題後面)')
    p4.runs[0].font.italic = True
    p4_elem = p4._p
    
    # 2. 安全移除
    if p4_elem.getparent() is not None:
        p4_elem.getparent().remove(p4_elem)
    
    # 3. 找到錨點 (Anchor)
    # 目前順序：[0]方法二 -> [1]方法三 -> [2]原始標題
    anchor_paragraph = body[2] 
    
    # 4. 插隊 (跟在標題後面)
    anchor_paragraph.addnext(p4_elem)


    # =====================================================
    # 方法五：超連結混合技 (Hyperlink Hybrid) - 大魔王
    # =====================================================
    print("--- 執行方法五：超連結混合技 ---")
    url = "https://www.google.com"
    link_text = "方法五：點我前往 Google (我是超連結，我也插在最前面)"

    # 1. [高階] 註冊關聯 (取得 rId)
    part = doc.part 
    # docx.parts.document.DocumentPart
    r_id = part.relate_to(url, RT.HYPERLINK, is_external=True)

    # 2. [底層] 手工打造 <w:hyperlink>
    hyperlink = OxmlElement('w:hyperlink')
    hyperlink.set(qn('r:id'), r_id) # 設定關聯 ID

    # 3. 建立內容 (Run + 樣式 + Text)
    run = OxmlElement('w:r')
    rPr = OxmlElement('w:rPr')
    
    # 設定藍色
    c = OxmlElement('w:color')
    c.set(qn('w:val'), '0000FF')
    rPr.append(c)
    # 設定底線
    u = OxmlElement('w:u')
    u.set(qn('w:val'), 'single')
    rPr.append(u)
    
    run.append(rPr)
    
    # 設定文字
    t = OxmlElement('w:t')
    t.text = link_text
    run.append(t)
    
    hyperlink.append(run) # 把 Run 裝進 Hyperlink

    # 4. [混合技] 借殼上市
    # 建立一個空段落容器
    p_container = doc.add_paragraph()
    # 把超連結塞進去
    p_container._p.append(hyperlink)

    # 5. [底層] 移動位置 (移到最前面 Index 0)
    p_link_elem = p_container._p
    
    # 安全移除
    if p_link_elem.getparent() is not None:
        p_link_elem.getparent().remove(p_link_elem)
        
    # 插隊當老大
    body.insert(0, p_link_elem)


    # 存檔
    output_path = r'D:\Temp\demo_result_final.docx'
    doc.save(output_path)
    print(f"操作完成！請開啟 '{output_path}' 查看結果。")

if __name__ == "__main__":
    run_advanced_demo()

# 1. [高階] 註冊關聯 (取得 rId)
part = doc.part 
# docx.parts.document.DocumentPart
r_id = part.relate_to(url, RT.HYPERLINK, is_external=True) 

<Relationship Id="rId5" 
              Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink" 
              Target="https://www.google.com" 
              TargetMode="External"/>

<!-- ❌ 錯誤寫法 -->
<w:hyperlink url="https://www.google.com"> ... </w:hyperlink>

<!-- ✅ 正確寫法 -->
<w:hyperlink r:id="rId5"> ... </w:hyperlink>

    # 4. 插隊 (跟在標題後面)
    anchor_paragraph.addnext(p4_elem)

# 假設 anchor 是標題
anchor_paragraph = body[2] 

# 建立新段落
p_new = doc.add_paragraph("我是插隊在前面的段落")
p_elem = p_new._p

# 安全移除
if p_elem.getparent() is not None:
    p_elem.getparent().remove(p_elem)

# 插在標題前面
anchor_paragraph.addprevious(p_elem)