LiquidGlassKit

LiquidGlassKit 是一个面向 UIKit 的 Liquid Glass 效果库。它使用 Swift、Metal 和公开 UIKit API，在较旧的 iOS 系统上重现类似 iOS 26 的玻璃视觉效果，并提供与系统控件相近的替代组件。

当前版本：2.0.0

• 支持 iOS 13.0 及以上版本。
• 在 iOS 26 及以上版本可选择使用系统原生 Liquid Glass API。
• 在旧系统上使用项目自带的 Metal 渲染实现。
• 提供玻璃视图、视觉效果视图、滑块、开关和 Lens 视图。
• 支持玻璃着色、交互模式、圆角、形状合并和背景模糊。
• 通过 Swift Package Manager 和 Bazel 构建。
• Metal Shader 由包构建流程自动处理。

旧系统使用自定义实现；iOS 26+ 是否使用原生实现由工厂方法的 isNative 参数决定。

在 Xcode 中选择 File → Add Package Dependencies...，填入：

https://github.com/Mac-XK/LiquidGlassKit.git

选择 2.0.0 或更高版本，然后将 LiquidGlassKit 产品加入需要使用它的 Target。

也可以在其他 Swift Package 的 Package.swift 中加入：

dependencies: [
    .package(
        url: "https://github.com/Mac-XK/LiquidGlassKit.git",
        from: "2.0.0"
    )
]

并在 Target 中声明依赖：

targets: [
    .target(
        name: "YourApp",
        dependencies: ["LiquidGlassKit"]
    )
]

将 Sources/LiquidGlassKit 加入工程 Target Membership，并同时加入两个 Metal 文件：

Sources/LiquidGlassKit/LiquidGlassVertex.metal
Sources/LiquidGlassKit/LiquidGlassFragment.metal

Xcode 需要把 Metal 文件编译成 default.metallib，并将其放入名为 LiquidGlassKitShaderResources.bundle 的资源包。资源包必须随 App、Framework 或插件一起发布。

使用 Swift Package Manager 时，Package.swift 中的资源声明会自动完成这项工作；直接拖入源码时，需要在 Build Phases 中手动检查资源是否已复制。

import UIKit
import LiquidGlassKit

let effect = LiquidGlassEffect(style: .regular, isNative: true)
let glassView = VisualEffectView(effect: effect)

glassView.frame = CGRect(x: 20, y: 100, width: 240, height: 80)
glassView.layer.cornerRadius = 24
glassView.clipsToBounds = true
view.addSubview(glassView)

glassView.contentView.addSubview(label)

isNative 的行为：

• true：iOS 26+ 优先使用系统实现，旧系统使用 LiquidGlassKit 实现。
• false：始终使用 LiquidGlassKit 自带实现。

let containerEffect = LiquidGlassContainerEffect(isNative: true)
let containerView = VisualEffectView(effect: containerEffect)
containerView.contentView.addSubview(firstView)
containerView.contentView.addSubview(secondView)

可以通过 containerEffect.spacing 调整多个玻璃元素开始合并的间距。

let glassSwitch = LiquidGlassSwitch.make(isNative: true)
glassSwitch.isOn = true
glassSwitch.addTarget(
    self,
    action: #selector(switchChanged),
    for: .valueChanged
)
view.addSubview(glassSwitch)

let glassSlider = LiquidGlassSlider.make(isNative: true)
glassSlider.minimumValue = 0
glassSlider.maximumValue = 100
glassSlider.value = 50
view.addSubview(glassSlider)

let lensView = LiquidLensView()
lensView.restingBackgroundColor = .white.withAlphaComponent(0.2)
lensView.setLifted(true, animated: true, alongsideAnimations: nil, completion: nil)

项目默认使用公开 API 的背景捕获路径。需要测试 CABackdropLayer 路径时，在 Target 的 Other Swift Flags 中加入：

-DLIQUIDGLASSKIT_ENABLE_PRIVATE_API

启用后，iOS 26.2 以下系统会优先使用 Backdrop 路径；iOS 26.2 及以上仍使用公开的根视图渲染路径。私有 API 适合内部测试环境，发布版本应根据目标分发渠道进行评估。

LiquidGlassKit 本身是 Swift 模块。接入 Objective-C 动态库时，建议：

1. 将 LiquidGlassKit 作为本地 Package 加入动态库 Target，或加入所有 Swift/Metal 源文件。
2. 链接 UIKit、Metal、MetalKit、MetalPerformanceShaders 和 CoreVideo。
3. 新建 Swift 桥接类，在其中创建 LiquidGlassEffectView、LiquidGlassSlider 或 LiquidGlassSwitch。
4. 通过生成的 YourTarget-Swift.h 从 Objective-C Hook 代码调用桥接方法。
5. 将 LiquidGlassKitShaderResources.bundle 放入宿主 App 或插件可查找的资源目录。

• LiquidGlassView 会进行背景捕获和 Metal 渲染，建议控制视图数量。
• 背景捕获区域越大，CPU/GPU 开销越高。
• 不需要连续更新时，可将 autoCapture 设为 false，在内容变化后手动调用 captureBackground()。
• 对固定尺寸的玻璃控件设置明确的 frame 或 Auto Layout 约束，减少重复布局。
• 在真机上测试不同内容复杂度和动态效果，模拟器结果仅供参考。

LiquidGlassKit/
├── Package.swift
├── BUILD
├── Info.plist
├── README.md
└── Sources/LiquidGlassKit/
    ├── LiquidGlassView.swift
    ├── LiquidGlassEffectView.swift
    ├── LiquidGlassSlider.swift
    ├── LiquidGlassSwitch.swift
    ├── LiquidLensView.swift
    ├── ZeroCopyBridge.swift
    ├── LiquidGlassVertex.metal
    └── LiquidGlassFragment.metal

检查 LiquidGlassKitShaderResources.bundle 是否随目标一起打包，并确认其中包含 default.metallib。直接加入源码时，重点检查 Build Phases → Copy Bundle Resources。

确认设备支持 Metal、视图已经加入层级并设置了有效尺寸，同时检查渲染视图背后是否存在可捕获的内容。

提交代码后创建语义化版本 Tag，例如：

2.0.0

使用者选择 from: "2.0.0" 时，Swift Package Manager 会按版本规则获取对应提交。

发布到 GitHub 前，请保留原项目的版权和许可证信息，并在仓库中补充 LICENSE 文件。项目中使用的系统框架和 Metal 工具链归 Apple 所有。

Copyright © 2026 Mac-XK