---
title: "重構 SwiftUI 介面"
description: "說明如何讓 Codex 拆分過大的 SwiftUI screen，在不改行為的前提下降低後續維護成本。"
verifiedAt: "2026-05-06"
---

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

當一個 SwiftUI file 長成巨大的 screen，`body` 裡混著 layout、branching、async work 和 inline actions，每次小改都會變得高風險。這個用例的目標不是重設計 feature，也不是引入新架構，而是在不改變行為和佈局的前提下，把 screen 拆成小的 subviews，讓下一次修改更容易 review。

> [!CAUTION]
> SwiftUI 重構的邊界是 behavior-preserving。不要藉機換架構、改導航、改視覺、改 analytics 或重寫業務邏輯，除非這些變化被明確列為單獨任務並有驗證證據。

官方頁面：[https://developers.openai.com/codex/use-cases/ios-swiftui-view-refactor](https://developers.openai.com/codex/use-cases/ios-swiftui-view-refactor)

## 適合什麼任務

| 場景 | Codex 應該做什麼 |
|---|---|
| 巨大的 SwiftUI screen 很難 review | 拆出 meaningful section views，保持 explicit data flow |
| 現有 iOS feature 視覺和行為都不能變 | 只做結構重構，並用 build/test/simulator checks 驗證 |
| `body` 裡混著 side effects 和 business logic | 把 non-trivial actions 移到 methods，把業務邏輯移到 services 或 models |
| screen 裡有 optional view models 或 state plumbing | 修 Observation ownership，優先 MV-first，不預設加 view model |

## 使用的能力

| 能力 | 用法 | 連結 |
|---|---|---|
| `build-ios-apps` | 使用 SwiftUI view refactor skill，抽取 subviews、穩定 data flow、簡化 Observation，並保持行為不變 | [https://github.com/openai/plugins/tree/main/plugins/build-ios-apps](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) |

相關官方說明：

- Build iOS Apps plugin：[https://github.com/openai/plugins/tree/main/plugins/build-ios-apps](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps)
- Agent skills：[https://developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)

## 起始提示詞

```text
请使用 Build iOS Apps plugin 和其中的 SwiftUI view refactor skill，清理 [NameOfScreen.swift]，但不要改变 screen 的行为或外观。

约束：
- 保持 behavior、layout、navigation 和 business logic 不变；如果发现必须单独指出的 bug，请明确说明。
- 默认采用 MV，而不是 MVVM。引入新 view model 前，优先使用 `@State`、`@Environment`、`@Query`、`.task`、`.task(id:)` 和 `onChange`；只有这个 feature 明确需要时，才保留 view model。
- 重新整理 view 顺序，让 stored properties、computed state、`init`、`body`、view helpers 和 helper methods 从上到下容易扫描。
- 把有意义的 sections 抽成独立 `View` types，使用小而明确的 inputs、`@Binding`s 和 callbacks。不要把一个巨大 `body` 换成一堆巨大的 computed `some View` properties。
- 把 non-trivial button actions 和 side effects 从 `body` 移到小 methods，把真正的 business logic 移到 services 或 models。
- 保持 root view tree 稳定。局部 conditional sections 或 modifiers 足够时，避免用 top-level `if/else` 切换完全不同的 screens。
- 重构时修正 Observation ownership：iOS 17+ 上 root `@Observable` models 由 owning view 用 `@State` 持有；除非 UI 确实需要这种 state shape，否则避免 optional 或 delayed-initialized view models。
- 每完成一次 extraction，运行最小有用 build 或 test check，证明 screen 行为仍然一致。

交付：
- 重构后的 screen 和抽取出的 subviews
- 简短解释新的 subview boundaries 和 data flow
- 哪些地方有意保留了 view model，以及原因
- 你运行过哪些 validation checks 来证明行为保持不变
```

這個 prompt 明確要求 behavior-preserving refactor。Codex 不能把重構變成架構重寫。

## 推薦技術面

| 需要 | 推薦預設值 | 原因 |
|---|---|---|
| UI architecture | SwiftUI，MV-first，圍繞 `@State`、`@Environment` 和 small dedicated `View` types 拆分 | 大 screen 通常先簡化 view tree 和 state flow，再決定是否真的需要 view model |
| Refactor workflow | [Build iOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) | SwiftUI view refactor skill 提供 extraction、Observation 和 side-effect cleanup 規則 |
| Validation | `xcodebuild`、previews、focused UI checks | 每次 extraction 後跑小驗證，比一次性大改更可信 |

## 要求 Codex 做什麼

把這些規則直接放進 prompt：

- 按 environment dependencies、stored properties、computed non-view state、`init`、`body`、view helpers、helper methods 的順序整理檔案。
- 抽取 meaningful sections 到 dedicated `View` types。
- 子檢視只接收 small explicit inputs、`@Binding`s 和 callbacks。
- computed `some View` helpers 保持少而小。
- 不要把一個巨大 `body` 改成一長串 private computed view fragments。
- non-trivial button actions 和 side effects 移出 `body`。
- 業務邏輯放進 services 或 models。
- root view tree 保持穩定，儘量使用區域性 conditional sections 或 modifiers。
- iOS 17+ root `@Observable` models 由 owning view 用 `@State` 持有。

## 小驗證迴圈

行為不變的重構必須有證據。要求 Codex 每完成一個 meaningful extraction 後，執行最小有用驗證：

- build。
- preview。
- focused unit / UI test。
- simulator check。

最後讓它總結：

- 結構上改了什麼。
- 哪些行為、導航、業務規則、持久化、analytics semantics 和 user-visible layout 沒有改。
- 哪些 view model 被保留，以及為什麼。

## 實用建議

### 先拆分，再爭論架構

如果 screen 太大，先抽 section views。更短、更明確的 view tree 往往會自然降低加 view model 的需求。

### 給子檢視最小介面

優先傳 `let` values、`@Binding`s 和單一用途 callbacks，不要把整個 parent model 傳給每個 child view。

### 讓 Codex 列出 intentional non-changes

安全重構最需要的是可 review。讓 Codex 明確寫出它沒改哪些東西，能顯著降低 review 成本。

## 接下來去哪

<Cards>
  <Card title="iOS 模擬器修 Bug" description="重構後需要在 simulator 裡復現和驗證關鍵流程。" href="/zh-Hant/docs/codex/official/08-scenarios/101-ios-simulator-bug" />
  <Card title="構建 iOS 應用" description="需要從腳手架、build 和 debug 建立更完整 iOS 工作流。" href="/zh-Hant/docs/codex/official/08-scenarios/109-ios-app" />
  <Card title="原生應用路線" description="按 iOS、macOS 和平臺工具鏈選擇後續學習順序。" href="/zh-Hant/docs/codex/official/07-learning-paths/77-native-app-path" />
  <Card title="官方 SwiftUI refactor" description="需要最新 use case 和外掛說明時回官方頁面核驗。" href="https://developers.openai.com/codex/use-cases/ios-swiftui-view-refactor" />
</Cards>
