xlsx-surgerylisted

# xlsx 外科手術(xlsx Surgery) ## 什麼時候用 任何時候你要**改一個既有的 .xlsx**,而且要求「只動我指定的那幾格/那塊,**其餘全部一位元不差**」—— 尤其原檔含**公式、精細樣式、圖表、樞紐表、外部連結**這些「用函式庫重載會被動壞」的東西。 xlsx 是一個 zip 包著一堆 XML part 的格式;天真地「載入→改→存回」會**靜默破壞你根本沒碰的部分**。 這技能是那些破壞的地雷圖 + 避法。 ### ★觸發紀律(什麼時候「必須」對照本技能) **觸發時機不只是「當你動手寫 xlsx 操作碼時」,而是「任何碼路徑會碰到 xlsx 交付物的任何時刻」**—— 這包含**接既有模組**,不限新寫碼。真實事故:法則 1/3/7 白紙黑字都在,卻因為只把「產出交付檔」 接上一個**既有的**函式(它內部偷偷 `load_workbook`+`wb.save` 整檔重存),圖表照樣被毀——因為 沒人在「接線那一刻」把這條既有路徑對照法則過一遍。 **硬紀律(兩條,寫進計畫、交付前必跑):** 1. **接線前對照**:凡任何碼路徑會對 xlsx 交付檔做**寫入 / 轉存 / 搬運 / 另存**(**含呼叫既有模組**), 在接它之前先把它對照**法則 1–7 過一遍**,把「這條路徑用 ZIP 手術還是整檔重寫」寫進計畫。 既有函式的名字取得再無害(`append_source`/`build`/`save_as`…),也要打開看它內部**到底怎麼寫檔**。 2. **出口自檢必跑**:交付前跑**法則 3 的出口自檢**——拿真 Excel(或位元/圖表-parts 級對照原檔) 驗「開得了 + 圖在 + 結構等值」。寬鬆工具(openpyxl/LO)的綠**不算**通過。 --- ## 核心物理法則 ### 法則 1:最小切口——只改目標,絕不整檔/整頁重寫 主流函式庫(如 openpyxl)「載入整個工作簿再存���」會**重新序列化每一個 part**——它不認得的東西 (某些圖表、樞紐、外部連結、少見的 namespace)可能被丟失、降級或改寫。**外科手術式**: - 只對**目標 part**(某個 worksheet XML)做**字串級精確定位取代**,其他 part **原封搬運**(ZIP 級 copy)。 - 換一個 sheet 就只換那一個 part 的 bytes,別重打包整個工作簿。 - **絕不 parse 整頁的根標籤**(見法則 2 的 namespace 雷)。 ### 法則 2:五個「真 Excel 拒開、寬鬆工具看不到」的檔案級地雷 以下每一個,**openpyxl / LibreOffice 重載都容忍(顯示正常=假綠)**,只有**真 Microsoft Excel 開** 會踩到(典型症狀:「檔案損壞、要修復」、part XML error `0x808c0002`「行1欄0」)。 1. **整樹 parse 毀 namespace**:用 XML 樹工具(如 ElementTree)parse 整頁 worksheet 再寫出 → 它會把命名空間前綴**改名**(如 `mc:`→`ns1:`),又把它「以為沒用到」的 namespace 宣告當垃圾**刪掉** ——但那個宣告其實被**某個屬性的『值』**引用著(如 `mc:Ignorable="x14ac"`,`x14ac` 是屬性值裡的 前綴,樹工