PPTX 建立、編輯與分析
一個 .pptx 檔案其實是 XML 檔案的 ZIP 壓縮檔。請根據任務選擇方法:
| 任務 | 方法 |
|---|---|
| 建立新簡報 | 撰寫 pptxgenjs 指令稿 — 請參閱下方的陷阱提醒 |
| 編輯現有簡報,或從範本建立 | 解壓縮 → 編輯 ppt/slides/slideN.xml → 重新壓縮 |
| 讀取內容 | markitdown deck.pptx(每個投影片會以 <!-- Slide number: N --> 標記區隔);視覺化網格:python scripts/thumbnail.py deck.pptx |
指令稿
路徑皆相對於此技能所在的目錄。其餘皆為純 Python、node 或 shell 指令。
| 指令稿 | 功能說明 |
|---|---|
scripts/thumbnail.py deck.pptx [prefix] | 為每個投影片產生標籤式網格,用於挑選範本版面配置。僅適用 .pptx。可傳入 prefix 參數,預設為 thumbnails,若不指定會覆寫同目錄中其他簡報的網格 |
scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml] | 複製一個投影片(或 slideLayoutN.xml),並自動處理所有套件內部的關聯記錄。也可直接對 .pptx 檔案使用,加上 -o out.pptx 參數 |
scripts/clean.py unpacked/ | 刪除不再被參考的投影片、媒體與關係檔案。請在完成 <p:sldIdLst> 的編輯後執行 |
scripts/office/validate.py deck.pptx [--original src.pptx] | 檢查結構描述(Schema)、關係、內容類型、圖表與投影片;每個錯誤都會指出修復方法。若簡報衍生自範本,請加上 --original 參數,它會以範本為基準進行檢查,避免範本本身的 XSD 錯誤影響結果 |
scripts/office/soffice.py --headless --convert-to pdf deck.pptx | LibreOffice 包裝指令 — 裸 soffice 指令在此沙盒中會卡住 |
使用 pptxgenjs 建立簡報 — 陷阱提醒
pptxgenjs 已預先安裝 — 請勿先執行 npm install;直接撰寫指令稿並使用 require('pptxgenjs')。僅在 require 失敗時才執行:npm install pptxgenjs。模型已知其 API;以下是常見的陷阱:
- 在新增投影片之前,請先設定
pres.layout。 預設畫布為LAYOUT_16x9= 10" × 5.625",而非 13.3" 寬。超出邊界的座標仍會被寫入,但不會被限制 — 形狀只是不在投影片上。(LAYOUT_WIDE為 13.3" × 7.5"。) - Hex 顏色:絕對不要使用
#,也不要使用 8 位數。 使用color: "FF0000"。"#FF0000"以及將透明度寫入 hex("00000020")都會破壞檔案。如需半透明效果:請在填滿與圖片上使用transparency: 0-100,在陰影上使用opacity: 0.0-1.0— 兩者若用錯對象會被靜默忽略。 - pptxgenjs 會原地修改選項物件(首次使用時會將值轉換為 EMU)。請勿對兩個不同的
add*呼叫共用同一個shadow/options 物件 — 每次都要建立全新的物件。 - 陰影
offset必須 ≥ 0 — 負數偏移會破壞檔案。若要向上投射陰影,請使用angle: 270搭配正數偏移。 letterSpacing會被靜默忽略 — 正確的選項是charSpacing。- 列表: 每個項目使用
bullet: true,不要使用字面上的•(會產生雙重項目符號)。除了最後一個項目,每個陣列項目都需設定breakLine: true。使用paraSpaceAfter來間隔有項目符號的段落,不要使用lineSpacing(會產生巨大間隙)。 - 每個輸出檔案使用一個新的
new pptxgen()— 請勿重複使用同一個實例。 rectRadius僅適用於ROUNDED_RECTANGLE,不適用於RECTANGLE。- 不支援漸層填滿 — 請改用漸層圖片作為背景。
- 文字方塊內建內部邊距 — 當文字需要與形狀、線條或圖示在同一 x 座標對齊時,請設定
margin: 0。 - 備忘稿請使用
slide.addNotes("...")(純文字,每個投影片一次),不要放在投影片上的文字方塊中。 - 保持圖表為原生格式。 使用
addChart()來處理 PowerPoint 可以繪製的任何圖表(對於組合圖,請傳入{type, data, options}的陣列)。對於程式庫未暴露的 PowerPoint 原生功能(趨勢線、誤差線),請自行計算額外的資料系列,或事後處理產生的 OOXML — 不要退而使用渲染圖片。只有 PowerPoint 沒有原生形式的圖表類型(Sankey、網路圖、弦圖)才以圖片形式放入。 - 預設圖表呈現簡陋 — 沒有標題、沒有資料標籤、配色老舊。請設定
showTitle+title、showValue: true+dataLabelPosition、從你的調色板設定chartColors: [...],並調整框架(catAxisLabelColor/valAxisLabelColor、valGridLine: { color, size }、catGridLine: { style: "none" },單一資料系列時設定showLegend: false)。 - 在堆疊長條圖或堆疊柱狀圖上,
dataLabelPosition必須是ctr、inEnd或inBase。outEnd會破壞檔案。 - 使用
secondaryValAxis/secondaryCatAxis的組合圖系列,需要在圖表選項上同時設定valAxes與catAxes,每個各兩個項目。 如果缺少,pptxgenjs 會寫入從未宣告的軸線 id,導致 PowerPoint 捨棄該圖表並報告檔案損毀。僅提供valAxes是不夠的。 - 執行
writeFile()後,請執行python scripts/office/validate.py deck.pptx。 它會報告上述兩個圖表錯誤以及 PowerPoint 會拒絕的投影片 XML 缺陷,並針對每個問題指出修復方法。請在產生器中修復它們,而不是手動編輯壓縮後的 XML。 - 絕對不要重新排列
<p:presentation>的子元素。 pptxgenjs 會將<p:notesMasterIdLst>寫在<p:sldIdLst>之後,並將兩個母版指向同一個主題部分。PowerPoint 可以正常讀取 — 但若移動該元素,同一個簡報就會變得無法開啟。 - 圖示: 將
react-icons渲染為 SVG(ReactDOMServer.renderToStaticMarkup),使用sharp以 ≥256px 進行柵格化,然後透過addImage({ data: "image/png;base64," + buf.toString("base64") })插入 — 需要image/png;base64,前綴(react-icons、react、react-dom與sharp已預先安裝 — 僅在require失敗時才執行npm install react-icons react react-dom sharp)。
編輯現有簡報與範本
首先挑選版面配置:python scripts/thumbnail.py template.pptx template-thumbs 會產生每個投影片的標籤式網格,並列出產生的檔案 — template-thumbs.jpg,超過 12 張投影片時會拆分為 template-thumbs-N.jpg。請務必傳入第二個參數,並以簡報名稱命名。 預設為 thumbnails,因此同一個目錄中兩個簡報的縮圖會靜默地互相覆蓋 — 第一個簡報的網格會直接消失(此功能僅適用於範本分析 — 視覺品質檢查需要轉換為圖片中的全解析度渲染;且僅接受 .pptx,因此請先將 .potx 複製為 .pptx 名稱)。搭配 markitdown 使用,將每個內容段落對應到範本投影片,並變化版面配置 — 不要將每個段落都放在同一個「標題與項目符號」投影片上。
python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml # 複製一個投影片(或 slideLayoutN.xml);會印出新投影片的路徑
# 重新排序 / 刪除投影片 = 編輯 ppt/presentation.xml 中的 <p:sldIdLst>
python scripts/clean.py unpacked/ # 刪除後:移除孤立的投影片、媒體、關係
# 在 ppt/slides/slideN.xml 中編輯投影片內容
(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .) # 在目錄「內部」進行壓縮;若不移除,被刪除的部分會殘留
python scripts/office/validate.py out.pptx --original deck.pptx
- 在編輯任何投影片內容之前,請先完成所有結構性工作 — 新增、刪除、重新排序。
add_slide.py會直接複製投影片檔案,因此在編輯後複製會複製到已編輯的內容;而clean.py會刪除任何不在<p:sldIdLst>中的投影片,包括你剛寫入的投影片。 - 絕對不要手動複製投影片檔案 —
add_slide.py會為新投影片進行所有必要的註冊,並報告其結果(Created ppt/slides/slide17.xml from slide2.xml)。它也可以直接對檔案操作:add_slide.py deck.pptx slide2.xml -o out.pptx— 請務必傳入-o,否則它會原地改寫輸入的簡報。 複製的投影片仍會「參考」其來源的圖表/SmartArt/內嵌物件部分,而非複製它們,因此編輯一個投影片的圖表會改變另一個投影片。 - 如果你使用
python-pptx,請注意它有三項功能無法做到:複製投影片(其唯一的進入點是add_slide(layout))、透過text_frame.text = "..."保留格式(這會將段落折疊成一個未設定樣式的 run — 請改為指派run.text)、以及讀取大多數範本藝術檔案使用的 SVG/EMF(add_picture會引發UnidentifiedImageError)。 - 舊版
.ppt必須先轉換:python scripts/office/soffice.py --headless --convert-to pptx file.ppt。.potx範本的解壓縮與壓縮方式完全相同 — 請在輸出時保留.potx副檔名。 - 若要重複使用範本中的圖示或圖片,請複製已包含該項目的投影片或版面配置。
在填入範本時:
- 如果你要撰寫 XML 轉換腳本,請使用
defusedxml.minidom進行解析 — 透過xml.etree.ElementTree進行 OOXML 的往返轉換會改寫命名空間前綴並破壞簡報。 - 範本插槽 ≠ 來源項目。 如果範本顯示 4 位團隊成員,而你只有 3 位,請刪除第 4 位成員的整個群組(圖片 + 文字方塊),而不僅僅是文字 — 然後在品質檢查中檢查是否有孤立的視覺元素。
- 每個列表項目一個
<a:p>— 切勿將項目串聯成單一段落。複製同級<a:pPr>以保留間距,並在標題、章節標題與行內標籤(Status:、Owner:)上將<a:rPr>設定為b="1"。 - 讓項目符號繼承自版面配置;僅在需要覆蓋時才加入
<a:buChar>、<a:buAutoNum>(編號)或<a:buNone>— 絕不要在文字中使用字面上的•。 - 開頭或結尾有空白的文字需要在
<a:t>上設定xml:space="preserve"。
設計點子
不要建立無聊的投影片。 白色背景上的純文字項目符號無法打動任何人。請考慮針對每個投影片使用此清單中的點子。
開始之前
- 選擇一個大膽且符合內容的調色板:調色板應讓人感覺是為此主題特別設計的。如果你將顏色換到一個完全不同的簡報中仍然「可行」,那就表示你的選擇還不夠具體。
- 支配優先於均等:一種顏色應主導(60-70% 的視覺重量),搭配 1-2 種輔助色調與一種鮮明的強調色。絕對不要讓所有顏色重量均等。
- 深色/淺色對比:標題與結論投影片使用深色背景,內容投影片使用淺色(「三明治」結構)。或者,整份簡報都使用深色以營造高級感。
- 致力於一個視覺主題:選擇一個獨特元素並重複使用 — 圓角圖片框架、彩色圓圈中的圖示。讓它出現在每個投影片上。不要使用色塊或強調條作為你的主題(參閱避免清單)。
調色板
選擇與主題相符的顏色 — 不要預設使用通用的藍色。使用以下調色板作為靈感:
| 主題 | 主要色 | 次要色 | 強調色 |
|---|---|---|---|
| 午夜主管 | 1E2761(海軍藍) | CADCFC(冰藍) | FFFFFF(白) |
| 森林與苔蘚 | 2C5F2D(森林) | 97BC62(苔蘚) | F5F5F5(奶油) |
| 珊瑚能量 | F96167(珊瑚) | F9E795(金) | 2F3C7E(海軍藍) |
| 暖陶土 | B85042(陶土) | E7E8D1(沙) | A7BEAE(鼠尾草) |
| 海洋漸層 | 065A82(深藍) | 1C7293(青綠) | 21295C(午夜) |
| 炭灰極簡 | 36454F(炭灰) | F2F2F2(米白) | 212121(黑) |
| 青綠信賴 | 028090(青綠) | 00A896(海沫) | 02C39A(薄荷) |
| 莓果與奶油 | 6D2E46(莓果) | A26769(塵玫瑰) | ECE2D0(奶油) |
| 鼠尾草平靜 | 84B59F(鼠尾草) | 69A297(尤加利) | 50808E(石版) |
| 櫻桃大膽 | 990011(櫻桃) | FCF6F5(米白) | 2F3C7E(海軍藍) |
每個投影片
每個投影片都需要一個視覺元素 — 圖片、圖表、圖示或形狀。純文字投影片容易被遺忘。
版面配置選項:
- 兩欄(左側文字,右側插圖)
- 圖示 + 文字行(彩色圓圈中的圖示、粗體標題、下方說明)
- 2x2 或 2x3 網格(一側為圖片,另一側為內容區塊網格)
- 半出血圖片(全左或全右側)搭配內容疊加
資料顯示:
- 大型統計數字標註(60-72pt 大字型,下方對應小標籤)
- 比較欄(之前/之後、優點/缺點、並列選項)
- 時間軸或流程圖(編號步驟、箭頭)
視覺修飾:
- 章節標題旁的小型彩色圓圈中的圖示
- 關鍵統計數據或標語使用斜體強調文字
排版
你寫入 .pptx 中的字型名稱會由使用者的 PowerPoint 渲染,而非由這個環境。你的視覺品質檢查透過 LibreOffice 渲染,它會替換它沒有的字型 — 而某些字型的替代字型具有不同的寬度,因此你的品質檢查預覽可能會顯示文字溢位(或貼合),而實際簡報中可能不會發生。為了讓你的品質檢查可靠:
- 安全字型(在品質檢查中渲染寬度準確 且 Office 內建):Arial、Calibri、Cambria、Times New Roman、Courier New、Bookman Old Style、Century Schoolbook。對於本文以及任何需要考慮貼合度的內容,請使用這些字型。
- 零品質檢查風險的個性化標題:將安全清單中的襯線字型標題(Cambria、Bookman Old Style、Century Schoolbook)與安全清單中的無襯線本文字型(Calibri 或 Arial)搭配使用。你可以在不放棄可靠溢位檢查的情況下獲得視覺對比。
- 如果使用者指定了安全清單以外的字型(例如 Georgia 或 Trebuchet MS):在使用者要求的地方使用它,但請為這些容器預留額外空間(約 10%),並且不要信任這些元素上的品質檢查文字貼合度 — 該字型的預覽是近似值。如果使用者未指定,請優先為本文使用安全清單字型。
- 品質檢查不可靠字型(替代字型具有不同寬度 — 溢位檢查可能錯誤):Georgia、Trebuchet MS、Impact、Arial Black、Garamond、Consolas、Palatino Linotype。Calibri Light 的替代字型因環境而異;請將其視為品質檢查不可靠。適用於帶有空間的標題/強調文字;請不要信任這些字型上的品質檢查文字貼合度。
- 絕不預設使用 Aptos — Office 2023 之後的預設字型在此處沒有指標相容的替代字型 並且 在較舊的 Office 安裝中缺失,因此它在兩端都不可靠。
| 元素 | 大小 |
|---|---|
| 投影片標題 | 36-44pt 粗體 |
| 章節標題 | 20-24pt 粗體 |
| 本文 | 14-16pt |
| 標題 | 10-12pt 低調 |
…
[因翻譯而截斷]