現代化模板渲染
基於 React 與 TailwindCSS 嘅模板開發方案
本插件採用 React + TailwindCSS 技術棧進行圖片渲染，將現代前端嘅工程化能力引入模板開發領域，解決咗傳統模板引擎在長期維護上嘅痛點。
傳統方案嘅維護陷阱
隨著項目迭代，基於 art-template 嘅模板往往會陷入維護泥潭：
- 邏輯黑洞：業務邏輯混雜在 HTML 模板中，難以閱讀同剝離。
- 樣式衝突：全局 CSS 類名隨著時間推移不斷堆積，修改一個樣式可能導致多處崩壞。
- 重構風險：缺乏類型檢查，修改字段名就像在"排雷"，只能祈禱運行時唔出錯。
方案對比
傳統方案 (art-template)
開發痛點
- 調試低效：修改代碼 -> 編譯生成 -> 瀏覽器刷新，反饋鏈路極長。
- 工程缺失：缺乏 Source Map 導致報錯定位難；全局 CSS 易引發樣式衝突。
- 維護困難：邏輯與視圖耦合嚴重，缺乏 TypeScript 類型支持，重構風險高。
- 交互受限：僅能實現靜態渲染，難以處理複雜嘅動態佈局邏輯。
- 資源割裂：圖片、字體等靜態資源引用路徑處理繁瑣，缺乏統一嘅打包優化。
現代方案 (React)
核心優勢
- 極致體驗：內置可視化面板，支持 HMR 熱更新，毫秒級反饋。
- 架構先進：組件化開發實現高內聚低耦合；TailwindCSS 解決樣式衝突。
- 生態豐富：背靠 React 龐大生態，海量組件庫與工具庫即插即用。
- 邏輯復用：利用 Hooks 輕鬆復用狀態邏輯，輕鬆應對複雜數據處理。
- 構建優化：依託 Vite 強大嘅構建能力，自動處理資源壓縮、路徑別名等。
綜合對比表
| 特性 | art-template | React + Tailwind |
|---|---|---|
| 核心理念 | 字符串拼接模板 | 組件化視圖構建 |
| 樣式方案 | 全局 CSS (易衝突) | TailwindCSS (原子化) |
| 數據流 | 弱類型，隱式傳遞 | TypeScript 強類型 props |
| 調試體驗 | 盲寫，手動刷新 | 可視化面板，實時預覽 |
| 渲染機制 | 運行時編譯 HTML | 構建時預編譯 SSR |
架構優勢
本方案用現代前端工程化思維重構咗靜態圖片嘅生成方式，核心優勢體現在三個方面：
組件化構建：摒棄 art-template 簡陋嘅 include 語法，React 組件允許將複雜畫面拆解為獨立單元。每個組件獨立管理樣式與邏輯，基礎組件可在不同模板間無縫復用。
原子化樣式：TailwindCSS 徹底告別 style.css 幾千行嘅噩夢。樣式直接作用於 DOM 元素，不存在類名覆蓋問題；構建時自動剔除未使用的樣式，生成嘅 HTML 體積更小。
類型安全：從數據獲取到圖片渲染，全鏈路 TypeScript 類型護航。編寫模板時 IDE 自動提示數據結構，後端字段變更時前端立即報錯，避免線上"圖片渲染失敗"。
開發輔助
雖然最終產物係靜態圖片，但內置咗可視化開發面板 (pnpm dev) 來提升開發效率：
- 實時預覽：修改組件代碼，瀏覽器右側即時刷新渲染結果。
- 數據Mock：可配置多套 JSON 數據，輕鬆測試文本超長、頭像缺失等邊緣情況。
- 快速調試：無需啟動整個 Bot，僅需瀏覽器即可完成模板開發。
生態復用
得益於 React 標準，可以直接引入成熟嘅庫來豐富靜態畫面嘅表現力：
- 排版佈局：引入現代化嘅 UI 組件庫，快速構建精美嘅卡片、列表。
- 數據可視化：使用專業圖表庫將複雜數據渲染為統計圖表。
- 矢量圖標：引入海量 SVG 圖標庫，支持任意縮放不失真。
工作原理
- 開發階段：利用 Vite 提供秒級啟動與毫秒級熱更新，在可視化面板中實時調試 UI。
- 構建階段：將 React 組件編譯為優化嘅服務端渲染 (SSR) 包，不依賴瀏覽器 JS 執行。
- 運行階段：
- 插件接收數據，調用渲染函數。
- React SSR 引擎將組件渲染為純靜態 HTML。
- Karin 框架接管 HTML，調用 Puppeteer 進行截圖並發送。
性能優化
SSR 直接輸出包含完整樣式與內容嘅 HTML，Puppeteer 打開頁面後無需等待 JavaScript 加載與執行即可立即截圖，顯著降低咗渲染耗時與內存佔用。
SSR 渲染引擎
core 包通過 Render 函數調用 template 子包嘅 reactServerRender，實現咗插件邏輯與模板渲染嘅解耦。
入口與初始化：reactServerRender 接收渲染請求、輸出目錄和插件數組，首先確保輸出目錄存在，然後通過 ComponentAutoRegistry 掃描配置文件，按平台分組懶加載組件模塊並綁定數據驗證函數，最終存入 Map 註冊表。
SSRRender 實例化：創建 ResourcePathManager 檢測運行環境（開發/生產），解析包目錄路徑並處理 pnpm 符號鏈接；創建 HtmlWrapper 負責 HTML 包裝；創建 PluginContainer 並按 enforce 字段（pre → normal → post）對插件排序。
渲染流程：構建 PluginContext 上下文和 RenderState 狀態對象 → 執行 runBefore 前置插件（如二維碼生成）注入額外 props → ComponentRendererFactory 從註冊表查找組件、驗證數據、合併 props、處理嵌套路徑、調用 React.createElement → 執行 runDuring 渲染插件（可包裝組件）→ 調用 renderToString 將 React 組件轉為 HTML 字符串 → 執行 runAfter 後置插件（可修改 HTML）。
輸出階段：生成帶時間戳的安全文件名 → HtmlWrapper.wrapContent 計算 CSS 和圖片的相對路徑、替換圖片 src、注入 DOCTYPE/meta/CSS link/主題類名 → 寫入文件系統 → 返回 HTML 文件路徑供 Karin 框架截圖。
Last updated on