` 的 d 值 |
| `label` | 否 | string | `"Tab 1"` / `"Tab 2"` ... | tab 下方文字 |
| `viewport` | **强烈建议** | number | `960` | path 的坐标范围。Material Icons 填 **24** |
`viewport` 的坑：默认 960 是飞行图标用的坐标范围。如果你用 Material Design icons（坐标范围 0-24），不传 viewport 会导致图标缩放为 `24/960 = 2.5%`，肉眼看不见。SVG path 图库见[第 16 节](#icons)。
### `el.setButtons(config)`
设置按钮组。
- **参数类型：** `Array<{id?, label?, style?}>`
- **style 预设：** `transparent` / `surface` / `blue` / `orange` / `red` / `green` / `purple`
- **style 自定义：** `[r, g, b, a]` RGBA 数组（0-1）
```js
el.setButtons([
{ id: 't', label: '透明', style: 'transparent' },
{ id: 's', label: '表面', style: 'surface' },
{ id: 'b', label: '蓝色', style: 'blue' },
{ id: 'c', label: '自定义紫', style: [0.6, 0.2, 1, 0.8] }
]);
```
### `el.setDialog(config)`
设置弹窗文案。
- **参数类型：** `{title?, body?, cancelText?, okayText?}`
```js
el.setDialog({
title: '提示',
body: '这是一条通知消息。',
cancelText: '取消',
okayText: '确定'
});
```
### `el.setScroll(config)`
设置滚动容器卡片列表。
- **参数类型：** `Array<{title, subtitle?, link?}>`
- `link` 是 `{text, href?}`
```js
el.setScroll([
{ title: '标题', subtitle: '副标题', link: { text: '查看', href: 'https://...' } },
{ title: '只有标题' }
]);
```
---
## 7. 所有事件一览 {#events}
所有事件都是 `CustomEvent`，`bubbles: true`（冒泡到 document）。
| 事件名 | `event.detail` 内容 | 何时触发 |
|--------|---------------------|----------|
| `lg-statechange` | `{toggleOn, sliderValue, selectedTab, selectedTab2, dark, hideOverlayButtons, globalSeparableBlur}` | 用户拖拽开关/滑块/点击 tab 时 |
| `lg-buttontap` | `{id}` | 按钮被点击，id 是 `setButtons` 传的 id |
| `lg-dialogtap` | `{action: "cancel"` 或 `"okay"}` | 弹窗取消/确定被点击 |
| `lg-linktap` | `{index, href}` | 滚动容器卡片链接被点击 |
| `lg-navigate` | `{dest, name}` | 内部导航（暂未用到） |
| `lg-back` | 无 detail | overlay-buttons 的返回按钮被点 |
**监听示例：**
```js
document.addEventListener('lg-statechange', function(e) {
console.log('toggleOn:', e.detail.toggleOn); // true/false
console.log('sliderValue:', e.detail.sliderValue); // 0-100
console.log('selectedTab:', e.detail.selectedTab); // 0/1/2（第一排，single-bottom-tabs / bottom-tabs 用）
console.log('selectedTab2:', e.detail.selectedTab2);// 0/1/2/3（第二排，bottom-tabs-2 / bottom-tabs 用）
console.log('dark:', e.detail.dark); // true/false
});
document.addEventListener('lg-buttontap', function(e) {
console.log('点击按钮:', e.detail.id);
});
document.addEventListener('lg-dialogtap', function(e) {
console.log('弹窗操作:', e.detail.action); // "cancel" 或 "okay"
});
document.addEventListener('lg-linktap', function(e) {
console.log('链接点击: 第', e.detail.index, '个卡片, href=', e.detail.href);
});
```
---
## 8. 开关 toggle {#toggle}
### 完整可运行示例
保存为 `toggle.html`，双击打开：
```html
开关 toggle
单份透明版（mode=single-toggle）
单份白卡版（mode=toggle-card）
开关状态：-
```
### 每个 mode 解释
| mode | 画什么 | 推荐高度 | 何时用 |
|------|--------|---------|--------|
| `single-toggle` | 1 个透明玻璃开关，折射壁纸 | 200px | 做 iOS 风格设置页开关 |
| `toggle-card` | 1 个白色胶囊卡片里的开关 | 200px | 做 Material Design 风格开关 |
| `toggle` | 上面透明 + 下面白卡，上下排列 | 280px | 对比展示/调试 |
### 状态读取
```js
document.addEventListener('lg-statechange', function(e) {
var isOn = e.detail.toggleOn;
// true = 开关开了, false = 关了
});
```
### 两个开关联动
`toggle`（双份）模式下，两个开关是**联动的**——拖上面，下面的跟着动。它们共享同一个状态 `toggleOn`。
---
## 9. 滑块 slider {#slider}
保存为 `slider.html`：
```html
滑块 slider
单份透明版（mode=single-slider）
单份白卡版（mode=slider-card）
滑块值：-
```
| mode | 推荐高度 |
|------|---------|
| `single-slider` | 200px |
| `slider-card` | 200px |
| `slider`（双份） | 280px |
---
## 10. 底部标签栏 bottom-tabs {#bottom-tabs}
### 完整可运行示例 — 单排 3 tab
保存为 `tabs.html`：
```html
底部标签栏
透明版（3 tab）
白卡风（4 tab）
选中的 tab：-
```
### mode 和 config 对应关系
| mode | 用 config 的哪行 | 典型 tab 数 |
|------|-----------------|------------|
| `single-bottom-tabs` | `config[0]` | 3 |
| `bottom-tabs-2` | `config[1]` | 4 |
| `bottom-tabs` | 两行都用 | 3 + 4 |
### 图标尺寸
每个 tab 的图标渲染在 **24×24 像素**区域内，上方是图标、下方是 12px 文字。图标 SVG path 的坐标范围用 `viewport` 指定——Material Icons 填 `24`。
---
## 11. 按钮组 buttons {#buttons}
保存为 `buttons.html`：
```html
按钮组
4 个按钮一组
点击日志：-
```
### style 预设色
| 名称 | tint 色 | 表面色 | 文字色 |
|------|---------|--------|--------|
| `transparent` | 透明 | 透明 | 黑 |
| `surface` | 透明 | 白 30% | 黑 |
| `blue` | #0088FF | 透明 | 白 |
| `orange` | #FF8D28 | 透明 | 白 |
| `red` | #FF4D4F | 透明 | 白 |
| `green` | #34C74B | 透明 | 白 |
| `purple` | #9C27B0 | 透明 | 白 |
### 自定义颜色
```js
{ id: 'c', label: '自定义', style: [0.2, 0.5, 1, 0.8] }
// R G B A (0-1)
```
### 每个按钮单独 frame
如果你想每个按钮独立放在不同容器里（而不是组件内部自动排列），创建多个 ``：
```html
```
---
## 12. 弹窗 dialog {#dialog}
保存为 `dialog.html`：
```html
弹窗
弹窗示例（点击按钮不关闭）
-
```
**为什么需要 MutationObserver？** 弹窗的取消/确定按钮被点击后，组件**内部硬编码**了关闭行为：`this.setAttribute('mode', prevMode)` 切回进入 dialog 之前的视图。`e.preventDefault()` 对 `CustomEvent` 无效。MutationObserver 在 mode 被改走的瞬间拦截并恢复。
**如果你想要正常的关闭行为**（点了就关），删掉 MutationObserver 那段即可。
---
## 13. 滚动容器 scroll-container {#scroll}
保存为 `scroll.html`：
```html
滚动容器
滚动容器（手指滑动）
-
```
**注意：mode 是 `"scroll-container"`，不是 `"scroll"`。** 写错了会渲染成默认的底部标签栏视图。
---
## 14. 主题 {#theme}
liquid-glass 支持浅色/深色两种主题，通过 `dark` 属性控制。
### 静态设置
```html
```
浅色 = 白底卡片 + 黑色文字。深色 = 黑底卡片 + 白色文字。
**所有组件都受主题影响：** 开关/滑块的白卡底色（白↔黑）、标签栏容器色、按钮组默认背景色、弹窗遮罩色、滚动容器卡片底色，全部跟着 `dark` 走。只有壁纸（透明背景版那部分）不受主题影响——它永远折射壁图片。
### 动态切换（JS）
```html
```
`setAttribute('dark', '')` / `removeAttribute('dark')` 会触发组件内部重绘，无需手动调用任何方法。
### overlay-buttons（内置切换按钮）
```html
```
加上 `overlay-buttons` 属性后，组件右上角会渲染两个 Canvas 内按钮：
| 按钮 | 图标 | 功能 |
|------|------|------|
| 返回 | ← 箭头 | 派发 `lg-back` 事件，组件内部切回上一视图 |
| 主题切换 | 太阳/月亮 | 切换 `dark` 属性的有无（浅↔深） |
两个按钮在 WebGL Canvas 内部渲染（不是 HTML 元素），带玻璃质感和触摸反馈。点击主题切换按钮后，组件自动 `addAttribute`/`removeAttribute('dark')` 并重绘。
**如果只想单独显示主题切换按钮（不要返回按钮）：**
```html
```
`theme-button` 属性只显示主题切换按钮，不影响返回按钮的显示。两个属性可组合：
| 属性 | 返回按钮 | 主题切换 |
|------|---------|---------|
| 都不设 | 隐藏 | 隐藏 |
| `overlay-buttons` | 显示 | 显示 |
| `theme-button` | 隐藏 | 显示 |
| 两个都设 | 显示 | 显示 |
### 读取当前主题状态
```js
var el = document.querySelector('liquid-glass');
console.log('当前主题:', el.hasAttribute('dark') ? '深色' : '浅色');
el.addEventListener('lg-statechange', function(e) {
console.log('主题变为:', e.detail.dark ? '深色' : '浅色');
});
```
### 多组件独立主题
每个 `` 的主题是**独立的**。A 深色不影响 B 浅色：
```html
```
### 主题对壁纸的影响
壁纸图片本身**不变色**——深色模式下壁纸还是那张图。但白卡底色会翻转为黑卡底色，文字颜色也跟着翻转。
---
## 15. 渲染参数调优 {#render}
```html
```
| 参数 | 作用 | 范围 | 默认 |
|------|------|------|------|
| `dpr` | 渲染分辨率上限。`"1"` 强制 1x（可察觉轻微模糊） | ≥0.5 | 屏幕 DPR |
| `corner-style` | `"0"`直角 `"1"`圆角 `"2"`胶囊 | 0/1/2 | `"1"` |
| `blur-tap-cap` | 手指按住时玻璃模糊强度 | 1-33 | 17 |
| `overlay-buttons` | 右上角显示「返回」「主题切换」按钮 | 布尔属性 | 不显示 |
| `theme-button` | 右上角单独显示「主题切换」按钮，不影响返回按钮 | 布尔属性 | 不显示 |
---
## 16. SVG 图标速查表 {#icons}
直接复制粘贴到 `icon` 字段，全部 `viewport: 24`。
| 图标 | 名称 | path |
|------|------|------|
| 🏠 | 首页 | `M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z` |
| 🔍 | 搜索 | `M15.5 14h-.79l-.28-.27a6.5 6.5 0 1 0-.7.7l.27.28v.79l5 4.99L20.49 19zm-6 0A4.5 4.5 0 1 1 14 9.5 4.5 4.5 0 0 1 9.5 14z` |
| ❤️ | 心形 | `M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z` |
| 👤 | 人形 | `M12 12a5 5 0 1 0-5-5 5 5 0 0 0 5 5zm0 2c-3.33 0-10 1.67-10 5v3h20v-3c0-3.33-6.67-5-10-5z` |
| ⭐ | 星星 | `M12 17.27 18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z` |
| ✈️ | 飞行 | `M400 552 L147 653 q-24 10 -45.5 -4.5 T80 608 v-22 q0 -12 5.5 -23 t15.5 -18 l299 -209 v-176 q0 -33 23.5 -56.5 T480 80 q33 0 56.5 23.5 T560 160 v176 l299 209 q10 7 15.5 18 t5.5 23 v22 q0 26 -21.5 40.5 T813 653 L560 552 v144 l103 72 q8 6 12.5 14.5 T680 801 v24 q0 20 -16.5 32.5 T627 864 l-147 -44 l-147 44 q-20 6 -36.5 -6.5 T280 825 v-24 q0 -10 4.5 -18.5 T297 768 l103 -72 v-144 Z` |
**飞行图标 viewport = 960**（默认值即正确，不传 viewport），其余图标 viewport = 24。
### 如何获取更多图标
1. 打开 https://fonts.google.com/icons
2. 选图标 → 点右上角下载 → 选 **SVG**
3. 用文本编辑器打开 `.svg` 文件
4. 找到 `` ，复制引号内的内容
5. 贴到 `icon` 字段，加 `viewport: 24`
---
## 17. 常见报错与排查 {#troubleshooting}
### 1. `WARNING: Too many active WebGL contexts`
**原因：** 浏览器限制 8-16 个 WebGL context。你创建了太多 `` 元素而没销毁旧的。
**解决：** 先 `remove()` 旧元素再创建新的：
```js
// 错：直接 innerHTML = '' → 元素移除但 WebGL context 可能没释放
container.innerHTML = '';
// 对：逐个 remove 触发 disconnectedCallback → dispose
var old = container.querySelectorAll('liquid-glass');
for (var i = 0; i < old.length; i++) old[i].remove();
container.innerHTML = '';
```
### 2. `Uncaught ReferenceError: xxx is not defined`
**原因：** 组件 JS 内部变量作用域 bug（如 `s2TrackW` / `t1TrackY` / `SLIDER_KNOB_HIT_H`）。**当前版本已全部修复。** 如果你还在用旧版 liquid-glass.js，更新到最新。
### 3. `[liquid-glass] wallpaper load failed`
**原因：** 壁纸图片跨域且服务端没返回 `Access-Control-Allow-Origin` 头。
**解决：** 图片放同域，或用 `data:` URL，或服务端加 CORS 头。
### 4. JS API vs HTML 属性
**问题：** 用 `setAttribute('tabs', JSON.stringify(...))` 设 tab 配置，渲染出来还是默认的 "Tab 1/2/3" + 飞机图标。
**原因：** Web Component 生命周期时序。`mode` 的 `attributeChangedCallback` 触发 `_rebuild` 时，`tabs` 属性可能还没解析完，导致 `_tabsConfig` 为 `null`。
**解决：一律用 JS API。** 不要传 HTML 属性 `tabs` / `buttons` / `dialog` / `scroll`。用 `el.setTabs()` / `el.setButtons()` / `el.setDialog()` / `el.setScroll()`。
```js
// 错
el.setAttribute('tabs', JSON.stringify([[...]]));
// 对
requestAnimationFrame(function() {
el.setTabs([[...]]);
});
```
### 5. 图标不显示或极小
**原因：** `viewport` 没传，默认 960，Material Icons 需要 24。
**现象：** 图标存在但肉眼几乎看不见（缩放为 2.5%）。
**解决：** 加 `viewport: 24`。
### 6. 容器不渲染（空白）
**原因：** `` 没有 CSS 宽高。Canvas 尺寸 = CSS 尺寸 × DPR，0 宽高 = 不渲染。
**解决：**
```html
```
### 7. `mode="scroll"` 不渲染滚动容器
**原因：** mode 字符串是 `"scroll-container"`（带连字符），不是 `"scroll"`。
**现象：** 写 `mode="scroll"` → 组件回退到默认 mode `"bottom-tabs"` → 显示 3 个 tab。
**解决：** `mode="scroll-container"`。
---
## 18. 页面架构建议 {#architecture}
### 场景 A：展示页（多个静态组件）
每个组件一个 ``，全写在一个 HTML 里。**限制：总共不超过 6-8 个**（WebGL context 上限）。
```html
```
### 场景 B：SPA / 组件切换（Tab 式）
一个容器，点按钮切换 mode，**每次切换先销毁旧元素**：
```html
```
### 场景 C：壁纸预加载
如果你有一个大壁纸（比如 `data:` URL 约 800KB），想避免每个组件各自加载一次，可以提前存到全局变量：
```html
```
---
> **GooseHyperGlassCDN2.0** · Minecraft_goose 开发 · 2026-07-22
> **基于：** [Kyant0/AndroidLiquidGlass](https://github.com/Kyant0/AndroidLiquidGlass)（Android 原项目）
> **CDN 地址：** `https://glass.goose.cc.cd/liquid-glass.js`
> **文件大小：** ~345KB（gzip ~95KB）
> **浏览器要求：** 支持 WebGL 1.0 + Custom Elements v1 + ES2020（Chrome 80+ / Edge 80+ / Safari 14+ / Firefox 80+）