view-refactor

视图重构

概述

将 macOS 视图重构为小巧、明确且稳定的场景和视图类型。布局、选择、命令和设置默认使用原生 SwiftUI。只有在桌面行为确实需要时，才在边界处使用 AppKit。

核心准则

1) 明确建模场景

• 将应用拆分为有意义的场景根节点：主窗口、设置、实用工具窗口、检查器或菜单栏附加项。
• 不要让一个庞大的根视图悄然负责所有桌面界面。

2) 保持可预测的文件结构

• 除非文件已有更适用的局部约定，否则遵循以下顺序：
• 环境
• private/public let
• @State / 其他存储属性
• 计算属性 var（非视图）
• init
• body
• 计算视图构建器 / 其他视图辅助项
• 辅助函数 / 异步函数

2b) 按职责拆分文件

• 对于非简单应用，不要将整个应用、所有视图、模型、存储、网络客户端、进程客户端和辅助代码都放在一个 Swift 文件中。
• 仅在临时示例或代码片段非常小的情况下，才接受使用单个 Swift 文件：大约少于 50 行、只有一个屏幕、没有持久化、没有网络或进程客户端，也没有可复用模型。
• 使用 App/<AppName>App.swift，其中仅包含 @main 应用和 AppDelegate。
• 让 Views/ContentView.swift 专注于根布局和视图组合；将功能界面移至 Views/SidebarView.swift、Views/DetailView.swift 和 Views/ComposerView.swift 等文件。
• 将值类型和选择枚举移至 Models/*.swift，将存储移至 Stores/*.swift，将应用服务端、网络和进程客户端移至 Services/*.swift，将小型格式化工具、解析器和扩展移至 Support/*.swift。
• 保持文件精简，并以其包含的主要类型命名。

3) 优先使用专用子视图类型，而不是大量计算属性 some View 片段

• 将侧边栏行、详情面板、检查器或工具栏内容等有意义的桌面界面部分提取为专用子视图。
• 让计算属性 some View 辅助项保持精简且少量。
• 向子视图传递明确的数据、绑定和操作，而不是将整个场景模型传下去。

4) 保持选择和布局稳定

• 优先使用稳定的拆分布局或窗口布局，并在其中采用局部条件判断。
• 避免在选择发生变化时，在顶层切换差异巨大的根视图。
• 保持布局不变；由状态驱动其中的内容。

5) 将命令、工具栏和操作从 body 中提取出来

• 不要将复杂的按钮逻辑直接内嵌。
• 如果可以明确命名，就不要在同一代码块中混合命令路由、菜单状态和布局。
• 让 body 易于阅读，呈现 UI，而不是充当桌面视图控制器。

6) 有意使用场景存储和应用存储

• 只有在确实有助于还原场景时，才使用 @SceneStorage 存储每个窗口的临时状态。
• 使用 @AppStorage 存储持久偏好设置；不要用它存储仅在单个窗口中有意义的临时 UI 开关。
• 将场景所有的状态放在场景根节点附近。

7) 严格限制 AppKit 变通方案

• 如果存在 representable 或 NSWindow 桥接，将其隔离在小型包装器或辅助项中。
• 不要让 AppKit 引用扩散到无关的 SwiftUI 视图中。
• 如果桥接开始负责整个功能，请重新评估架构。

8) Observation 的用法

• 对于面向现代 macOS 目标版本的 @Observable 引用类型，在所属视图中将其存储为 @State。
• 将可观察对象显式传递给子视图。
• 对于较旧的部署目标，需要时改用 @StateObject 和 @ObservedObject。

工作流

1. 确定当前场景边界，以及文件是否承担了过多职责。
2. 按照清晰、可预测的自上而下结构重新组织文件。
3. 将桌面端专属部分提取为独立的子视图类型。
4. 围绕选择项、场景和命令来稳定根布局，而不是在顶层使用分支逻辑。
5. 将操作逻辑、命令路由和工具栏行为移入具名辅助项或独立类型。
6. 收紧 AppKit 桥接，使命令式边界精简且明确。
7. 除非请求明确要求同时进行结构和行为更改，否则保持行为不变。

重构清单

• 添加更多 UI 之前，先拆分过大的视图文件。
• 将纯模型、标识符和选择枚举移出视图文件。
• 将 Process、URLSession、app-server 和平台客户端代码从 SwiftUI 视图移至 Services/。
• 保持 AppDelegate 和 @main 应用入口精简。
• 每次完成重要拆分后都进行构建，以便将编译错误控制在局部范围内。

常见异味

• 根视图混杂了窗口框架、设置、工具栏代码、命令处理和详情布局。
• 单个应用文件混杂了应用入口、根布局、功能视图、模型、存储、服务客户端和支持扩展。
• 在 Mac 侧边栏—详情布局中强行套用 iOS 风格的推送导航。
• 使用多个布尔值来表示互斥的检查器、工作表或实用工具窗口。
• AppKit 对象在多个 SwiftUI 层之间传递，却没有明确的所有权依据。
• 用大型计算型视图片段代替真正的子视图。

说明

• 良好的 macOS 重构应让场景结构、选择流程和命令归属一目了然。
• 如果问题本质上是缺少桌面端模式，请使用 swiftui-patterns。
• 如果问题本质上是与 AppKit 的边界，请使用 appkit-interop。