liquid-glass

Liquid Glass

概述

使用此技能，尽可能少地添加自定义装饰，让 macOS SwiftUI 应用采用现代 macOS 设计系统。先从标准应用结构、工具栏、搜索位置、工作表和控件入手，然后仅在应用需要独特表面效果时添加自定义 Liquid Glass。

优先使用系统提供的玻璃效果和自适应材质，而不是定制模糊效果、不透明背景或自定义工具栏／侧边栏外观。在添加更多效果前，先检查现有 UI 中是否有多余的填充、遮罩和裁剪。

工作流

1. 阅读相关场景或根视图，并识别其结构模式： NavigationSplitView、TabView、工作表呈现、详情／检查器布局、工具栏或自定义浮动控件。
2. 移除系统工作表、侧边栏和工具栏背后的自定义背景或暗化图层，除非产品明确需要它们。这些效果可能遮挡 Liquid Glass，并干扰自动滚动边缘效果。
3. 先更新标准 SwiftUI 结构和控件。
4. 仅在标准控件无法满足应用专属 UI 的需求时，才添加自定义 glassEffect 表面。
5. 检查玻璃分组、转场、图标处理和前景激活状态在视觉上是否协调，并确认鼠标和键盘仍可正常使用。
6. 如果 UI 更改也会影响 SwiftPM GUI 应用的启动行为，请使用 build-run-debug，让应用以 .app 前台应用包的形式运行，而不是作为原始可执行文件运行。

应用结构

• 对于由层级驱动的 macOS 布局，优先使用 NavigationSplitView。让侧边栏使用系统 Liquid Glass 材质，而不是在其上绘制效果。
• 对于紧邻浮动侧边栏的主视觉图稿或大型媒体，使用 backgroundExtensionEffect，让视觉内容能够延伸到安全区域之外，同时避免裁剪主体。
• 让检查器在视觉上与当前选中项相关联，避免为检查器添加比其所检查内容更厚重的自定义背景。
• 如果应用使用标签页，请将 TabView 用于持久的顶层分区，并保留每个标签页各自的导航状态。
• 不要将仅适用于 iPhone 的标签栏最小化／配件行为强加给 Mac 应用。在 macOS 上，优先使用常规顶部工具栏和原生的标签页／搜索位置。
• 如果工作表使用 presentationBackground 只是为了模拟磨砂材质，可以考虑移除它，让系统的新材质自行呈现。
• 对于应在视觉上从工具栏按钮发起的工作表转场，请将发起呈现的项目设为导航缩放转场的来源，并将工作表内容标记为目标。

工具栏

• 默认工具栏项目会显示在浮动的 Liquid Glass 表面上，并自动分组。
• 使用 ToolbarSpacer 表达分组关系：
  • 使用固定间距，将相关操作分隔为不同组。
  • 使用灵活间距，将前导操作与尾随组推开。
• 当某个项目应独立显示且不带共享玻璃背景时（例如个人资料／头像项目），使用 sharedBackgroundVisibility。
• 在工具栏项目内容中添加 badge，用于通知或状态指示。
• 预计更多工具栏场景会采用单色图标渲染。仅在表达语义（例如主要操作或警告状态）时使用 tint，不要纯粹将其用作装饰。
• 如果工具栏下方的内容带有额外的暗化、模糊或自定义背景图层，请先移除它们，再评估新的自动滚动边缘效果。
• 对于包含许多浮动元素的密集窗口，请使用 scrollEdgeEffectStyle 调整内容的滚动边缘效果，而不是构建自定义栏背景。

搜索

• 对于适用于整个分栏视图层级的搜索字段，请将 searchable 附加到 NavigationSplitView，而不是只附加到某一列。
• 如果搜索是次要功能，且更适合使用紧凑的入口，请使用 searchToolbarBehavior，而不是手动制作工具栏按钮和单独的字段。
• 对于多标签页应用中的专用搜索页面，请将搜索角色分配给一个 标签页，并将 searchable 放在 TabView 上。
• 当搜索字段位于工具栏右上角时，应确保大多数应用内容都能通过搜索找到。
• 在 iPad 和 Mac 上，专用搜索标签页通常会在浏览建议上方显示居中的字段，而不是底部搜索栏。

控件

• 优先使用标准 SwiftUI 控件，而不是创建自定义玻璃组件。
• 预期描边按钮在较大尺寸下默认使用胶囊形状。在 macOS 上，mini、small 和 medium 控件会保留圆角矩形形状，以适应更紧凑的布局。
• 当按钮形状需要明确指定时，使用 buttonBorderShape。
• 在检查器和弹出窗口中使用 controlSize 保持紧凑，只有对真正醒目的操作才使用超大尺寸。
• 对于主要操作，请使用系统的玻璃和突出玻璃按钮样式，而不是手动重新创建半透明按钮背景。
• 对于具有离散值的滑块，传入 step 以自动显示刻度，或在 ticks 闭包中指定刻度。
• 对于应围绕基线向左右扩展的滑块，请设置 neutralValue。
• 对于菜单项，使用 Label 或标准控件初始化器，以便图标在各个平台上始终位于前导侧。
• 对于必须与工作表、卡片或窗口边角同心对齐的自定义形状，请使用带有 containerConcentric 圆角配置的同心矩形形状，而不是猜测圆角半径。

自定义 Liquid Glass

• 对于自定义玻璃表面，请使用 glassEffect。默认形状类似胶囊，文本前景色会自动变得鲜明易读，以适应下方不断变化的内容。
• 当胶囊形状不合适时，请为 glassEffect 传入明确的形状。
• 仅在颜色具有实际含义时（例如表示状态或号召性操作）添加 tint。
• 对于带有交互元素的自定义控件或容器，请使用 glassEffect(... .interactive())，使其像系统玻璃一样缩放、弹跳并闪烁。
• 将相邻的自定义玻璃元素放在同一个 GlassEffectContainer 中。这是视觉正确性的要求，不只是为了整理代码：不同容器无法采样彼此的玻璃，可能导致折射效果不一致。
• 当匹配的玻璃元素需要在收起和展开状态之间变形时，请将 glassEffectID 与本地 @Namespace 配合使用。

审查清单

• 先更新标准结构和控件，再添加自定义玻璃效果。
• 除非确有需要，否则移除与系统材质冲突的不透明背景、深色遮罩以及自定义工具栏或工作表填充。
• 根据预期的搜索范围，将 searchable 附加到正确的容器层级。
• 工具栏分组使用 ToolbarSpacer、sharedBackgroundVisibility 和 badge，而不是一次性手动构建界面装饰。
• 图标着色应具有语义，而非仅作装饰。
• 彼此相邻的自定义玻璃元素应共用一个 GlassEffectContainer。
• 玻璃变形过渡应将 glassEffectID 与命名空间及稳定标识配合使用。
• 用于测试结果的任何 SwiftPM GUI 应用都应作为 .app 捆绑包启动，而不是作为原始可执行文件启动。

使用准则

• 如果标准 SwiftUI API 已能提供现代 macOS 行为，就不要从头重建系统侧边栏、工具栏、工作表或控件。
• 不要仅仅因为旧版本需要，就在 NavigationSplitView 侧边栏、系统工具栏或工作表后应用自定义不透明背景。
• 不要将相关的玻璃元素分散到多个 GlassEffectContainer 中。
• 不要仅为增加视觉变化就给每个图标或玻璃表面着色。
• 不要认为 iPhone 的标签页／搜索行为也适用于 macOS。优先采用原生桌面工具栏、分栏视图和检查器布局。
• 检查 Liquid Glass 行为时，不要让 GUI SwiftPM 应用以裸可执行文件的形式启动；缺少前台激活可能会让设计问题看起来像渲染问题。

何时使用其他技能

• 如果主要问题是场景架构、侧边栏／详情布局、命令或设置，而非 Liquid Glass 专属处理，请使用 swiftui-patterns。
• 如果主要问题是文件结构、状态所有权，以及在设计变更前拆分大型视图，请使用 view-refactor。
• 如果设计需要窗口、面板、响应者链或仅限 AppKit 的控件行为，请使用 appkit-interop。
• 如果需要在视觉更新后启动、验证应用或检查其日志，请使用 build-run-debug。