HTML優先投影片製作是做什麼的？

一個兩階段的製作方式，打造使用者仍可在PowerPoint中編輯的自訂精美投影片。

為什麼採用這個工作流程

PowerPoint是進行視覺設計迭代最糟糕的地方——緩慢、繁瑣、難以保持一致。 HTML/CSS是最適合迭代的地方：你可以在幾秒鐘內排版一張投影片、預覽並調整間距、色彩和層級。但最終成品必須是真實、可編輯的.pptx，以便使用者在自己的工具中調整用詞和品牌元素（將每張投影片輸出為圖片對他們來說毫無用處）。

所以：在HTML中設計，以原生PPTX交付。 你既可以快速迭代，又能得到可編輯的結果。

此資料夾中的內容：

檔案	用途
`references/html_prototype.html`	第一階段起點：三張投影片、以CSS變數定義的品牌色彩、幻燈片導航
`scripts/pptx_helpers.py`	第二階段輔助函式庫：幾何、調色盤、頁首/頁尾/卡片/膠囊/重點元件
`scripts/render_diagram.py`	將程式碼繪製的SVG渲染為高解析度PNG
`scripts/render_pptx.ps1`	將.pptx的每張投影片匯出為PNG以供檢查（Windows + PowerPoint）
`examples/example_deck.py`	一個可執行的三張投影片範例，建構在輔助函式庫之上
`examples/example_diagram.py`	一個可執行的圖表產生器，展示圖表章節中的每一種技巧

語氣——像顧問一樣撰寫標題，而不是像文案

在撰寫任何標題、副標題或內文之前，請先閱讀此處。 版面編排正確但用詞不當產生的投影片，使用者必須重寫，這比沒有投影片更糟。這適用於任何要呈現給客戶或同事的內容——投影片、HTML投影片秀、儀表板、狀態報告、一頁文件。

LLM在處理投影片時的預設語域是搶眼的廣告文案。大多數商業受眾並不想要這種風格。除非使用者另有要求，否則請以資深顧問為高階主管受眾撰寫的語域來書寫：平實、陳述性、具體且一次到位。

規則

標題應說明投影片的內容，而非進行表演。

命名內容。如果只掃描標題的讀者無法重建論點，那麼標題就失敗了。有標籤和編號永遠比耍聰明好——階段1：退貨漏洞告訴讀者他們在哪裡；我們開頭的那張則什麼都沒說，迫使他們繼續閱讀才能搞清楚。

應避免的結構

不要	為什麼失敗	要這樣做
`儀表板報告。` / `它不做解釋。`	兩拍的「鋪陳然後爆點」。讀起來像口號，而非發現。	`目前的儀表板報告數字，但未進行分析`
`他們因為儀表板而放棄了最後一個工具。` / `別再賣他們另一個儀表板了。`	同樣的兩拍，外加對讀者說教。	`為什麼另一個儀表板無法解決這個問題`
`我們開頭的那張：`	一個冒號的懸念，隱藏答案以製造懸疑。	`階段1：退貨漏洞`
`而以下是你的解決方法。`	顯得隨意，而且回答了沒人問的問題。	`建議修復方案與建置估價`
`三件事。然後我們去證明它。`	為了節奏而使用的斷裂片段。	`我們這次會議需要的東西`
`擺在桌上的東西。`	用慣用語代替描述。	`我們交付的項目`
`每兩週，一個附帶數字的發現。`	標語取代了標籤。	`時間表`
`只有一位能看到全部四家供應商的人，才會發現這個。`	修辭鋪陳。	`為什麼我們的團隊適合進行這項工作`

也要避免：以修辭疑問句作為標題；單詞的戲劇性效果（陷阱、招數、收尾）作為主要標題；為了衝擊力而使用的句子片段；破折號揭示；「事情是這樣的」；任何聽起來像是要大聲朗讀的東西。

具體來說

標題： 名詞短語或平實陳述。分析方法、資料需求與交付日期、給客戶的問題、執行第一階段所需條件。
將工作編號。 階段、層級、步驟。階段1到階段8、層級1/2/3。編號讓計畫清晰易懂，並讓人們在會議中有可以參考的對象。
副標題承載限定詞，而不是玩笑：階段1 · 方法、資料請求 · 層級1。
內文： 包含主詞和動詞的完整句子。一次、正確地說出重點，而不是用越來越強烈的語氣重複三次。
保留具體細節。 平實不意味著模糊。今年迄今840萬美元，退款率12.5% 是完全正確的。數字、名稱、日期和來源是讓它可信的關鍵。
謹慎使用粗體——用於段落中承載重量的那一個詞組，而不是為了節奏。
引言是例外。 客戶的原話可以保持原樣，而一句真正有力的句子可以放在引用框中——但要將其陳述為一個發現，而不是標語。

百分比必須附帶基數

百分比很好——繼續使用它們。但沒有基數的百分比無法判斷。「前10%的經紀人」在20名經紀人中代表2人，而在1000人中代表100人；讀者無法判斷這是一個模式還是兩個個體。

每次百分比是關於人、事物或事件的份額時，都要將計數放在百分比旁邊。 前6名經紀人（60人中的10%）、4,100名客戶（820,000人中的0.5%）、供應商A收到1,200萬美元，佔所有退款金額（2,400萬美元）的一半。
當群體很小時，先寫數字，再寫百分比。 少於約30個項目時，計數本身就是發現：6名經紀人開出了18,000美元 優於 10%的經紀人開出了20%的金額。
並列的兩個百分比需要各自的基數。 20%的金額來自12%的聯繫人只有在讀者同時知道這是18,000美元中的90,000美元以及30,000個聯繫人中的3,600個時才有用。
指明分母。 說明百分比是相對於什麼：佔8月退款金額、佔至少索賠一次的客戶、佔工作10天或以上的經紀人。
在可能的情況下，說明百分比對應的金額或人數。「3%支付給了不同的帳戶」變成 1,500筆退款（15萬美元），佔全年總額的3%。
佔整體份額的發現值得使用佔整體份額的圖表，例如100%堆疊長條圖，這樣讀者無需計算就能看到一半。

自我檢查：對於頁面上的每個%，讀者能否不離開句子就回答「佔多少的？」？如果不能，請加上計數。

出貨前的自我檢查

單獨、按順序閱讀投影片的標題。如果它們讀起來像目錄，那就對了。如果它們讀起來像推銷稿，就重寫。

第一階段——在HTML中建立原型

在16:9的畫布（1280×720）上，用每張投影片一個 .slide div 來構建 deck.html。將品牌色彩放在 :root CSS變數中（從使用者的範本中提取——請參閱下方的「品牌」）。編排頁首、章節標題、卡片、提示框、表格。在此處迭代直到設計正確——透過開啟/截圖來預覽，並讓使用者確認結構和外觀。

references/html_prototype.html 是一個現成的起點（封面、一個帶頁首+三張卡片+重點的投影片、一張圖片投影片、頁尾），並附帶CSS變數調色盤。請閱讀並改編它。

這個階段是設計的沙盒。不要追求每個字的完美——要確定版面系統（頁首/頁尾的裝飾、卡片樣式、字型比例、強調色的用法），因為第二階段會鏡像它。

讓原型像幻燈片一樣可導航

總是在 </body> 之前加入這個小腳本，讓HTML預覽像PowerPoint一樣前進——點擊（或 →/↓/空白鍵）前往下一張投影片，←/↑ 返回。 這讓第一階段的審查感覺像在簡報，而且是純HTML的（沒有需要帶入第二階段的東西）。

選取文字時絕對不能翻頁。 人們會選取投影片上的文字來複製它。拖曳會以 click 事件結束，所以單純的點擊處理器會在中間複製時跳到下一張投影片。以下腳本會忽略滑鼠在按下和放開之間移動超過5px時的點擊，或當有文字被選取時。真正的點擊仍然會前進。

點擊必須從被點擊的那張投影片前進，絕不能根據滾動位置猜測。猜測在某些視窗大小下會選錯投影片，導致一次點擊跳過兩張投影片。按鍵（→/←）仍然可以使用滾動位置，因為沒有東西可以點擊。

<script>
  /* 像幻燈片一樣預覽：點擊或 →/↓/空白鍵 = 下一張，←/↑ = 上一張。選取文字不會前進。 */
  (function(){
    var slides=[].slice.call(document.querySelectorAll('.slide'));
    function next(){ var y=scrollY+10; return slides.find(function(s){return s.offsetTop>y;}) || null; }
    function prev(){ var y=scrollY-10, p=null; slides.forEach(function(s){ if(s.offsetTop<y) p=s; }); return p; }
    function to(s){ if(s) s.scrollIntoView({behavior:'smooth',block:'start'}); }
    var downX=0,downY=0;
    addEventListener('mousedown',function(e){ downX=e.clientX; downY=e.clientY; });
    addEventListener('click',function(e){
      if(e.target.closest('a,button,input,textarea,select'))return;
      /* 選取文字或拖曳滑鼠，不是對投影片的點擊 */
      var sel=window.getSelection&&String(window.getSelection()); if(sel&&sel.trim())return;
      if(Math.abs(e.clientX-downX)>5||Math.abs(e.clientY-downY)>5)return;
      /* 從被CLICKED的投影片前進，而不是根據滾動位置猜測 */
      var s=e.target.closest('.slide'); to(s ? slides[slides.indexOf(s)+1] : next());
    });
    addEventListener('keydown',function(e){
      if(['ArrowRight','ArrowDown',' ','PageDown'].indexOf(e.key)>-1){e.preventDefault();to(next());}
      else if(['ArrowLeft','ArrowUp','PageUp'].indexOf(e.key)>-1){e.preventDefault();to(prev());}
    });
  })();
</script>

如果投影片只停留在瀏覽器中（HTML投影片秀），到此為止：第一階段就是交付物。

第二階段——生成原生的可編輯PPTX

使用 python-pptx 重新建立已批准的設計，讓每個元素都可編輯。使用配套的輔助函式庫 scripts/pptx_helpers.py——將其複製到投影片資料夾中。它提供了16:9的幾何、品牌調色盤區塊，以及你會在每張投影片上重複使用的元件：

new_prs()、blank_slide(prs)、body_bg(slide)
add_header(slide, title, meta)、add_footer(slide, left, right)
add_section_title、add_subtitle
add_text(...) — 支援字串、段落列表或混合樣式的執行區： [[("粗體部分", {"bold": True}), ("普通部分", {"color": MUTED})]]
add_rect、add_card（頂部/左側強調色條）、add_pill、bulleted、add_takeaway
add_image(slide, path, x, y, w) — 以圖片自身比例放置圖片
save_deck(prs, path) — 儲存，並在檔案被鎖定/開啟時切換到新檔名

結構（請參閱 examples/example_deck.py 以取得可執行的三張投影片範例）：

from pptx_helpers import *
def slide_intro(prs): ...      # 每張投影片一個建構函式
def slide_cards(prs): ...
def main():
    prs = new_prs()
    slide_intro(prs); slide_cards(prs)
    print(save_deck(prs, DECK_DIR / "我的投影片.pptx"))

艱苦贏得的規則（這些可以防止常見失敗）

永遠不要覆蓋使用者已開啟的檔案。 PowerPoint會鎖定該檔案；直接的 prs.save() 會拋出 PermissionError。save_deck() 透過提升到 v2、 v3……來處理這個問題。將工作副本放在明顯的地方，並告訴使用者哪個檔案是最新的。
將所有東西建構成圖形/文字，而不是圖片。 這就是重點——他們必須能夠編輯它。對於密集的比較，請使用真實的表格（slide.shapes.add_table）。
在每個執行區上明確設定字型（python-pptx無法可靠地繼承主題字型）。
關閉自動圖形的預設陰影（shape.shadow.inherit = False）並清除它們的預設文字——輔助函式庫已經這樣做了。
每張投影片一個建構函式 + 一個按順序列出它們的 main()。在那裡重新編號頁尾。

預覽/驗證循環（一定要做——不要在不看的情況下出貨）

每次建置後，將投影片渲染為PNG並實際查看；修正溢出/間距；重新建置。

Windows（已安裝PowerPoint）：
```
powershell -NoProfile -File scripts/render_pptx.ps1 -pptx "我的投影片.pptx" -outdir preview
```
會寫出 preview/s1.png、s2.png……它會以唯讀方式開啟檔案，因此即使使用者已開啟投影片也能運作，而且如果PowerPoint已在執行中，它會保持執行。
沒有PowerPoint — 如果可用的話，可以使用 libreoffice --headless --convert-to pdf（或轉為PNG）。

然後閱讀PNG，調整建構函式，重新執行。迭代直到乾淨為止。

品牌（色彩 + 字型）

不要預設使用一個調色盤。從使用者的情境中提取品牌：讀取 .pptx 範本的主題（ppt/theme/theme1.xml → <a:clrScheme>）、公司的網站/CSS，或詢問2–3種顏色。在 :root 變數（HTML）和 pptx_helpers.py（PPTX）頂部的BRAND區塊中設定它們一次，以使兩個階段匹配。將 WORDMARK_PATH 設定為品牌標誌的PNG路徑，或保留為 None。這兩個檔案中出貨的顏色是中性的預設值；請替換它們。

投影片內部的圖表——用程式碼繪製它們，不要生成它們

對於投影片上的主視覺（流程圖、管道圖、漏斗圖、架構圖或流程圖），不要手動放置數十個PowerPoint圖形，也不要用AI圖像生成器。圖像模型是為照片和藝術而建構的。對於圖表，它們會失敗：文字模糊、標籤拼寫錯誤、形狀對不齊、顏色偏離品牌，而且沒有任何東西是可編輯的。

相反，請撰寫一個SVG（一個用程式碼定義的向量圖形：<path>、<circle>、<rect>、<text>，帶有漸層和濾鏡）並將其渲染為高解析度PNG。電腦會按照規格繪製每一條線，因此它會是像素級銳利、完全符合品牌、可重複且易於編輯（更改十六進位代碼或詞語並重新渲染）。

對使用者的一個類比：要求圖像模型繪製圖表，就像要求藝術家憑記憶徒手繪製藍圖。撰寫程式碼來繪製它就像是CAD——一把尺和圓規——每次都精確無誤。

用於：管道/流程/漏斗圖、架構圖、流程圖、概念圖……

HTML優先投影片製作