---
title: "适配 Apple Liquid Glass 视觉体系"
description: "说明如何把 SwiftUI app 迁移到 Liquid Glass，并用小步审计和验证降低重设计风险。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

把现有 SwiftUI app 迁移到 Liquid Glass，不应该从“整体重设计”开始。更稳的方式是把它当成 iOS 26 + Xcode 26 migration：先审计一个高流量 flow，再用 native Liquid Glass APIs 替换 custom blur/material stacks，并为早于 iOS 26 的设备保留 fallback。

> [!IMPORTANT]
> 平台视觉迁移必须以当前 Apple SDK、deployment target 和官方 API 文档为准。不要在旧 Xcode、旧 simulator 或未验证设备上直接把 visual migration 写进生产路径。

官方页面：[https://developers.openai.com/codex/use-cases/ios-liquid-glass](https://developers.openai.com/codex/use-cases/ios-liquid-glass)

## 适合什么任务

| 场景 | Codex 应该做什么 |
|---|---|
| 现有 SwiftUI app 需要实际 iOS 26 Liquid Glass 迁移计划 | 审计现有 UI，先迁移一个 flow |
| app 里有 custom cards、sheets、tab bars、toolbars、action buttons | 判断哪些应变成 native Liquid Glass，哪些应保持 plain content |
| app 仍支持旧 iOS 版本 | 使用 `#available(iOS 26, *)` gate 新 API，并保留非 glass fallback |

## 使用的能力

| 能力 | 用法 | 链接 |
|---|---|---|
| `build-ios-apps` | 使用 SwiftUI Liquid Glass、SwiftUI UI patterns 和 simulator debugging skills，现代化 iOS screens，并在 iOS 26 simulators 上验证 | [https://github.com/openai/plugins/tree/main/plugins/build-ios-apps](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) |

相关官方说明：

- Codex plugins：[https://developers.openai.com/codex/plugins](https://developers.openai.com/codex/plugins)
- Agent skills：[https://developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)

## 起始提示词

```text
请使用 Build iOS Apps plugin 和其中的 SwiftUI Liquid Glass skill，把这个 app 中一个高流量 flow 迁移到 Liquid Glass。

约束：
- 把它当作 iOS 26 + Xcode 26 migration 处理，但要用 `#available(iOS 26, *)` 为更早 deployment targets 保留 non-glass fallback。
- 先 audit 这个 flow。指出哪些 custom backgrounds、blur stacks、chips、buttons、sheets 和 toolbars 应该变成 native Liquid Glass，也指出哪些 surfaces 应该保持 plain content。
- 优先使用 system controls 和 native APIs，例如 `glassEffect`、`GlassEffectContainer`、`glassEffectID`、`.buttonStyle(.glass)` 和 `.buttonStyle(.glassProminent)`，不要用 custom blurs 重造。只有当真实 morphing transition 能改善 flow 时，才结合 `@Namespace` 使用 `glassEffectID`。
- 在 layout 和 visual modifiers 之后应用 `glassEffect`，保持 shapes 一致，只在真正响应 touch 的 controls 上使用 `.interactive()`。
- 使用 XcodeBuildMCP 在 iOS 26 simulator 上 build 和 run，为迁移后的 flow 捕获 screenshots，并明确说明使用了哪个 scheme、simulator 和 checks。

交付：
- 这个 flow 的简洁 migration plan
- 已实现的 Liquid Glass slice
- pre-iOS 26 devices 上的 fallback behavior
- 使用过的 simulator validation steps 和 screenshots
```

这个 prompt 先要求 audit，再要求实现一个 self-contained slice，并强制写清楚 simulator validation。

## 推荐技术面

| 需要 | 推荐默认值 | 原因 |
|---|---|---|
| Liquid Glass UI APIs | [SwiftUI](https://developer.apple.com/documentation/swiftui/) + `glassEffect`、`GlassEffectContainer`、glass button styles | 优先使用 native APIs，移除 custom blur layers |
| Platform baseline | iOS 26 and Xcode 26 | Liquid Glass 随 iOS 26 SDK 提供，Codex 应使用 Xcode 26 编译并显式添加旧系统 fallback |
| Simulator validation | [XcodeBuildMCP](https://www.xcodebuildmcp.com/) | visual migration 需要 build、launch、screenshot 和 log inspection |

## 从 iOS 26 Baseline 开始

先用 iOS 26 SDK 重新 build app，看看 standard SwiftUI controls 自动获得了什么效果。只有 custom parts 仍然过平、过重或脱离 system chrome 时，再让 Codex 迁移。

如果 app deployment target 低于 iOS 26，prompt 里必须提前写明。SwiftUI Liquid Glass skill 应该用 `#available(iOS 26, *)` 保护 glass-only APIs，并保留在旧设备上仍可读的 fallback path。

## 使用 iOS Plugin

Liquid Glass 任务里，Build iOS Apps plugin 的实用模式是：

1. 审计一个 flow。
2. 迁移一小组 surfaces。
3. 在 iOS 26 simulator 上 launch。
4. 截图后再扩大 scope。

默认规则可以直接写进 prompt：

- 优先使用 native `glassEffect`、`GlassEffectContainer`、glass button styles 和 `glassEffectID` transitions，不用 custom blur views 重造材质系统。
- `.glassEffect(...)` 放在 layout 和 visual modifiers 后面，让 material 包住最终 shape。
- 多个相关 glass surfaces 一起出现时，用 `GlassEffectContainer` 包起来。
- `.interactive()` 只用于真的响应 touch 的 buttons、chips、controls。
- corner shapes、tinting、spacing 在 feature 内保持一致。
- pre-iOS 26 targets 保留 non-glass fallback。

## WWDC 参考

开始迁移真实 production flow 前，先看这些 WWDC25 session：

- [Meet Liquid Glass](https://developer.apple.com/videos/play/wwdc2025/219/)
- [Get to know the new design system](https://developer.apple.com/videos/play/wwdc2025/356/)
- [Build a SwiftUI app with the new design](https://developer.apple.com/videos/play/wwdc2025/323/)
- [Build a UIKit app with the new design](https://developer.apple.com/videos/play/wwdc2025/284/)
- [What's new in SwiftUI](https://developer.apple.com/videos/play/wwdc2025/256/)

## 实用建议

### 不要把所有东西都玻璃化

Liquid Glass 应该在内容上方形成清楚的 control layer，而不是把每张 card 都变成发光面板。阅读优先的 content 应保持 plain；tinting 留给 semantic emphasis 或 primary actions。

### 先做一个高流量 Flow

tab root、detail screen、sheet、search surface 或 onboarding flow 通常比全 app sweep 更适合第一轮迁移。这样 review 更容易，也更容易沉淀 reusable component patterns。

### 有意 review fallback

如果 deployment target 低于 iOS 26，让 Codex 同时展示 Liquid Glass version 和 fallback implementation。这样能提前发现 API availability regression。

## 接下来去哪

<Cards>
  <Card title="构建 iOS 应用" description="先建立可重复 build、launch 和 simulator validation loop。" href="/docs/codex/official/08-scenarios/109-ios-app" />
  <Card title="SwiftUI 重构" description="视觉迁移前先把过大的 screen 拆成可 review 的边界。" href="/docs/codex/official/08-scenarios/102-swiftui-refactor" />
  <Card title="iOS 模拟器修 Bug" description="迁移后用同一条 simulator flow 验证视觉和行为。" href="/docs/codex/official/08-scenarios/101-ios-simulator-bug" />
  <Card title="官方 Liquid Glass use case" description="API、SDK 和插件说明以官方页面与 Apple 文档为准。" href="https://developers.openai.com/codex/use-cases/ios-liquid-glass" />
</Cards>
