liquid-glass

面向 Apple 平台的 Liquid Glass 设计系统

使用 Apple 在 WWDC 2025 上推出的 Liquid Glass 设计语言构建和迁移 SwiftUI 应用。此技能涵盖 iOS 26、iPadOS 26、macOS 26（Tahoe）、watchOS 26、tvOS 26 和 visionOS 26。

重要：使用最新文档

实现 Liquid Glass 功能时，务必获取最新的 Apple 开发者文档。各个操作系统测试版之间的 API 可能会发生变化。请参考以下关键文档网址：

• https://developer.apple.com/documentation/SwiftUI/Applying-Liquid-Glass-to-custom-views
• https://developer.apple.com/documentation/swiftui/view/glasseffect(_:in:)
• https://developer.apple.com/documentation/SwiftUI/Landmarks-Building-an-app-with-Liquid-Glass
• https://developer.apple.com/videos/play/wwdc2025/323/（WWDC25 会议：使用新的设计构建 SwiftUI 应用）

核心概念

Liquid Glass 是一种半透明的动态材质，专用于导航层（工具栏、标签栏、按钮、控件），浮于应用内容之上。它会实时弯曲和折射光线，通过镜面高光响应设备运动，并持续适应背景内容。

切勿将玻璃效果应用于内容本身（列表、表格、媒体、文本块）。玻璃效果仅用于控件和导航。

快速入门：关键 API

1. 自定义视图的玻璃效果

// Basic - capsule shape (default)
Text("Label")
    .padding()
    .glassEffect()

// With shape and style
Image(systemName: "heart.fill")
    .padding()
    .glassEffect(.regular, in: .rect(cornerRadius: 16))

// Tinted glass
Text("Tinted")
    .padding()
    .glassEffect(.regular.tint(.blue))

// Interactive glass (scales, bounces, shimmers on touch - iOS only)
Button("Tap Me") { }
    .glassEffect(.regular.interactive())

2. 玻璃样式

样式	使用场景	透明度
.regular	标准 UI：工具栏、按钮、导航栏	中
.clear	内容色彩鲜明或明亮的多媒体背景	高
.identity	有条件地停用玻璃效果（辅助功能）	无

3. GlassEffectContainer（关键）

玻璃无法采样其他玻璃。附近的玻璃元素必须共用一个容器，以确保视觉一致并实现形变效果。

GlassEffectContainer(spacing: 30.0) {
    Button("Action 1") { }
        .glassEffect()
        .glassEffectID("btn1", in: namespace)

    Button("Action 2") { }
        .glassEffect()
        .glassEffectID("btn2", in: namespace)
}

4. 形变过渡

在 GlassEffectContainer 内使用 @Namespace 和 glassEffectID，实现流畅的玻璃形变：

@Namespace private var namespace
@State private var isExpanded = false

GlassEffectContainer(spacing: 16) {
    if isExpanded {
        ForEach(items) { item in
            ItemView(item: item)
                .glassEffect(.regular, in: .rect(cornerRadius: 24))
                .glassEffectID(item.id, in: namespace)
        }
    }
    Button {
        withAnimation { isExpanded.toggle() }
    } label: { Label("Toggle", systemImage: "chevron.down") }
    .buttonStyle(.glass)
    .glassEffectID("toggle", in: namespace)
}

5. 背景延伸效果

延伸并模糊导航元素（工具栏、侧边栏、检查器）后方的视觉内容：

Image(landmark.backgroundImageName)
    .resizable()
    .aspectRatio(contentMode: .fill)
    .frame(minWidth: 0, maxWidth: .infinity, minHeight: 0, maxHeight: .infinity)
    .backgroundExtensionEffect()

6. 玻璃按钮

// Standard glass button
Button("Action") { }
    .buttonStyle(.glass)

// Prominent glass button (for primary actions)
Button("Save") { }
    .buttonStyle(.glassProminent)

7. 带玻璃效果的工具栏

工具栏项会自动应用玻璃样式。使用 ToolbarSpacer 和 ToolbarItemGroup 进行布局：

.toolbar {
    ToolbarSpacer(.flexible)
    ToolbarItem { ShareLink(item: data, preview: preview) }
    ToolbarSpacer(.fixed)
    ToolbarItemGroup {
        Button("Favorite", systemImage: "heart") { }
        Button("Add", systemImage: "plus") { }
    }
    ToolbarItem {
        Button("Info", systemImage: "info") { }
    }
}
.toolbar(removing: .title) // Remove title for clean glass toolbar

8. 标签栏

使用 Xcode 26 编译时，标签栏会自动采用玻璃效果：

TabView {
    Tab("Home", systemImage: "house") { HomeView() }
    Tab("Search", systemImage: "magnifyingglass") { SearchView() }
}
.tabBarMinimizeBehavior(.onScrollDown) // Collapse tab bar on scroll

9. 带玻璃效果的工作表

部分高度的工作表会自动采用 Liquid Glass 背景：

.sheet(isPresented: $showSheet) {
    SheetContent()
        .presentationDetents([.medium, .large])
    // Do NOT add .presentationBackground() - system handles it
}

迁移工作流（现有应用）

详细迁移步骤请参阅迁移指南。

摘要：

1. 使用 Xcode 26 SDK 编译——系统组件会自动采用玻璃效果
2. 移除自定义工具栏背景（.toolbarBackground）
3. 将导航元素上的自定义材质替换为玻璃效果修饰符
4. 将成组的玻璃元素放入 GlassEffectContainer
5. 为主视觉图片添加 .backgroundExtensionEffect()
6. 更新 SF Symbol 变体（在 iOS 26+ 中，将 circle 变体替换为 none 变体）
7. 测试辅助功能（降低透明度、增强对比度、减少动态效果）

平台注意事项

平台特定的详细信息请参阅平台特定说明。

主要差异：

• macOS：在玻璃按钮上使用 .tint(.clear) 以确保正确渲染；编辑背景时使用 WindowBackgroundShapeStyle.windowBackground，而不是 Material
• iOS（iPhone）：可使用 .interactive()；使用 UIDevice.current.userInterfaceIdiom 进行布局
• iPadOS：网格尺寸更大；侧边栏可适配标签视图
• 条件编译：使用 #if os(macOS) / #if os(iOS) 编写平台特定代码

常见陷阱

如需了解详细的陷阱和解决方案，请参阅 references/pitfalls-and-solutions.md。

关键问题：

• GlassEffectContainer 外的玻璃元素会导致视觉效果不一致
• 对玻璃视图使用 rotationEffect 会导致形状变形——使用 UIGlassEffect 接入 UIKit
• 带玻璃效果的菜单标签会产生动画瑕疵——使用自定义 ButtonStyle
• 命中测试只会在内容上注册，而不会在玻璃区域注册——使用 contentShape() 修复
• 多个玻璃效果会产生多个 CABackdropLayer 实例（每个实例有 3 个离屏纹理）——使用容器进行分组

真实示例模式

如需查看 Apple Landmarks 示例应用中的完整代码模式，请参阅 examples/landmarks-patterns.md。

架构最佳实践

1. 使用 NavigationSplitView 作为带玻璃侧边栏的应用根视图
2. 使用 NavigationStack 在详情列中进行深层导航
3. 使用带 @Environment 注入的 @Observable 数据模型
4. 使用 FlexibleHeader 模式：配合滚动联动视差效果的可伸展主视觉图片
5. 使用 .inspector() 显示补充详情面板
6. 使用 .searchable() 实现全局搜索（自动应用玻璃样式）
7. 使用 ToolbarSpacer(.flexible) 和 ToolbarSpacer(.fixed) 布局工具栏
8. 优先在工具栏中使用带文本标签的基于符号的按钮
9. 使用 .symbolVariant() 修饰符更改 SF Symbol 状态
10. 使用 .symbolEffect(.drawOn) 实现图标动画过渡