Peekaboo 实战:SwiftUI Liquid Glass 液态玻璃效果完整实现指南

原创2026-10-12 20:25:361,871 阅读
文章标签:GUI 自动化桌面应用CLIMCP 服务屏幕录制AI Agent本地部署

Peekaboo 实战:SwiftUI Liquid Glass 液态玻璃效果完整实现指南

Liquid Glass 是 Apple 在 macOS 26 / iOS 26 及更高版本中引入的动态材质系统,它将玻璃的光学特性与流体感结合:模糊背景内容、反射周边色彩与光线,并对触摸与指针交互做出实时响应。本篇指南以 Peekaboo 开源仓库为参照,系统讲解在 SwiftUI 中实现与定制 Liquid Glass 效果的全部要点——从最基础的 glassEffect() 修饰符,到多玻璃效果的合并、形态变换(morphing)动效、玻璃按钮样式,以及围绕系统版本差异的适配与回退方案。读完本文,你将能够为自定义视图、按钮、徽章乃至整个容器体系落地一套完整且可降级运行的液态玻璃 UI。

概述:什么是 Liquid Glass

Liquid Glass 是一种在 iOS 与 macOS 新版本中引入的动态材质,结合了玻璃的光学特性与流体的动感。它的核心特征包括:

  • 模糊材质背后的内容(blur)
  • 反射周围内容的色彩与光线
  • 对触摸与指针交互做出实时反应
  • 在视图切换期间支持形状之间的形态变换(morph)
  • 同时适用于标准组件与自定义组件

从视觉上理解,Liquid Glass 并不仅仅是"一层毛玻璃"——它更像一块会呼吸的实体玻璃:当内容在它背后移动时,光线与颜色会折射进材质表面;当指针靠近时,它会产生微妙的隆起与色彩变化。在 Peekaboo 中,这一材质被用于空状态(Empty State)的主视觉幽灵形象、会话页面的主要操作按钮等处,让界面在现代化观感与系统原生一致性之间取得平衡。

需要特别说明的是,Liquid Glass 属于系统级新能力,并非所有版本都能直接使用。Peekaboo 的 Mac 应用目标平台最低为 macOS 14(见 Apps/Mac/Package.swift),因此项目在引入玻璃效果时,始终配套了针对旧系统的材质回退方案(详见下文"系统版本适配"一节)。

基础实现

为视图添加 Liquid Glass

为视图添加 Liquid Glass 最简单的方式是使用 glassEffect() 修饰符:

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect()

默认情况下,该修饰符会在视图内容背后以 Capsule(胶囊)形状应用常规变体的玻璃效果。

glassEffect 修饰符的完整签名还包括 isEnabled 参数,可在需要时以声明式方式动态开关玻璃效果(例如根据用户设置或视图状态决定是否启用):

.glassEffect(.regular, in: .capsule, isEnabled: isGlassEnabled)

自定义形状

你可以为 Liquid Glass 效果指定不同的形状。系统提供三种常用形状选项:

  • .capsule(默认)
  • .rect(cornerRadius: CGFloat)
  • .circle
Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(in: .rect(cornerRadius: 16.0))

值得注意的是,in: 参数接受任意符合 Shape 协议的类型,而不仅是上述系统形状。Peekaboo 项目中就使用了自定义 Shape 来实现独特的玻璃外形:AnimatedGhostView 把自定义的 GhostShape(一个带有三褶波浪下摆的幽灵剪影)直接传入 glassEffect,让液态玻璃沿着不规则轮廓流动。完整实现见 Apps/Mac/Peekaboo/Features/StatusBar/GhostImageView.swift:

@ViewBuilder
private var ghostBody: some View {
    if #available(macOS 26.0, *) {
        GhostEyesView(glance: self.glance)
            .foregroundStyle(.primary.opacity(0.70))
            .glassEffect(.regular.tint(.white.opacity(0.25)).interactive(), in: GhostShape())
    } else {
        // macOS 14-25 的材质回退实现
        ZStack {
            GhostShape()
                .fill(.ultraThinMaterial)
            GhostShape()
                .fill(LinearGradient(
                    colors: [.white.opacity(0.45), .white.opacity(0.12)],
                    startPoint: .top,
                    endPoint: .bottom))
            GhostEyesView(glance: self.glance)
                .foregroundStyle(.primary.opacity(0.70))
        }
    }
}

这段代码同时演示了两个关键实践:其一,自定义 Shape 可以直接作为玻璃容器形状,让液态玻璃适配品牌化的不规则外形;其二,通过 #available(macOS 26.0, *) 进行版本分派,在旧系统上退化为 ultraThinMaterial 材质叠加线性渐变的近似外观,保证空状态主视觉在所有受支持系统上都能呈现。

定制 Liquid Glass 效果

玻璃变体与属性

Liquid Glass 效果通过配置 Glass 结构体进行定制。Glass 采用链式 API,可将变体、着色与交互能力组合使用:

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(.regular.tint(.orange).interactive())

关键定制选项:

  • .regular —— 标准玻璃效果
  • .tint(Color) —— 为玻璃添加颜色着色,用于暗示重要性或状态
  • .interactive(Bool) —— 让玻璃对触摸与指针交互做出反应

tint 的取值直接影响视觉效果:着色越浓,玻璃越显"存在感"。Peekaboo 的幽灵形象使用的是非常克制的 tint(.white.opacity(0.25))——半透明白色着色既让幽灵在深色背景下保持轮廓清晰,又不会喧宾夺主地破坏背后的折射内容。在需要强调交互性的场景(如主操作按钮、可点击卡片),则应叠加 .interactive()。

制作可交互的玻璃

要让 Liquid Glass 对触摸与指针交互产生反应,在 .regular 变体上追加 .interactive(true):

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(.regular.interactive(true))

更简洁的写法是直接调用无参形式(等价于 interactive(true)):

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect(.regular.interactive())

交互式玻璃在指针靠近、按下时会产生实时的高光、凹陷与色彩反馈。这也解释了为什么 Peekaboo 的幽灵空状态要使用 .interactive()——用户操作界面时指针扫过幽灵,玻璃材质会像真实物体一样作出反应,强化"可触摸的液态玻璃"这一设计语言。

处理多个玻璃效果

使用 GlassEffectContainer

当多个视图同时应用 Liquid Glass 时,应使用 GlassEffectContainer 包裹它们。这样做有两个直接收益:一是显著提升渲染性能(玻璃效果会被合并到更少的渲染通道中),二是让相邻玻璃之间能够产生自然的融合(blending)与形态变换(morphing)效果:

GlassEffectContainer(spacing: 40.0) {
    HStack(spacing: 40.0) {
        Image(systemName: "scribble.variable")
            .frame(width: 80.0, height: 80.0)
            .font(.system(size: 36))
            .glassEffect()

        Image(systemName: "eraser.fill")
            .frame(width: 80.0, height: 80.0)
            .font(.system(size: 36))
            .glassEffect()
    }
}

spacing 参数控制玻璃效果之间的相互作用方式:

  • 较小的 spacing:视图需要靠得更近才能让效果合并
  • 较大的 spacing:效果在更远的距离上即可合并

理解这个参数的关键在于:spacing 定义了"玻璃开始彼此感应并融合"的阈值距离,而非简单的布局间距。合理设置它,可以让多个玻璃元素在视觉上呈现"一块完整玻璃被分成几格"的效果,而非"几块各自独立的玻璃"。

合并多个玻璃效果

当多个视图需要被合并为单一的 Liquid Glass 效果时(例如动态创建视图,或视图位于 HStack / VStack 之外的场景),使用 glassEffectUnion 修饰符为每个效果指定分组标识:

@Namespace private var namespace

// Later in your view:
GlassEffectContainer(spacing: 20.0) {
    HStack(spacing: 20.0) {
        ForEach(symbolSet.indices, id: \.self) { item in
            Image(systemName: symbolSet[item])
                .frame(width: 80.0, height: 80.0)
                .font(.system(size: 36))
                .glassEffect()
                .glassEffectUnion(id: item < 2 ? "1" : "2", namespace: namespace)
        }
    }
}

上述代码中,前两个符号被归入分组 "1",其余符号归入分组 "2",从而形成两块独立的玻璃"群岛"。这在创建动态视图、或视图结构无法被单一容器统一包裹时尤为有用——glassEffectUnion 让跨布局的玻璃元素也能在指定的 Namespace 下协同融合。

形态变换(Morphing)与转场

创建 Morphing 转场

Liquid Glass 最引人注目的能力之一,是视图层级变化时玻璃形状的平滑形态变换。实现步骤如下:

  1. 使用 @Namespace 属性包装器创建一个命名空间
  2. 用 glassEffectID 为每个 Liquid Glass 效果关联一个唯一标识
  3. 在变更视图层级时使用动画
@State private var isExpanded: Bool = false
@Namespace private var namespace

var body: some View {
    GlassEffectContainer(spacing: 40.0) {
        HStack(spacing: 40.0) {
            Image(systemName: "scribble.variable")
                .frame(width: 80.0, height: 80.0)
                .font(.system(size: 36))
                .glassEffect()
                .glassEffectID("pencil", in: namespace)

            if isExpanded {
                Image(systemName: "eraser.fill")
                    .frame(width: 80.0, height: 80.0)
                    .font(.system(size: 36))
                    .glassEffect()
                    .glassEffectID("eraser", in: namespace)
            }
        }
    }

    Button("Toggle") {
        withAnimation {
            isExpanded.toggle()
        }
    }
    .buttonStyle(.glass)
}

当带有 Liquid Glass 的视图因视图层级变化而出现或消失时,morphing 效果便会发生:新玻璃从既有玻璃的轮廓中"生长"出来,或旧玻璃"收缩"融入新玻璃,而非生硬的闪现。这里的三个要素缺一不可——@Namespace 提供共享的标识空间,glassEffectID 让系统将前后两帧的玻璃识别为同一实体,withAnimation 则驱动系统在两者之间插值出形态变换的中间帧。

需要留意的是,morphing 依赖视图层级的变化(插入/移除)来触发;如果你只是改变单个玻璃的形状参数,则应依赖玻璃自身的动画能力而非 morphing 机制。

使用 Liquid Glass 的按钮样式

SwiftUI 为 Liquid Glass 提供了两种内建按钮样式。

Glass 按钮样式

Button("Click Me") {
    // Action
}
.buttonStyle(.glass)

.glass 样式适用于常规操作按钮,其外观与普通玻璃容器保持一致。

Glass Prominent 按钮样式

对于需要强调的重要操作,使用 .glassProminent:

Button("Important Action") {
    // Action
}
.buttonStyle(.glassProminent)

Prominent 变体拥有更高的视觉权重,适合作为界面中的主行动点(primary action)。

Peekaboo 在会话空状态页面的"New Session"按钮上就使用了这一样式,并且同样配套了版本回退——在 macOS 26 及以上使用 .glassProminent,旧系统则回退到 .borderedProminent:

@ViewBuilder
private var newSessionButton: some View {
    let button = Button {
        _ = self.sessionStore.createSession(title: "New Session")
    } label: {
        Label("New Session", systemImage: "plus")
            .padding(.horizontal, 6)
            .padding(.vertical, 2)
    }
    .controlSize(.large)

    if #available(macOS 26.0, *) {
        button.buttonStyle(.glassProminent)
    } else {
        button.buttonStyle(.borderedProminent)
    }
}

完整上下文见 Apps/Mac/Peekaboo/Features/Main/SessionChatView.swift。这种"新系统用玻璃、旧系统用等价系统样式"的双轨写法,值得作为整个应用层面的统一模式。

高级技巧

背景延伸效果(Background Extension)

为了让内容延伸到侧边栏或检查器(inspector)后方,形成"内容穿透玻璃侧栏"的沉浸式观感,可以使用背景延伸:

NavigationSplitView {
    // Sidebar content
} detail: {
    // Detail content
        .background {
            // Background content that extends under the sidebar
        }
}

配合 Liquid Glass 材质,延伸至侧边栏下方的背景会在玻璃下方形成可折射的内容层——这正是玻璃"有内容可反射"的前提。Peekaboo 的空状态页面也遵循了同样的设计原则:它在幽灵背后放置了一枚柔和的径向渐变光斑(RadialGradient),注释中明确写道"玻璃需要折射的东西"("gives the glass something to refract"),见 Apps/Mac/Peekaboo/Features/Main/SessionChatView.swift:

.background {
    // Soft accent glow behind the ghost gives the glass something to refract.
    RadialGradient(
        colors: [Color.accentColor.opacity(self.colorScheme == .dark ? 0.16 : 0.10), .clear],
        center: UnitPoint(x: 0.5, y: 0.35),
        startRadius: 20,
        endRadius: 340)
        .ignoresSafeArea()
}

这是一个值得记住的实战细节:液态玻璃的观感高度依赖其背后的内容。没有背后内容的玻璃只是一层灰色贴片;而在背后放置色彩渐变、图片或滚动内容,玻璃的折射、反射特性才能真正显现。

让横向滚动延伸到侧边栏下方

若希望横向滚动视图在侧边栏或检查器下方继续滚动,使用 scrollExtensionMode:

ScrollView(.horizontal) {
    // Scrollable content
}
.scrollExtensionMode(.underSidebar)

underSidebar 模式让滚动内容"钻入"侧边栏底部继续延伸,配合玻璃侧栏的模糊效果,能够营造出内容在玻璃后方流动的层次感。

最佳实践

综合原文档要点与 Peekaboo 项目的实际经验,应用 Liquid Glass 时应遵循以下原则:

  1. 善用容器(Container Usage):对多个视图应用 Liquid Glass 时,务必使用 GlassEffectContainer,以获得更好的渲染性能与形态变换支持。

  2. 注意修饰符顺序(Effect Order):.glassEffect() 应放在其他影响视图外观的修饰符之后。因为玻璃材质作用于视图内容之上,先完成布局与内容修饰,再套上玻璃,才能保证玻璃正确包裹最终呈现的外观。

  3. 精心选择间距(Spacing Consideration):仔细调节容器中的 spacing 值,控制玻璃效果何时、以何种距离合并。间距既是视觉间距也是"融合阈值"。

  4. 配合动画(Animation):变更视图层级时使用动画(如 withAnimation),才能触发平滑的 morphing 转场。

  5. 按需交互(Interactivity):只为需要响应用户交互的玻璃追加 .interactive()。交互式玻璃开销更高,不应盲目全局开启。

  6. 保持设计一致性(Consistent Design):在应用内维持统一的形状与样式,形成连贯的视觉语言。例如 Peekaboo 在幽灵空状态与主按钮上同时使用玻璃材质,但风格克制统一。

  7. 做好版本回退(版本适配):Liquid Glass 仅存在于新系统。若应用的目标平台包含旧系统,必须为 macOS 26 以下版本提供等价回退——Peekaboo 提供了两种可复用的模式:视图级回退(#available 分支切换材质)与组件级回退(ModernEffectView 统一封装)。

系统版本适配:Peekaboo 的现代化效果封装

为了让项目在 macOS 14 到 26+ 全范围内呈现"原生且一致"的视觉效果,Peekaboo 在 Apps/Mac/Peekaboo/Core/ModernEffects.swift 中封装了 ModernEffectView:当运行在 macOS 26+ 时,它通过 NSGlassEffectView 呈现真正的 Liquid Glass;在 macOS 14-25 上则使用系统原生 Material 近似替代。其核心结构如下:

var body: some View {
    if #available(macOS 26.0, *) {
        // Use new Liquid Glass on macOS 26+
        NativeGlassWrapper(
            style: self.style,
            cornerRadius: self.cornerRadius,
            content: self.content)
    } else {
        // Use standard macOS materials for 14-25
        self.content
            .background {
                RoundedRectangle(cornerRadius: self.cornerRadius)
                    .fill(self.style.nativeMaterial)
            }
            .clipShape(RoundedRectangle(cornerRadius: self.cornerRadius))
    }
}

NativeGlassWrapper 通过 NSViewRepresentable 将 NSGlassEffectView 桥接进 SwiftUI,并同步设置 cornerRadius 与 style:

func makeNSView(context: Context) -> NSGlassEffectView {
    let glassView = NSGlassEffectView()
    glassView.cornerRadius = self.cornerRadius
    glassView.style = self.style.glassStyle

    let hostingView = makeHostedContentView(content, identifier: nativeGlassHostingViewIdentifier)

    if let contentView = glassView.contentView {
        contentView.addSubview(hostingView)
        pinHostedContentView(hostingView, to: contentView)
    } else {
        glassView.addSubview(hostingView)
        pinHostedContentView(hostingView, to: glassView)
    }

    return glassView
}

与此同时,ModernEffectStyle 枚举为不同界面角色映射了合适的旧版材质:侧边栏使用 .bar、弹出层使用 .ultraThinMaterial、HUD 窗口使用 .ultraThickMaterial、工具栏使用 .bar、选择态使用 .thick。这套"风格枚举 + 版本分派 + 统一入口(.modernBackground(style:cornerRadius:))"的架构,使得应用内各模块无需各自操心系统差异,即可一致地获得 Liquid Glass 或等价材质。对于同时维护 AppKit 与 SwiftUI 界面的场景,还可参考仓库中的 AppKit 版指南 docs/AppKit-Implementing-Liquid-Glass-Design.md。

实战示例:自定义 Liquid Glass 徽章

综合上述所有技巧,下面是一个完整的自定义徽章组件:BadgeView 将系统符号叠加在彩色六边形上,外面包裹一层圆角矩形的液态玻璃;多个徽章放入 GlassEffectContainer 中,玻璃之间自然融合成一体:

struct BadgeView: View {
    let symbol: String
    let color: Color

    var body: some View {
        ZStack {
            Image(systemName: "hexagon.fill")
                .foregroundColor(color)
                .font(.system(size: 50))

            Image(systemName: symbol)
                .foregroundColor(.white)
                .font(.system(size: 30))
        }
        .glassEffect(.regular, in: .rect(cornerRadius: 16))
    }
}

// Usage:
GlassEffectContainer(spacing: 20) {
    HStack(spacing: 20) {
        BadgeView(symbol: "star.fill", color: .blue)
        BadgeView(symbol: "heart.fill", color: .red)
        BadgeView(symbol: "leaf.fill", color: .green)
    }
}

这个示例集中体现了本文的所有核心要点:glassEffect 的基础用法、in: 形状定制、GlassEffectContainer 的多玻璃合并,以及"彩色内容 + 玻璃"的折射设计。若需要让徽章响应指针交互,只需将 .glassEffect(.regular, in: .rect(cornerRadius: 16)) 改为 .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16));若需要让徽章在出现/消失时产生形态变换,则为其追加 glassEffectID(_:in:) 并配合 @Namespace 与动画即可。

总结

Liquid Glass 为 SwiftUI 应用带来了兼具光学真实感与流体动感的系统级材质能力。本文从基础修饰符出发,覆盖了形状定制、Glass 变体链式配置、交互式玻璃、GlassEffectContainer 与 glassEffectUnion 的多玻璃合并、基于 glassEffectID 的形态变换、玻璃按钮样式、背景延伸与滚动扩展,以及面向旧系统的回退方案。关键结论可以浓缩为三点:

  • 用对容器:多玻璃场景一律使用 GlassEffectContainer,用 spacing 控制融合阈值,用 glassEffectUnion 处理动态/非容器内视图;
  • 配好背景:玻璃的折射与反射依赖背后内容,记得在玻璃后方放置渐变、图片或滚动内容;
  • 做好回退:以 #available 分支或统一封装层(如 Peekaboo 的 ModernEffectView)为旧系统提供等价材质,确保界面在所有目标系统上保持一致。

依照本指南,你可以将 Liquid Glass 平滑地引入自己的 SwiftUI 应用,并在版本适配的约束下获得原生一致、可演进的玻璃化界面。

登录后查看全文
Peekaboo