Liquid Glass

Liquid Glass 设计系统

🎨 UI & 扩展 · 🏠 首页 › Liquid-Glass

---

📑 本页目录

• 1. 四条设计原则
• 2. 架构
• 3. 七档 GlassStyle
• 4. 组件清单（com.apex.agent.ui.glass）
• 5. 已玻璃化 / 明确不玻璃化
• 6. 性能设计
• 7. 如何验收 / 如何新增玻璃组件
• 8. 相关页面

Selective Liquid Glass UI：普通 Android UI + 精确使用的玻璃组件 + 自然层级 + 轻微动态材质 + 高性能 —— 而不是"整个 App → 透明 → blur → 一坨玻璃"。 组件位于 com.apex.agent.ui.glass，底层唯一依赖 Haze 1.4.0。

1. 四条设计原则

1. 选择性玻璃化 —— 只有适合的交互组件用玻璃：卡片、图标按钮、Drawer 导航项、悬浮件、对话框、 输入容器、小型状态组件。页面背景、大面积内容、终端渲染区一律不玻璃；
2. 诚实材质声明 —— 没有真实 backdrop 采样的地方只称 Frosted；未实现的 Refraction 明确标注 NOT IMPLEMENTED。禁止"alpha + blur + gradient + border"冒充 Liquid Glass；
3. 主题动态派生 —— tint、边缘高光、镜面高光全部从 MaterialTheme 解析， Light / Dark / Dynamic Color 自适应；不存在固定的 white alpha 0.1 万金油材质；
4. 业务层零底层耦合 —— 业务 UI 只用 ui.glass 的组件 API；Haze 调用被封装在 GlassSurface 单点，换底层库不波及业务。

2. 架构

                    业务 UI
                      │
            ┌─────────┴─────────┐
   Backdrop 档组件          Frosted 档组件
  state: HazeState!          state: null
            │                     │
            └──────────┬──────────┘
                  GlassSurface
           激活度动画 / 边缘光 / 高光 / 深度
                       │
                  GlassStyle 七档
                       │
                Haze 1.4.0（唯一底层）
           GraphicsLayer 采样 + RenderEffect
                       │
                   Android GPU

两个材质档

档	条件	能力
Backdrop	state: HazeState 且组件悬浮于 hazeSource 内容之上	真实采样背后 UI；API 32+ GPU RenderEffect 模糊 + tint + noise；API < 32 自动 scrim 降级
Frosted	state = null	主题色薄霜渐变 + 边缘光 + 镜面高光 + 深度。不声明 backdrop

Note

为什么列表内的卡片是 Frosted：Haze 1.4.0 不支持 hazeEffect 嵌套在 hazeSource 子树内 （该修复在 1.5.0 才引入）；且为每张卡片单独建源违反性能规范（禁止每卡 full-screen capture）。 因此聊天消息列表内的工具卡 / 计划卡诚实降级为 Frosted 档，而不是假装自己在采样背后内容。

3. 七档 GlassStyle

档	blur	tint	边缘	用途
Subtle	8dp	0.42	0.08	小型状态组件
Control	10dp	0.50	0.16	图标按钮 / 输入容器
Card	14dp	0.58	0.18	工具卡 / 状态卡
Navigation	12dp	0.46	0.13	Drawer 导航项（常态必须"非常轻"）
Floating	18dp	0.62	0.24	FAB / 悬浮输入栏
Dialog	22dp	0.66	0.24	对话框面板
Strong	26dp	0.74	0.28	特殊高聚焦场景

4. 组件清单（com.apex.agent.ui.glass）

组件	说明
GlassSurface	渲染核心：材质层 + 激活度动画 + 边缘光 + 高光 + 深度
GlassCard / GlassToolCard / GlassBadge	卡片族（ToolCard 带状态着色）
GlassIconButton / GlassButton	40dp 高圆角轻玻璃 / 胶囊按钮
GlassFloatingButton	48dp，比卡片更强的边缘与高光
GlassNavigationItem	Normal 轻量 / Selected 提亮 / Pressed 短暂高光 / Disabled 降权
GlassDialog	state 非 null 时经 HazeDialog 跨窗口采样 Activity 内容

交互状态机：

Normal 0 / Focused 0.35 / Selected 0.55 / Pressed 1  → 140ms 单向激活动画（非循环）
影响：高光亮度 · 边缘强度 · 按压缩放 · 选中浸染

5. 已玻璃化 / 明确不玻璃化

组件	档	Backdrop 源
Drawer 导航项 ×9	Backdrop	抽屉氛围背景（渐变 + 双光晕 + 细网格）
聊天悬浮输入栏	Backdrop	消息 LazyColumn
回到底部 FAB	Backdrop	消息 LazyColumn
顶栏菜单钮	Frosted	——（顶栏无重叠内容，诚实降级）
工具卡 / 运行中工具卡	Frosted	——（源内嵌套不可用）
Plan / Spec / 确认卡	Frosted	——（同上）
任务状态卡	Frosted	——（直排区无重叠）
玻璃实验室验证屏	Backdrop	验证区 Canvas（网格 + 文字 + 漂移光斑）

明确不玻璃化：终端渲染区（TerminalRenderer 保持纯色 + 高对比 + 低延迟）、 页面背景、聊天气泡正文、ContextMeterBar。

Caution

Refraction（折射位移）标注为 NOT IMPLEMENTED。 在真实现之前，任何"看起来像折射"的实现都会被 review 挡下 —— 项目拒绝假装拥有一枚没实现的特性。

6. 性能设计

• 每个 haze 源仅一次 GraphicsLayer 记录（单共享源层），无逐帧 Bitmap 分配；
• 模糊经 GPU RenderEffect；API < 32 设备走 scrim 降级，不做软件模糊；
• 玻璃叠加层（边缘 / 高光 / 深度）全部为单次 drawBehind 绘制，零额外图层；
• 激活动画 140ms tween 单向；除玻璃实验室验证屏（验证实时采样所必需的漂移光斑）外， 业务界面无循环动画。

7. 如何验收 / 如何新增玻璃组件

• 用抽屉里的 玻璃实验室 屏真机验证：backdrop 采样、模糊、边缘光、按压缩放、跨主题/跨 dark mode；
• 新增组件：查表选玻璃材质档 → 包 GlassSurface 暴露语义 API → 不要自己调 Haze；
• 逐条对照玻璃实验室页里的"诚实验收清单"打勾（尤其"是否真的采样了背后内容"这一条）。

8. 相关页面

• 界面导航地图 —— 玻璃组件都在哪些屏
• Module Map —— ui/glass 在 :app 里的位置
• PERF 笔记 —— 性能相关深入文档

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}