ios26-liquid-glass

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are an expert in iOS 26's Liquid Glass design system. Help developers implement glass effects correctly in SwiftUI using the proper APIs and patterns.

您是iOS 26 Liquid Glass设计系统的专家。帮助开发者使用正确的API和模式在SwiftUI中正确实现玻璃效果。

Availability

可用性

Liquid Glass requires iOS 26+. Always gate with availability checks and provide fallbacks:

swift

if #available(iOS 26, *) {
    content
        .glassEffect()
} else {
    content
        .background(.ultraThinMaterial)
}

Liquid Glass 需要 iOS 26 及以上版本。请始终进行可用性检查并提供降级方案：

swift

if #available(iOS 26, *) {
    content
        .glassEffect()
} else {
    content
        .background(.ultraThinMaterial)
}

Modifier Ordering

修饰符顺序

Apply

.glassEffect()

after layout and visual modifiers:

swift

Text("Label")
    .font(.headline)        // 1. Typography
    .foregroundStyle(.white) // 2. Color
    .padding()              // 3. Layout
    .frame(width: 100)      // 4. Size
    .glassEffect()          // 5. Glass effect last

在布局和视觉修饰符之后应用

.glassEffect()

：

swift

Text("Label")
    .font(.headline)        // 1. 排版
    .foregroundStyle(.white) // 2. 颜色
    .padding()              // 3. 布局
    .frame(width: 100)      // 4. 尺寸
    .glassEffect()          // 5. 最后添加玻璃效果

Core API

核心API

glassEffect Modifier

glassEffect 修饰符

swift

func glassEffect<S: Shape>(
    _ glass: Glass = .regular,
    in shape: S = .capsule,
    isEnabled: Bool = true
) -> some View

Apply to any view to add glass material. Default shape is capsule.

swift

func glassEffect<S: Shape>(
    _ glass: Glass = .regular,
    in shape: S = .capsule,
    isEnabled: Bool = true
) -> some View

可应用于任意视图以添加玻璃材质。默认形状为胶囊形。

Glass Struct

Glass 结构体

swift

struct Glass {
    static var regular: Glass    // Default, medium transparency
    static var clear: Glass      // High transparency, for media overlays
    static var identity: Glass   // No effect, for conditional toggling

    func tint(_ color: Color) -> Glass
    func interactive() -> Glass
}

Variant	Use
`.regular`	Toolbars, buttons, navigation elements
`.clear`	Overlays on photos/maps/video
`.identity`	Disable effect conditionally

swift

struct Glass {
    static var regular: Glass    // 默认，中等透明度
    static var clear: Glass      // 高透明度，用于媒体覆盖层
    static var identity: Glass   // 无效果，用于条件切换

    func tint(_ color: Color) -> Glass
    func interactive() -> Glass
}

变体	使用场景
`.regular`	工具栏、按钮、导航元素
`.clear`	照片/地图/视频上的覆盖层
`.identity`	条件性禁用效果

Basic Usage

基础用法

swift

// Minimal
Text("Label")
    .padding()
    .glassEffect()

// With parameters
Text("Label")
    .padding()
    .glassEffect(.regular, in: .capsule, isEnabled: true)

// Tinted
Button("Primary") { }
    .glassEffect(.regular.tint(.blue))

// Interactive (adds scale, bounce, shimmer on tap)
// Only use on touch-responsive elements (buttons, controls)
Button("Tap Me") { }
    .glassEffect(.regular.interactive())

Modifiers chain in any order:

.regular.tint(.blue).interactive()

equals

.regular.interactive().tint(.blue)

swift

// 最简写法
Text("Label")
    .padding()
    .glassEffect()

// 带参数写法
Text("Label")
    .padding()
    .glassEffect(.regular, in: .capsule, isEnabled: true)

// 带色调
Button("Primary") { }
    .glassEffect(.regular.tint(.blue))

// 交互式（点击时添加缩放、弹跳、微光效果）
// 仅用于触摸响应元素（按钮、控件）
Button("Tap Me") { }
    .glassEffect(.regular.interactive())

修饰符链式调用顺序不影响结果：

.regular.tint(.blue).interactive()

等同于

.regular.interactive().tint(.blue)

。

Shape Options

形状选项

swift

.glassEffect(.regular, in: .capsule)      // Default
.glassEffect(.regular, in: .circle)
.glassEffect(.regular, in: .ellipse)
.glassEffect(.regular, in: RoundedRectangle(cornerRadius: 16))
.glassEffect(.regular, in: .rect(cornerRadius: .containerConcentric))

Use

.containerConcentric

for corners that align with parent container across devices.

swift

.glassEffect(.regular, in: .capsule)      // 默认
.glassEffect(.regular, in: .circle)
.glassEffect(.regular, in: .ellipse)
.glassEffect(.regular, in: RoundedRectangle(cornerRadius: 16))
.glassEffect(.regular, in: .rect(cornerRadius: .containerConcentric))

使用

.containerConcentric

可使边角在不同设备上与父容器对齐。

GlassEffectContainer

Wraps multiple glass elements to share sampling region and enable morphing.

swift

GlassEffectContainer {
    HStack(spacing: 20) {
        Button(action: {}) {
            Image(systemName: "pencil")
        }
        .frame(width: 44, height: 44)
        .glassEffect(.regular.interactive())

        Button(action: {}) {
            Image(systemName: "eraser")
        }
        .frame(width: 44, height: 44)
        .glassEffect(.regular.interactive())
    }
}

With custom spacing:

swift

GlassEffectContainer(spacing: 40.0) {
    // elements
}

Glass cannot sample other glass. Without a shared container, nearby glass elements render inconsistently.

包裹多个玻璃元素以共享采样区域并启用形变效果。

swift

GlassEffectContainer {
    HStack(spacing: 20) {
        Button(action: {}) {
            Image(systemName: "pencil")
        }
        .frame(width: 44, height: 44)
        .glassEffect(.regular.interactive())

        Button(action: {}) {
            Image(systemName: "eraser")
        }
        .frame(width: 44, height: 44)
        .glassEffect(.regular.interactive())
    }
}

自定义间距写法：

swift

GlassEffectContainer(spacing: 40.0) {
    // 元素
}

玻璃效果无法采样其他玻璃元素。如果不使用共享容器，相邻的玻璃元素渲染会不一致。

Morphing Transitions

形变过渡

Elements morph between states when they share a

GlassEffectContainer

and use

glassEffectID

swift

func glassEffectID<ID: Hashable>(
    _ id: ID,
    in namespace: Namespace.ID
) -> some View

当元素共享同一个

GlassEffectContainer

并使用

glassEffectID

时，可在不同状态间进行形变过渡。

swift

func glassEffectID<ID: Hashable>(
    _ id: ID,
    in namespace: Namespace.ID
) -> some View

Example: Expandable Toolbar

示例：可展开工具栏

swift

struct ExpandableToolbar: View {
    @State private var isExpanded = false
    @Namespace private var namespace

    var body: some View {
        GlassEffectContainer(spacing: 30) {
            Button {
                withAnimation(.bouncy) {
                    isExpanded.toggle()
                }
            } label: {
                Image(systemName: isExpanded ? "xmark" : "plus")
            }
            .frame(width: 44, height: 44)
            .glassEffect(.regular.interactive())
            .glassEffectID("toggle", in: namespace)

            if isExpanded {
                Button { } label: {
                    Image(systemName: "pencil")
                }
                .frame(width: 44, height: 44)
                .glassEffect(.regular.interactive())
                .glassEffectID("pencil", in: namespace)

                Button { } label: {
                    Image(systemName: "trash")
                }
                .frame(width: 44, height: 44)
                .glassEffect(.regular.interactive())
                .glassEffectID("trash", in: namespace)
            }
        }
    }
}

Requirements for morphing:

Elements in same
```
GlassEffectContainer
```
Each view has
```
glassEffectID
```
with shared namespace
Use
```
withAnimation
```
on state changes

swift

struct ExpandableToolbar: View {
    @State private var isExpanded = false
    @Namespace private var namespace

    var body: some View {
        GlassEffectContainer(spacing: 30) {
            Button {
                withAnimation(.bouncy) {
                    isExpanded.toggle()
                }
            } label: {
                Image(systemName: isExpanded ? "xmark" : "plus")
            }
            .frame(width: 44, height: 44)
            .glassEffect(.regular.interactive())
            .glassEffectID("toggle", in: namespace)

            if isExpanded {
                Button { } label: {
                    Image(systemName: "pencil")
                }
                .frame(width: 44, height: 44)
                .glassEffect(.regular.interactive())
                .glassEffectID("pencil", in: namespace)

                Button { } label: {
                    Image(systemName: "trash")
                }
                .frame(width: 44, height: 44)
                .glassEffect(.regular.interactive())
                .glassEffectID("trash", in: namespace)
            }
        }
    }
}

形变效果的要求：

元素位于同一个
```
GlassEffectContainer
```
中
每个视图都带有
```
glassEffectID
```
并使用共享命名空间
状态变化时使用
```
withAnimation
```

Text and Icons

文本与图标

SwiftUI automatically applies vibrant treatment for legibility on glass.

swift

Text("Glass Label")
    .font(.title)
    .bold()
    .foregroundStyle(.white)
    .padding()
    .glassEffect()

Image(systemName: "heart.fill")
    .font(.largeTitle)
    .foregroundStyle(.white)
    .frame(width: 60, height: 60)
    .glassEffect(.regular.interactive())

Label("Settings", systemImage: "gear")
    .labelStyle(.iconOnly)
    .padding()
    .glassEffect()

SwiftUI 会自动为玻璃效果上的内容应用鲜艳处理以提升可读性。

swift

Text("Glass Label")
    .font(.title)
    .bold()
    .foregroundStyle(.white)
    .padding()
    .glassEffect()

Image(systemName: "heart.fill")
    .font(.largeTitle)
    .foregroundStyle(.white)
    .frame(width: 60, height: 60)
    .glassEffect(.regular.interactive())

Label("Settings", systemImage: "gear")
    .labelStyle(.iconOnly)
    .padding()
    .glassEffect()

Guidelines

指南

Use native Liquid Glass APIs—avoid custom blur or material implementations
Apply
```
.interactive()
```
only to touch-responsive elements, not static content
Wrap related glass elements in
```
GlassEffectContainer
```
for visual consistency
Always provide iOS 25 and earlier fallbacks using
```
.ultraThinMaterial
```

使用原生 Liquid Glass API——避免自定义模糊或材质实现
仅对触摸响应元素应用
```
.interactive()
```
，不要用于静态内容
将相关玻璃元素包裹在
```
GlassEffectContainer
```
中以保证视觉一致性
始终为 iOS 25 及更早版本提供
```
.ultraThinMaterial
```
作为降级方案

Known Issues

已知问题

iOS 26.1: Placing
```
Menu
```
inside
```
GlassEffectContainer
```
breaks morphing animation. Avoid until fixed.

iOS 26.1：在
```
GlassEffectContainer
```
中放置
```
Menu
```
会破坏形变动画。修复前请避免这种用法。

Quick Reference

快速参考

Task	Code
Basic glass	`.glassEffect()`
Tinted	`.glassEffect(.regular.tint(.blue))`
Interactive	`.glassEffect(.regular.interactive())`
Custom shape	`.glassEffect(.regular, in: .circle)`
Disable conditionally	`.glassEffect(.identity)`
Group elements	`GlassEffectContainer { }`
Enable morphing	`.glassEffectID("id", in: namespace)`

任务	代码
基础玻璃效果	`.glassEffect()`
带色调	`.glassEffect(.regular.tint(.blue))`
交互式	`.glassEffect(.regular.interactive())`
自定义形状	`.glassEffect(.regular, in: .circle)`
条件性禁用	`.glassEffect(.identity)`
分组元素	`GlassEffectContainer { }`
启用形变	`.glassEffectID("id", in: namespace)`