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 / 基于模糊的技术）：更简单且纯 CSS 驱动的方法可近似磨砂玻璃效果，但通常无法提供相同的折射/色差/镜面管线行为。
WebGL 着色器框架或自定义 Three.js/WebGL 实现：如果需要完全控制，可自行实现自定义着色器通道；这将工作从库抽象转移到您自己的渲染管线。
其他 DOM 转 canvas/实时效果管线：相邻解决方案可将 DOM 栅格化为纹理以创建屏幕空间效果，但工作流程和配置将不同于 LiquidGlass 的基于 DOM 的玻璃元素设置。
静态设计资源：对于无需交互和实时更新的情况，预渲染玻璃图像或导出组件可降低运行时成本，但牺牲动态折射/参数变更。