name: liquid-glass-developer description: 上下文感知路由到 iOS 26 液态玻璃实现模式。用于处理玻璃效果、GlassEffectContainer、变形过渡或 iOS 26 视觉效果时。

液态玻璃开发者（iOS 26）

目的

上下文感知路由到 iOS 26 液态玻璃实现模式。正确使用 GlassEffectContainer、glassEffect 修饰符、变形过渡和交互效果。

何时自动激活

处理玻璃效果或 iOS 26 视觉效果时
关键词：glass、liquid glass、glassEffect、GlassEffectContainer、iOS 26、morphing、UIGlassEffect、UIVisualEffectView、cornerConfiguration、GlassContainerViewIOS26、GlassEffectViewIOS26
编辑带有玻璃效果修饰符的文件时
实现导航面板、浮动按钮或半透明 UI 时

🚨 关键规则（切勿违反）

始终将玻璃元素分组在 GlassEffectContainerIOS26 中 - 玻璃元素必须分组以实现统一组合
始终为变形使用 glassEffectIDIOS26 - 出现/消失的元素需要 ID 以实现平滑过渡
玻璃定义其形状 - 使用 glassEffect(in: Shape)，无需单独的 clipShape()
玻璃仅用于导航层 - 切勿应用于内容，仅用于浮动控件
为按钮使用交互式玻璃 - 按钮应使用 .regular.interactive() 以实现触摸反馈

📋 快速参考

可用工具（View+iOS26.swift）

// 带 iOS 版本检查的 GlassEffectContainer 包装器
GlassEffectContainerIOS26(spacing: 20) {
    // 玻璃元素放在这里
}

// 交互式玻璃效果（触摸时缩放/弹跳）
.glassEffectInteractiveIOS26(in: Circle())
.glassEffectInteractiveIOS26(in: .rect(cornerRadius: 16))

// 标准玻璃效果（无触摸反馈）
.glassEffectIOS26(in: Circle())

// 变形过渡 ID
.glassEffectIDIOS26("buttonId", in: glassNamespace)

// 玻璃按钮样式（传统，推荐使用 glassEffectInteractiveIOS26）
.buttonStyleGlassIOS26()

完整模式示例

struct NavigationPanel: View {
    @Namespace private var glassNamespace
    @State private var isExpanded = false

    var body: some View {
        GlassEffectContainerIOS26(spacing: 20) {
            HStack {
                Button { } label: {
                    Image(systemName: "magnifyingglass")
                        .frame(width: 40, height: 40)
                }
                .glassEffectInteractiveIOS26(in: Circle())
                .glassEffectIDIOS26("search", in: glassNamespace)

                if isExpanded {
                    Button { } label: {
                        Image(systemName: "plus")
                            .frame(width: 40, height: 40)
                    }
                    .glassEffectInteractiveIOS26(in: Circle())
                    .glassEffectIDIOS26("add", in: glassNamespace)
                }
            }
        }
        .animation(.bouncy, value: isExpanded)
    }
}

玻璃形状

// 圆形按钮
.glassEffectInteractiveIOS26(in: Circle())

// 圆角矩形
.glassEffectInteractiveIOS26(in: .rect(cornerRadius: 16))

// 胶囊形
.glassEffectInteractiveIOS26(in: Capsule())

🔄 变形过渡

用于玻璃元素之间的平滑状态过渡：

@Namespace private var glassNamespace

// 具有相同容器和 ID 的元素平滑变形
GlassEffectContainerIOS26 {
    if editing {
        plusButton
            .glassEffectIDIOS26("leftButton", in: glassNamespace)
    } else {
        burgerButton
            .glassEffectIDIOS26("leftButton", in: glassNamespace)
    }
}
.animation(.bouncy, value: editing)

关键要求：

元素在同一个 GlassEffectContainerIOS26 中
每个元素都有带有共享命名空间的 glassEffectIDIOS26
用动画包装状态变化

⚠️ 常见错误

无容器分组

// ❌ 错误 - 独立的玻璃效果
HStack {
    button1.glassEffectIOS26(in: Circle())
    button2.glassEffectIOS26(in: Circle())
}

// ✅ 正确 - 在容器中分组
GlassEffectContainerIOS26 {
    HStack {
        button1.glassEffectInteractiveIOS26(in: Circle())
        button2.glassEffectInteractiveIOS26(in: Circle())
    }
}

冗余的 clipShape

// ❌ 错误 - 玻璃前使用 clipShape
.clipShape(Circle())
.glassEffectIOS26(in: Circle())

// ✅ 正确 - 玻璃定义形状
.glassEffectInteractiveIOS26(in: Circle())

缺少变形 ID

// ❌ 错误 - 突兀的出现/消失
if isVisible {
    button.glassEffectInteractiveIOS26(in: Circle())
}

// ✅ 正确 - 平滑变形
if isVisible {
    button
        .glassEffectInteractiveIOS26(in: Circle())
        .glassEffectIDIOS26("button", in: namespace)
}

玻璃应用于内容

// ❌ 错误 - 玻璃应用于内容
Text("Hello World")
    .glassEffectIOS26(in: .rect(cornerRadius: 8))

// ✅ 正确 - 玻璃仅用于浮动控件
// 为内容使用标准背景：
Text("Hello World")
    .background(Color.Background.primary)

📚 iOS 版本处理

所有工具内部处理 iOS 版本检查：

iOS 26+：应用原生玻璃效果
iOS < 26：回退到 Color.Background.navigationPanel + .ultraThinMaterial

// 这在所有 iOS 版本上都有效
.glassEffectInteractiveIOS26(in: Circle())

// 等效于：
if #available(iOS 26.0, *) {
    self.glassEffect(.regular.interactive(), in: Circle())
} else {
    self
        .background(Color.Background.navigationPanel)
        .background(.ultraThinMaterial)
}

🔧 UIKit 实现

可用工具（UIView+iOS26Glass.swift）

// 用于分组玻璃元素的容器（类似于 SwiftUI 中的 GlassEffectContainerIOS26）
let container = GlassContainerViewIOS26(spacing: 12)
container.glassContentView.addSubview(yourContent)

// 独立的玻璃效果视图（始终交互式）
let glassView = GlassEffectViewIOS26()
glassView.glassContentView.addSubview(yourButton)

// 玻璃按钮配置
let config = UIButton.Configuration.glassIOS26()
let button = UIButton(configuration: config)

UIKit 模式示例

final class NavigationBarView: UIView {
    private let glassContainer = GlassContainerViewIOS26(spacing: 12)
    private let buttonGlass = GlassEffectViewIOS26()

    override init(frame: CGRect) {
        super.init(frame: frame)
        setup()
    }

    private func setup() {
        // 将容器添加到视图
        addSubview(glassContainer) {
            $0.pinToSuperview(insets: UIEdgeInsets(top: 0, left: 16, bottom: 0, right: 16))
            $0.height.equal(to: 44)
        }

        // 设置带玻璃的圆形按钮
        buttonGlass.applyCircleShape(diameter: 44)
        buttonGlass.layoutUsing.anchors {
            $0.size(CGSize(width: 44, height: 44))
        }

        // 将按钮添加到玻璃内容视图（不要直接添加到 buttonGlass）
        buttonGlass.glassContentView.addSubview(myButton) {
            $0.center(in: buttonGlass.glassContentView)
        }

        // 将玻璃按钮添加到容器的内容视图
        glassContainer.glassContentView.addSubview(buttonGlass)
    }
}

形状方法

// 圆形按钮（44x44）
glassView.applyCircleShape(diameter: 44)

// 胶囊/药丸形状（例如，用于标题视图）
glassView.applyCapsuleShape(height: 44)

// iOS 26+：使用 cornerConfiguration = .capsule()
// iOS < 26：使用 layer.cornerRadius 回退

UIKit 关键规则

始终将内容添加到 glassContentView - 切勿直接将子视图添加到玻璃视图

// ❌ 错误
glassView.addSubview(button)

// ✅ 正确
glassView.glassContentView.addSubview(button)

在设置中调用形状方法一次 - 不要在 layoutSubviews 中调用（除非高度动态变化）

// ❌ 错误 - 每个布局传递都调用
override func layoutSubviews() {
    super.layoutSubviews()
    glassView.applyCapsuleShape(height: bounds.height)
}

// ✅ 正确 - 使用固定高度调用一次
func setup() {
    glassView.applyCapsuleShape(height: 44)
}

GlassEffectViewIOS26 始终交互式 - 没有属性设置，触摸反馈内置

为文本按钮使用 glassIOS26()

var config = UIButton.Configuration.glassIOS26()
config.title = "Done"
config.baseForegroundColor = .Control.accent100
let button = UIButton(configuration: config)

iOS 版本处理（UIKit）

// GlassEffectViewIOS26 内部处理版本检查：
// iOS 26+：使用 cornerConfiguration 的 UIGlassEffect
// iOS < 26：UIBlurEffect(style: .systemUltraThinMaterial) + Background.navigationPanel

// 内部实现示例：
private func setupGlassEffect() {
    if #available(iOS 26.0, *) {
        let glassEffect = UIGlassEffect()
        glassEffect.isInteractive = true
        let effectView = UIVisualEffectView(effect: glassEffect)
        addSubview(effectView)
        glassEffectView = effectView
    } else {
        backgroundColor = .Background.navigationPanel
        let blurView = UIVisualEffectView(effect: UIBlurEffect(style: .systemUltraThinMaterial))
        addSubview(blurView)
    }
}

📁 关键文件

文件	用途
`View+iOS26.swift`	SwiftUI 玻璃效果工具和包装器
`UIView+iOS26Glass.swift`	UIKit 玻璃效果工具
`HomeBottomNavigationPanelView.swift`	带玻璃按钮的导航面板
`ChatInput.swift`	带变形汉堡/加号按钮的聊天输入
`ChatActionPanel.swift`	带交互式玻璃的操作按钮
`EditorNavigationBarView.swift`	带玻璃容器的 UIKit 导航栏
`EditorNavigationBarTitleView.swift`	带胶囊玻璃的 UIKit 标题视图

🔗 外部资源

✅ 实施清单

SwiftUI

[ ] 玻璃元素包装在 GlassEffectContainerIOS26 中
[ ] 按钮使用 glassEffectInteractiveIOS26（不仅仅是 glassEffectIOS26）
[ ] 状态依赖元素具有 glassEffectIDIOS26 用于变形
[ ] 玻璃效果前没有冗余的 clipShape()
[ ] 玻璃仅用于导航/浮动控件，而非内容
[ ] 状态变化的动画包装器（withAnimation(.bouncy) 或 .animation()）

UIKit

[ ] 玻璃元素包装在 GlassContainerViewIOS26 中
[ ] 内容添加到 glassContentView（不直接添加到玻璃视图）
[ ] 形状方法在设置中调用一次（不在 layoutSubviews 中）
[ ] 文本按钮使用 UIButton.Configuration.glassIOS26()
[ ] 圆形按钮使用 applyCircleShape(diameter:)
[ ] 药丸/胶囊形状使用 applyCapsuleShape(height:)

测试

[ ] 在 iOS 26 模拟器上测试玻璃外观
[ ] 在 iOS 18 模拟器上测试回退行为

🔗 相关技能

design-system-developer → 玻璃按钮中使用的图标和颜色
ios-dev-guidelines → SwiftUI 模式和视图修饰符

导航：此技能涵盖 iOS 26 液态玻璃模式。有关实施细节，请参见 View+iOS26.swift。