SwiftUI 中的 Liquid Glass：在 iOS 26 上推出 Return 的三種模式

Apple 的 Liquid Glass 是一行程式碼的 SwiftUI API：.glassEffect()。¹ Return 是我製作的冥想計時器,在 iOS、macOS 和 tvOS 上共使用了九次。² 其中一次是將此修飾器套用至自訂的 Shape,讓計時器數字本身逐個字符地化為流動玻璃。

有趣的問題是當您超越這一行程式碼時會發生什麼。Apple 的人機介面指南制定了嚴格的分層規則:Liquid Glass 屬於功能層(控制元件、導覽、暫時性 UI),絕對不應該出現在內容層。³ Return 的九次使用中,大多數是教科書般的功能層應用:選擇器、按鈕、控制條、暫停狀態徽章。最有趣的是其中三次在不打破規則的前提下加以彎折。

本文將剖析我推出的三種模式、它們所遵守的規則、令我陷入困境的陷阱,以及一個我刻意未使用的 API 介面。

摘要

• iOS 26 將 Liquid Glass 以 .glassEffect(_:in:) 形式推出。預設變體為 .regular,預設形狀為 Capsule。¹
• Return 使用了三種超越一行程式碼的模式:在自訂 Shape 上套用玻璃(透過 Core Text 字符路徑呈現計時器文字)、鏡面模式(透過翻轉並加上遮罩的副本在底下產生反射),以及功能層 HUD 疊層。
• Apple 的 HIG 規則:Liquid Glass 用於功能層,標準材質用於內容層。³
• 我刻意沒有使用 GlassEffectContainer。變形 API 在 Return 中沒有使用情境(沒有任何玻璃元件會變形成另一個),且我未測試過渲染效能差距;這是未經測量的取捨,並非建議。¹
• 陷阱:平面背景上的玻璃看起來會像平面;無抖動的數字渲染需要固定寬度的儲存格;tvOS 的 HStack 會忽略 layout-direction 環境值;變形動畫必須遵守減少動態效果的設定。

一行程式碼的 API 和分層規則

Apple 以小巧的介面推出 Liquid Glass,作為 WWDC 2025 的主要設計支柱:¹¹³

Text("Hello, World!")
    .font(.title)
    .padding()
    .glassEffect()                              // default: .regular variant, Capsule shape

Text("Hello, World!")
    .glassEffect(in: .rect(cornerRadius: 16))   // custom shape

Text("Hello, World!")
    .glassEffect(.regular.tint(.orange).interactive())  // tint + touch reactivity

三個調節旋鈕:變體(.regular 或 .clear)、形狀(任何 Shape),以及 GlassEffectStyle 鏈(色調、互動性)。這就是單一檢視的全部 API。多檢視渲染由獨立的 GlassEffectContainer 處理,稍後會談到。

HIG 比 API 更為嚴謹。Apple 的人機介面指南為每個 iOS 26+ 介面定義了兩層:³

1. 內容層:使用者正在消費的文件、清單、照片或媒體。在此處使用標準材質(現有的 .regularMaterial、.thinMaterial 等)。
2. 功能層:控制元件、導覽、分頁列、側邊欄、暫時性疊層。在此處使用 Liquid Glass。

Apple 的具體指示:「請勿在內容層使用 Liquid Glass。Liquid Glass 在能清楚區分互動元素與內容時效果最佳,將其納入內容層可能造成不必要的複雜性與令人困惑的視覺階層。」³

聽起來這條規則限制重重,直到您將其對應到實際的應用程式。Return 是冥想計時器。其內容層是貫穿全應用程式的呼吸影像與循環影片。其功能層是時長選擇器、開始/暫停/停止按鈕堆疊、次要設定按鈕列,以及(在 tvOS 上)暫停狀態徽章。Return 九次玻璃使用中的八次都是教科書般的功能層應用:三種針對 iOS 與 macOS 程式碼路徑的時長選擇器變體、開始/暫停切換、停止按鈕、設定按鈕列、tvOS 暫停指示器,以及一個額外的暫時性控制疊層。⁴

第九次則是刻意的邊緣情況(將 Liquid Glass 套用在計時器數字本身),下一節將詳細說明。

模式 1:在自訂形狀上套用玻璃

Return 的計時器數字並不是繪製在玻璃背景上的文字。玻璃就是文字本身。.glassEffect(.clear, in:) 接受任何 Shape,⁹ 而 Shape 是一個產生 Path 的協定。¹⁰ 因此訣竅是:使用 Core Text 將計時器字串轉換為字符路徑,¹¹ 然後將該 path-as-Shape 傳遞給 .glassEffect。⁵⁶

import SwiftUI
@preconcurrency import CoreText

struct GlassTextShape: Shape {
    let text: String
    let font: CTFont

    func path(in rect: CGRect) -> Path {
        guard !text.isEmpty else { return Path() }
        let combinedPath = CGMutablePath()

        let attrString = NSAttributedString(string: text, attributes: [.font: font])
        let line = CTLineCreateWithAttributedString(attrString)
        guard let runs = CTLineGetGlyphRuns(line) as? [CTRun], !runs.isEmpty else {
            return Path()
        }

        for run in runs {
            let glyphCount = CTRunGetGlyphCount(run)
            guard glyphCount > 0 else { continue }
            var glyphs = [CGGlyph](repeating: 0, count: glyphCount)
            var positions = [CGPoint](repeating: .zero, count: glyphCount)
            let range = CFRange(location: 0, length: glyphCount)
            CTRunGetGlyphs(run, range, &glyphs)
            CTRunGetPositions(run, range, &positions)

            for i in 0..<glyphCount {
                guard let glyphPath = CTFontCreatePathForGlyph(font, glyphs[i], nil) else { continue }
                let transform = CGAffineTransform(translationX: positions[i].x, y: positions[i].y)
                combinedPath.addPath(glyphPath, transform: transform)
            }
        }

        // Core Text y-axis is flipped vs SwiftUI; flip then re-bound and center.
        var swiftPath = Path(combinedPath).applying(CGAffineTransform(scaleX: 1, y: -1))
        let flippedBounds = swiftPath.boundingRect
        let offsetX = rect.midX - flippedBounds.midX
        let offsetY = rect.midY - flippedBounds.midY
        return swiftPath.applying(CGAffineTransform(translationX: offsetX, y: offsetY))
    }
}

這是來自 Return/Return/GlassTextShape.swift 的實際生產程式碼。⁵ path(in:) 函式使用 Core Text 排列字串,走訪每個 CTRun,擷取每個字符的 CGPath,並將其合併為一個 CGMutablePath。合併後有兩個不太明顯的步驟:Core Text 的座標系統將原點置於左下角,而 SwiftUI 的 Path 則置於左上角,因此路徑必須透過 CGAffineTransform(scaleX: 1, y: -1) 翻轉。接著,翻轉後路徑的 boundingRect 會有負的 y 值,因此需要透過位移將其重新置中於 SwiftUI 給予 Shape 的矩形內。略過任一個轉換,字符就會上下顛倒或顯示在畫面外。

接著,套用部分只是一行程式碼:

Rectangle()
    .fill(.clear)
    .frame(width: cellWidth, height: cellHeight)
    .glassEffect(.clear, in: textShape)

清除的 Rectangle 是點擊目標的占位符;實際的視覺效果是 textShape 所產生的形狀。當形狀為字符路徑時,Liquid Glass 材質只會填滿字符的輪廓。結果是:計時器的每一個數字都成為獨立的流動玻璃形體,折射其後方播放的任何動畫。⁶

HIG 的細微之處。Apple 制定的規則是 Liquid Glass 用於功能層,標準材質用於內容層,但有一個明確的例外:內容層中的暫時性互動控制元件(滑桿、切換)在啟動時可以採用 Liquid Glass。³ Return 中的計時器數字是狀態顯示,不是控制元件:它們每秒從 Timer.publish(every: 1, ...) 更新一次,且沒有點擊手勢(下方的開始/暫停按鈕才是切換狀態的元件)。因此將 Liquid Glass 套用其上是刻意的邊緣情況,在意圖上比字面上的互動性更接近「暫時性互動控制元件」,因為使用者整段冥想期間都會盯著這些數字看,它們是視覺焦點。我是在彎折規則,而非打破它。一位嚴格遵循 HIG 的審查者可能會主張這應該使用標準材質;我認為計時器是一種已耗時控制介面,與進度指示器屬於同一類別。Apple 的文件並未直接裁定此案。

為何選擇自訂 Shape 而非 Text + 背景。繪製在玻璃背景上方的 Text 看起來像是文字在玻璃之上。將 Text 本身渲染為玻璃,看起來則屬於不同的視覺類別。使用者會將數字感知為功能性前景,具體而言是一個存在於被穿透觀看而非被觀看的暫時性元素。

模式 2:鏡面模式

Return 在計時器下方顯示其反射,並逐漸淡出。實際生產程式碼如下:⁶

VStack(spacing: 0) {
    GlassTimerText(text: displayTime, fontSize: fontSize)
        .accessibilityLabel("Time remaining: \(accessibleDescription)")

    if showReflection {
        GlassTimerText(text: displayTime, fontSize: fontSize)
            .scaleEffect(x: 1, y: -1)
            .mask(
                LinearGradient(
                    stops: [
                        .init(color: .white.opacity(0.2), location: 0),
                        .init(color: .clear, location: 0.6)
                    ],
                    startPoint: .top,
                    endPoint: .bottom
                )
            )
            .offset(y: -8)
            .accessibilityHidden(true)
    }
}

三個轉換組合成鏡面效果,全都是標準的 SwiftUI 原語:¹⁴

1. scaleEffect(x: 1, y: -1) 將第二份副本上下翻轉。
2. .mask(LinearGradient(...)) 將反射從頂部 20% 不透明度淡化至 60% 處完全透明。
3. .offset(y: -8) 將反射向上拉 8 點,使其緊接原圖,而不會留下可見的接縫。

反射上的 .accessibilityHidden(true) 修飾器是關鍵。VoiceOver 不應該朗讀鏡像時間兩次;原圖的 accessibilityLabel 與 accessibilityAddTraits(.updatesFrequently) 已經附加在上方的主要 GlassTimerText 實例上,而反射純粹是裝飾性的。

為何此模式特別適合 Liquid Glass。反射繼承了 GlassTimerText 的玻璃材質。原圖所在的任何背景(呼吸圈漸層、影片、染色場景)都會透過兩個副本折射。鏡面不需要任何玻璃專屬程式碼;玻璃材質會免費處理折射。整個效果只需三個修飾器加上一個漸層。

易用性的成本。啟用減少動態效果的使用者仍會看到鏡面,但時間更新之間玻璃材質的動畫會在其他地方透過 @Environment(\.accessibilityReduceMotion) 抑制。⁷ 反射本身是靜態的;只有數字過渡之間的變形會產生動畫。

模式 3:用於暫時性控制元件的玻璃 HUD 疊層

Return 中其餘八次玻璃使用都是教科書般的功能層應用。⁴ 每一次都遵循相同的模式:

durationPicker
    .frame(height: 50)
    .frame(maxWidth: 320)
    .glassEffect()
    .padding(.horizontal, 20)
    .transition(.opacity.combined(with: .scale(scale: 0.95)))

.transition(.opacity.combined(with: .scale(scale: 0.95))) 是關鍵所在。Liquid Glass 套用在暫時性控制元件上,只有當控制元件過渡時才會感覺對。永久停留在螢幕上的靜態玻璃 HUD 會被視為框架。當使用者點選時淡入並縮放、移開視線後淡出的玻璃 HUD,則會被視為片刻間的控制介面。

Apple 對 glassEffect 的文件含蓄地指出這一點:該修飾器「擷取內容傳送至容器以進行渲染」,並「即時對觸控與指標互動做出反應」。¹ 動畫鉤子並未在 API 中,但渲染管線假設玻璃元素會移動。靜態玻璃元素錯失了這項可供性。

Return 將此模式用於時長選擇器(使用者點選時向上滑出)、開始/暫停切換按鈕(始終可見但按下時會縮放)、停止按鈕(僅在會話進行中可見)、設定按鈕列(時長選擇器下方的水平控制條),以及 tvOS 暫停狀態徽章(僅在 Apple TV 上會話暫停時可見)。所有五種情境都遵守 HIG 的功能層規則。³

GlassEffectContainer 的問題

Apple 建議任何應用程式在多個檢視上使用 .glassEffect() 時都應採用 GlassEffectContainer,原因有二:更好的渲染效能(玻璃效果會被批次處理),以及在過渡期間將形狀變形成另一個的能力。¹

我沒有使用它。理由是針對應用程式而定的,並非反駁 Apple 的指導。Return 有九個玻璃檢視,沒有一個需要在彼此之間變形。⁴⁶ 時長選擇器永遠不會動畫變成開始按鈕。計時器文字永遠不會動畫變成設定按鈕列。每個玻璃元素都是獨立的。變形 API 將沒有可觸發的使用情境,而容器的間距規則會限制目前無需協調的版面配置。

渲染效能的論點我若無測量則無法完全反駁。Apple 的文件警告「太多」位於容器外的玻璃效果可能會降低效能。¹ Return 的九個檢視從未同時出現在螢幕上(時長選擇器只出現在選單狀態,停止按鈕只在會話進行中暫停時出現)。在任何特定畫面中,我數到三或四個可見的玻璃元素,在我測試過的 iOS、iPadOS、macOS、watchOS 和 tvOS 各裝置上都很流暢,但我尚未執行 Instruments 追蹤來比較容器包裝與僅修飾器的差異。因此誠實的說法是:Return 跳過 GlassEffectContainer 是基於觀察到良好的使用者體驗,而非經過測量的效能等價性。

我從中得出的規則:GlassEffectContainer 適用於多個玻璃元素同時可見且具動畫的應用程式。Apple 的範例是使用 glassEffectUnion(id:namespace:) 的符號集渲染:四個天氣符號流暢地融合與分裂為一體。¹ 這是教科書般的使用情境。如果 Return 未來的功能需要玻璃元素變形或共享容器的間距規則,屆時容器就是該添加的正確工具。對於今日的應用程式,我尚未遇到該情境。

令我陷入困境的陷阱

三個來自生產環境的真實 bug:

玻璃數字抖動。SF Pro Rounded 在比例渲染下具有可變寬度的數字。當計時器倒數時,顯示的字串長度會改變,周圍的 HStack 每秒都會重新排版,使整個計時器抖動。修正方法:每個字元使用固定寬度的儲存格。每個數字的 cellWidth 為 fontSize * 0.6,每個冒號為 fontSize * 0.3,而 HStack 變成穩定的網格。⁶

HStack(spacing: 0) {
    ForEach(Array(text.enumerated()), id: \.offset) { _, char in
        let isColon = char == ":"
        let cellWidth = isColon ? colonCellWidth : digitCellWidth
        GlassDigitCell(character: String(char), font: ctFont,
                       cellWidth: cellWidth, cellHeight: cellHeight)
    }
}

這些儲存格並非 Apple 標準;它們是針對小型固定字級下比例寬度渲染的變通方案。Apple 的 SF Pro Rounded 搭配 .monospacedDigit() 可以在 Text 上解決同樣的問題,但該修飾器無法在自訂的 Shape 玻璃渲染器上使用。固定儲存格版面是替代方案。

tvOS 的 layout-direction 覆寫。同一份 GlassTimerText 在 iOS、iPadOS、macOS 和 tvOS 上執行。但在 tvOS 上,即使 iOS 版本遵守了環境內的覆寫,在從右至左語言環境下 HStack 仍然鏡像。修正方法:同時透過環境值與明確的 flipsForRightToLeftLayoutDirection(false) 修飾器來固定版面方向,直接套用在數字儲存格的 HStack 上(父層 VStack 另外套用環境覆寫,使反射副本繼承之):⁶

HStack(spacing: 0) { ... }
    .flipsForRightToLeftLayoutDirection(false)
    .environment(\.layoutDirection, .leftToRight)

原因是:tvOS 的 HStack 在某些版本中似乎會忽略環境層級的覆寫,而 flipsForRightToLeftLayoutDirection(false) 是一個更可靠地被遵守的明確不鏡像合約。¹² 雙保險。

數字變形時的減少動態效果處理。Liquid Glass 預設會在顯示字串之間動畫化變形過渡。啟用 accessibilityReduceMotion 的使用者會將變形視為閃爍。修正方法:⁶

.animation(reduceMotion ? nil : .easeInOut(duration: 0.15), value: displayTime)

動畫修飾器讀取 @Environment(\.accessibilityReduceMotion),當減少動態效果開啟時完全停用過渡。Apple 的易用性指引非常明確:任何裝飾性動畫都必須遵守使用者的動態效果偏好。⁷

何時不該使用 Liquid Glass

拒絕也是設計的一部分。

請勿將 Liquid Glass 套用在內容層。Apple 的 HIG 寫得很明確,忽略此規則會產生混亂的階層:使用者無法分辨什麼是互動元素、什麼是內容。³ 如果玻璃效果裝飾著清單列或照片卡片,代表設計與平台背道而馳。

請勿在平面背景上使用玻璃。Liquid Glass 會折射其後方的事物。如果「後方的事物」是單一純色,折射就沒有東西可彎折,結果看起來會像是平面的染色矩形。請將玻璃放在富有變化的內容(漸層、圖像、影片)上方,或者完全不要使用玻璃。Return 的計時器畫面透過 VideoBackgroundView 在背景執行主題式封面影像與循環影片,⁴ 正是為了讓上方的玻璃元素永遠有紋理可折射。

對高頻內容使用玻璃時請保持謹慎。玻璃材質渲染受 GPU 限制,而玻璃形狀變化之間的預設變形動畫本身就是動畫。每秒更新一次的計時器在我的測試中沒有問題;以 60 Hz 運作的波形或音訊視覺化器則未經驗證,且可能與變形動畫衝突。我尚未測試其上限;請將此視為經驗法則,而非經過測量的閾值。Apple 的文件並未公佈具體數值。

請勿在未測試減少動態效果的情況下推出玻璃。每個玻璃動畫都應該以 accessibilityReduceMotion 為閘門。⁷ 玻璃形狀之間的預設變形是一種動態效果,而非僅僅淡入淡出。

Liquid Glass 對於在 iOS 26+ 上推出的應用程式意味著什麼

論點很小。只有在應用程式已經遵守 HIG 分層規則時,Liquid Glass 才是一行程式碼的 API。將控制元件放在功能層、將內容放在內容層的 SwiftUI 應用程式可以採用 .glassEffect() 修飾器,並預設感覺原生。

混合兩個分層的應用程式(將控制元件放在清單列內、將導覽列視為內容、在照片卡片上裝飾性框架)採用 Liquid Glass 後會感覺不對。材質沒問題;它底下的架構才是問題。

自訂 Shape 模式(模式 1)乾淨地延伸了規則。任何在功能上是控制元件的事物都可以採用 Liquid Glass,即使它在傳統意義上看起來不像「控制元件」。計時器是控制元件,音量計是控制元件,進度指示器是控制元件。將 Liquid Glass 套用在這些元素上完全符合規範。

請將本文與我先前關於透過 App Intents 與 MCP 伺服器 推出同款應用程式資料層的文章一同閱讀。視覺層是同一堆疊的第三個介面:用於系統 AI 的型別化實體、用於跨 LLM 代理的檔案格式,以及用於人類在裝置前的 Liquid Glass。⁸

常見問題

我可以在非 iOS 26 的平台上使用 .glassEffect() 嗎?

.glassEffect() 修飾器需要 iOS 26+、iPadOS 26+、macOS 26+、watchOS 26+、tvOS 26+、visionOS 26+。26 之前的平台有 .background(.regularMaterial) 等,可產生霧面玻璃效果,但並非新版 Liquid Glass 的折射效果。¹

GlassEffectContainer 會改變視覺效果嗎?

被容器包裝的玻璃元素在其間距規則導致重疊時可以將其形狀混合在一起。沒有容器的話,每個 .glassEffect() 都是獨立的。對於玻璃元素應該在動畫期間流暢融合的應用程式,GlassEffectContainer 是正確的工具。對於每個玻璃元素都保持獨立的應用程式,容器則是額外負擔。¹

為什麼不直接對 Text 使用 .foregroundStyle(.thinMaterial)?

thinMaterial 是標準材質,並非 Liquid Glass。視覺效果是霧面玻璃疊層,而非 Liquid Glass 那種折射玻璃伴隨光線彎折的效果。³ 對於應該看起來像是新材質的文字,.glassEffect(.clear, in: customShape) 才是受支援的途徑。

我該如何擷取 Liquid Glass 螢幕截圖用於行銷?

玻璃效果是在執行階段由 GPU 渲染,因此螢幕截圖是從已套用效果的模擬器或裝置中擷取。Apple 官方的 Liquid Glass 參考影像來自其 HIG 文件頁面與 WWDC 2025 場次。³

GlassTextShape 適用於任意文字還是僅適用於數字?

任何 Core Text 可以排列的字串都適用。Return 將其用於數字與冒號,但相同的 Shape 也適用於字母、符號、表情符號(搭配適合的字體)或混合字串。效能受限於字符數;以玻璃渲染長段落會很昂貴,但渲染六個字元的計時器則是輕而易舉。

三種模式、一條規則,以及一個我刻意跳過的 API。Liquid Glass 是 iOS 26+ 應用程式的第三個介面,座落於型別化實體與共享檔案格式之上。一行程式碼的 API 是真實存在的。其底下的 HIG 規則才是讓這一行程式碼運作的關鍵。

參考資料