REFERENCE / V2

从一个标签开始。

引入脚本、给组件明确尺寸、选择一个 mode。复杂内容通过 JavaScript 方法设置。

当前脚本: /liquid-glass.js
运行方式: WebGL 1.0 + Custom Element
运行时依赖: 无

安装

在页面中加载当前站点提供的脚本。浏览器会注册 <liquid-glass>。

<script src="/liquid-glass.js"></script>

快速开始

组件内部是 Canvas，没有宽高时不会渲染。先从单开关模式开始。

<script src="/liquid-glass.js"></script>

<liquid-glass
  mode="single-toggle"
  wallpaper="/assets/space-planet.jpg"
  dpr="1.5"
  style="width: 560px; max-width: 100%; height: 220px;">
</liquid-glass>

建议：移动端先使用 dpr="1" 或 dpr="1.5"，确认性能后再提高。

属性

属性	值	作用
`mode`	模式字符串	选择要渲染的组件。
`dark`	布尔属性	切换深色组件主题。
`wallpaper`	图片 URL / `gradient`	设置玻璃采样的背景。
`dpr`	≥ 0.5	限制渲染倍率，最高不超过设备 DPR。
`corner-style`	`0` / `1` / `2`	直角、圆角或胶囊风格。
`blur-tap-cap`	1–33	手指按压时的模糊上限。
`overlay-buttons`	布尔属性	显示画布内返回和主题按钮。
`theme-button`	布尔属性	只显示画布内主题按钮。

组件模式

优先使用单组件模式；双组件模式主要用于透明版和卡片版对比。

single-toggle单开关220px

single-slider单滑块220px

single-bottom-tabs单标签栏180px

buttons按钮组按内容

dialog对话框330px

scroll-container滚动列表440px

rating星级评分240px

ring-progress圆环进度300px

magnifier放大镜360px

toggle双开关对比360px

slider双滑块对比360px

bottom-tabs双标签栏对比340px

JavaScript API

配置数组和对象建议通过方法传入。元素进入 DOM 后，在下一帧调用。

setState(patch)

直接更新公开状态，例如评分值或圆环进度。

setTabs(groups)

设置一组或两组底部标签栏项目。

setButtons(items)

设置按钮文字、ID 和样式。

setDialog(config)

设置标题、正文与按钮文字。

setScroll(items)

设置滚动列表的标题和副标题。

const glass = document.querySelector('liquid-glass');

requestAnimationFrame(() => {
  glass.setButtons([
    { id: 'save', label: '保存', style: 'blue' },
    { id: 'cancel', label: '取消', style: 'surface' }
  ]);
});

事件

事件	`detail`	触发时机
`lg-statechange`	当前组件状态	主题、滑块、评分等状态改变。
`lg-navigate`	`{ dest, name }`	组件内部导航。
`lg-back`	无	点击返回操作。
`lg-buttontap`	`{ id }`	按钮组被点击。
`lg-dialogtap`	`{ action }`	对话框操作。
`lg-linktap`	`{ index, href }`	可点击链接项目触发。

glass.addEventListener('lg-statechange', (event) => {
  console.log(event.detail);
});

排错

画布完全空白

先检查组件是否有明确宽高，再确认 /liquid-glass.js 返回 JavaScript 而不是 404 页面。

壁纸加载后变黑

跨域图片需要允许 CORS。最稳妥的做法是把壁纸放在同一个 Cloudflare Pages 项目中。

手机滚动或动画卡顿

把 dpr 降为 1 或 1.5，同时减少页面中的 WebGL 组件数量。

浏览器提示 WebGL context 过多

切换展示内容时复用同一个元素，或先调用 remove() 销毁旧元素。单页建议控制在 6 个实例以内。

Cloudflare Pages 部署

连接 GitHub 仓库后使用以下配置。每次推送 main 都会重新构建。

Production branch: main
Build command: npm ci && npm run build
Build output directory: dist

部署完成后依次检查根页面、/doc/ 和 /liquid-glass.js。