LiquidGlass

LiquidGlass 是什麼？

LiquidGlass 是一個輕量的 JavaScript/TypeScript 函式庫，使用 WebGL 著色器在任意 HTML 元素上方渲染逼真的玻璃效果。它透過擷取每個玻璃元素後方的 DOM 內容並即時合成，來套用折射、模糊、色差、鏡面高光以及相關光照效果。

這個函式庫設計用於任意頁面背景（圖片、影片、畫布或純 HTML）。它採用多通道渲染管線，能處理多層玻璃、每個元素的獨立設定，以及頁面上的動態更新。

基於 WebGL 著色器的 HTML 元素玻璃渲染：透過處理玻璃元素後方的 DOM 內容並以著色器輸出合成，產生玻璃外觀。
即時多通道管線：支援折射、模糊強度控制、色邊緣分離，以及鏡面/邊緣光照效果。
每個元素與全域設定：可透過 data-config（JSON）個別設定每個玻璃元素，或透過 defaults 選項設定全域預設值。
層疊玻璃合成：透過合成方式支援玻璃疊玻璃的配置。
互動定位選項：啟用時可注入可拖曳的「浮動」面板行為（例如 floating: true），並包含 button 模式提供懸停/按壓的著色器回饋。
逼真表面控制：參數包含 cornerRadius、zRadius（斜角深度）、bevelMode（形狀曲率模式）、brightness、saturation、shadowOpacity 和 fresnel 反射。

安裝或匯入：透過 npm 安裝（npm install @ybouane/liquidglass）或直接從 CDN 匯入（https://cdn.jsdelivr.net/npm/@ybouane/liquidglass/dist/index.js）。
建立定位的根容器：傳給 LiquidGlass.init() 的 root 元素必須是具有 position: relative 的容器。
在根容器內加入玻璃元素：每個玻璃元素必須是根容器的直接子元素。初始化時，LiquidGlass 會在玻璃元素的第一個子元素注入 <canvas> 用於著色器輸出。
初始化：使用 LiquidGlass.init({ root: document.querySelector('#my-root'), glassElements: document.querySelectorAll('.glass') }) 建立實例，之後可用 instance.destroy() 清理。
設定效果：透過 element.dataset.config = JSON.stringify({ ... }) 提供每個元素的設定（例如模糊量、折射、邊角半徑）。可使用 playground 模式視覺化調整參數。

自訂「玻璃」卡片與面板：透過調整 blurAmount、brightness、cornerRadius 和 zRadius，為卡片元素套用霧面、深色或一般玻璃樣式。
互動放大鏡式鏡頭：使用 bevelMode: 1 搭配對應的 cornerRadius 和 zRadius 產生半球/圓頂鏡頭效果（可選擇啟用 floating）。
懸停/按壓 UI 回饋：設定 button: true，讓玻璃元素回應使用者互動—懸停時變亮，按壓時壓平斜角並加深陰影。
層疊玻璃疊玻璃合成：建構多層 UI，讓不同玻璃元素重疊，利用 LiquidGlass 的合成實現堆疊效果。
置於豐富背景上的玻璃：將玻璃元素置於圖片、影片、畫布或一般 HTML 內容的背景上方，同時將這些背景保持在根容器的擷取子元素內。

需要特定的 DOM 結構嗎？
是的。root 必須是定位容器（position: relative），每個玻璃元素必須是根容器的直接子元素。初始化時若有巢狀玻璃元素會顯示主控台警告並拒絕。

LiquidGlass 擷取什麼來產生玻璃效果？
著色器會取樣根容器的子元素，因此背景圖像等內容應置於根容器內的同層元素。根容器本身不會被擷取。

LiquidGlass 會自動建立任何 DOM 元素嗎？
它會在玻璃元素的第一個子元素注入 <canvas> 用於渲染著色器輸出。因此，避免在玻璃元素上依賴 :first-child CSS 選擇器。

同一頁面能否使用多個 LiquidGlass 根容器？
限制說明多個 LiquidGlass 根容器無法共享折射。另外，一個根容器中的玻璃元素無法看見另一個根容器中玻璃元素的渲染內容。

有無效能考量？
是的。函式庫依賴即時 DOM 光柵化與多通道 WebGL 管線，將 DOM 擷取至畫布被視為高耗費作業。

純 CSS 玻璃效果（backdrop-filter / 基於 blur 的技術）：更簡單且純 CSS 驅動的方法可近似霧面玻璃，但通常無法提供相同的折射/色差/鏡面管線行為。
WebGL 著色器框架或自訂 Three.js/WebGL 實作：若需完全控制，可自行實作自訂著色器通道；這會將工作從函式庫抽象層轉移至您自己的渲染管線。
其他 DOM 轉 canvas/即時效果管線：相鄰解決方案可將 DOM 點陣化為紋理，用以建立畫面空間效果，但工作流程與設定將與 LiquidGlass 的 DOM 基礎玻璃元素設定不同。
靜態設計資產：若無需互動與即時更新，預渲染玻璃影像或匯出元件可降低執行時成本，但犧牲動態折射/參數變更。