5分钟给Compose应用加玻璃拟态背景模糊：Haze完整入门指南

5分钟给Compose应用加玻璃拟态背景模糊：Haze完整入门指南

【免费下载链接】hazeBackground blurring for Compose Multiplatform / Jetpack Compose项目地址: https://gitcode.com/gh_mirrors/ha/haze

想让 Compose 应用的导航栏、悬浮卡片拥有那种"磨砂玻璃"质感，手搓 RenderEffect 和离屏画布非常折腾。Haze 正是为此而生的 Compose 背景模糊库：基于hazeSource和hazeBlur两个 Modifier 即可得到硬件加速的模糊、着色与预设材料样式，Android、iOS、桌面和 Web 全平台跑同一套代码。

三步把 Haze 接入 Compose 项目

v2 采用模块化设计：haze提供基础设施，模糊效果放在haze-blur，预设材料样式放在haze-materials。只引入你用得到的模块即可：

dependencies { implementation("dev.chrisbanes.haze:haze:<version>") implementation("dev.chrisbanes.haze:haze-blur:<version>") implementation("dev.chrisbanes.haze:haze-blur-materials:<version>") }

接下来只需认识两个角色：

• hazeSource：把某块内容"登记"为模糊来源，相当于告诉 Haze"从这里取背景"。
• hazeBlur：在另一块内容上消费来源，应用模糊。

两者通过rememberHazeState()返回的HazeState关联。以"背景图上盖一层全模糊"为例：

val hazeState = rememberHazeState() // 模糊状态的桥梁 Box { Image(painter, null, Modifier.hazeSource(hazeState)) // 背景：注册为模糊源 Box( modifier = Modifier.matchParentSize().hazeBlur( input = HazeInput.Sources(hazeState), // 从上面的源取样 style = HazeBlurStyle { blurRadius(20.dp) }, ), ) }

跑起来后，前景 Box 就是标准磨砂玻璃效果。这套"源 + 效果"的写法同样适用于滚动列表下的导航栏：把列表容器标成hazeSource，顶部栏用hazeBlur消费，滚动内容就会自然地从顶栏下方渗上来。

换色与调参：定制 HazeBlurStyle

默认只有模糊，实际设计往往还要底色和色调。HazeBlurStyle是一个 DSL，逐项声明即可：

val cardStyle = HazeBlurStyle { backgroundColor(Color.Black) // 模糊层的底色 colorEffects(listOf(HazeColorEffect.tint(Color.White.copy(alpha = 0.3f)))) // 整体着色 blurRadius(24.dp) // 半径越大，背景细节越糊 }

把cardStyle传给hazeBlur(style = cardStyle)，一张带雾面质感的悬浮卡片就完成了。需要更细的控制（噪声、进度式模糊等），可参考 haze-blur/ 模块源码与 docs/ 下的用法文档。

切换预设材料样式：一键对齐系统风格

如果目标是和原生 UI 保持一致，不必自己调参。haze-blur-materials内置了三套取自系统设计的材料样式，直接作为style使用：

Modifier.hazeBlur( input = HazeInput.Sources(hazeState), style = CupertinoMaterials.thin(), // iOS 风格的半透明材料 )

• Cupertino（ultraThin/thin/regular/thick）：对齐 Apple 平台的透明度梯度，深浅色主题自适应。
• Fluent（acrylicDefault、mica等）：对齐 Windows 的 Acrylic / Mica 材质。

除了模糊，v2 还提供haze-glass模块实现折射感的玻璃效果（类似 macOS 控制中心），感兴趣可以看 haze-glass/ 与截图测试里的信用卡示例。

性能调优：让 Haze 自动缩放输入

全分辨率实时模糊在小屏幕上压力不小。Haze 提供自适应输入缩放：根据渲染节奏把采样分辨率降到合适的档位，再放大显示，模糊质量几乎无感，功耗和帧率显著改善。效果对比可参考 docs/glass/performance.md 与下图：

实践中两条建议：

1. 模糊源尽量小：只把真正需要被模糊的内容标成hazeSource，别把整页都包进去。
2. 动画或滚动密集的场景用默认档位先跑，帧率吃紧时再调低缩放上限。

接下来看哪里

• 官方文档：docs/，覆盖核心概念、迁移与进阶效果
• 可运行示例：sample/，导航栏、卡片、对话框等场景都有对应代码
• 完整 API 演进：haze/api/ 下的历史版本签名文件

上手路径建议：先用"源 + 效果"跑通一个导航栏场景 → 换成CupertinoMaterials或FluentMaterials对齐目标平台风格 → 最后打开输入缩放做性能回归。整个流程基本就是本文 5 分钟内容的复刻。

【免费下载链接】hazeBackground blurring for Compose Multiplatform / Jetpack Compose项目地址: https://gitcode.com/gh_mirrors/ha/haze