view-refactor

ビューのリファクタリング

概要

macOS のビューを、小さく、明示的で、安定したシーン型とビュー型に向けてリファクタリングします。レイアウト、選択、コマンド、設定には、標準でネイティブの SwiftUI を使用します。デスクトップの動作に本当に必要な狭い範囲に限り、AppKit を使用します。

基本ガイドライン

1) シーンを明示的にモデル化する

• アプリを、メインウィンドウ、設定、ユーティリティウィンドウ、インスペクター、メニューバーエクストラなど、意味のあるシーンのルートに分割します。
• 1つの巨大なルートビューに、デスクトップのすべての画面を暗黙的に所有させないでください。

2) 予測しやすいファイル構成にする

• ファイル内に、より確立されたローカルな慣例がすでにある場合を除き、次の順序に従います。
• Environment
• private／public let
• @State／その他の格納プロパティ
• 計算型 var（ビュー以外）
• init
• body
• 計算型ビュー構築子／その他のビュー用ヘルパー
• ヘルパー／非同期関数

2b) 責務ごとにファイルを分割する

• 小規模でないアプリでは、アプリ全体、すべてのビュー、モデル、ストア、ネットワーククライアント、プロセスクライアント、ヘルパーを1つの Swift ファイルにまとめないでください。
• 使い捨ての小さなサンプルやスニペットに限り、単一の Swift ファイルを使用します。目安は約50行未満、1画面、永続化なし、ネットワーク／プロセスクライアントなし、再利用可能なモデルなしです。
• App/<AppName>App.swift には @main アプリと AppDelegate のみを配置します。
• Views/ContentView.swift はルートレイアウトと構成に専念させ、機能ごとの UI は Views/SidebarView.swift、Views/DetailView.swift、Views/ComposerView.swift などのファイルに移します。
• 値型と選択用の列挙型は Models/*.swift に、ストアは Stores/*.swift に、アプリサーバー／ネットワーク／プロセスクライアントは Services/*.swift に、小規模なフォーマッター／リゾルバー／拡張は Support/*.swift に移します。
• ファイルは小さく保ち、含まれる主要な型にちなんだ名前を付けます。

3) 多数の計算型 some View の断片より、専用のサブビュー型を優先する

• サイドバーの行、詳細パネル、インスペクター、ツールバーのコンテンツなど、デスクトップ画面の意味のあるセクションを、目的に特化したサブビューとして切り出します。
• 計算型 some View のヘルパーは、小さく、必要最小限に保ちます。
• シーンモデル全体を渡すのではなく、明示的なデータ、バインディング、アクションをサブビューに渡します。

4) 選択とレイアウトを安定させる

• 1つの安定した分割レイアウトまたはウィンドウレイアウトを優先し、その内部に局所的な条件分岐を配置します。
• 選択が変わるたびに、まったく異なるルート間で最上位の分岐を切り替えることは避けます。
• レイアウトは一定に保ち、状態によってその内部のコンテンツを変化させます。

5) コマンド、ツールバー、アクションを body の外に切り出す

• 複雑なボタンのロジックをインラインで埋め込まないでください。
• 明確な名前を付けられる場合は、コマンドのルーティング、メニューの状態、レイアウトを同じブロックに混在させないでください。
• body はデスクトップ用のビューコントローラーではなく、UI として読みやすく保ちます。

6) シーンストレージとアプリストレージを意図的に使う

• シーンの復元に本当に役立つ場合は、ウィンドウごとの一時的な状態に @SceneStorage を使用します。
• 永続的な設定には @AppStorage を使用し、1つのウィンドウでのみ意味を持つ一時的な 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、アプリサーバー、プラットフォームクライアントのコードを SwiftUI ビューから Services/ に移します。
• AppDelegate と @main のアプリエントリーポイントは最小限に保ちます。
• 大きな分割を行うたびにビルドし、コンパイルエラーが局所化されるようにします。

よくある問題の兆候

• ウィンドウの骨組み、設定、ツールバーのコード、コマンド処理、詳細レイアウトを混在させたルートビュー。
• アプリのエントリーポイント、ルートレイアウト、機能ビュー、モデル、ストア、サービスクライアント、補助的な拡張を混在させた単一のアプリファイル。
• Mac のサイドバーと詳細表示の問題に、iOS 風のプッシュナビゲーションを無理に適用している。
• 相互に排他的なインスペクター、シート、ユーティリティウィンドウを表す複数のブール値。
• 明確な所有権の理由もなく、AppKit オブジェクトが複数の SwiftUI レイヤーを通じて渡されている。
• 実際のサブビューの代わりに使われている、大きな計算プロパティのビュー断片。

補足

• 優れた macOS のリファクタリングでは、シーン構成、選択の流れ、コマンドの責務が明確になります。
• 根本的な問題がデスクトップ向けパターンの不足である場合は、swiftui-patterns を使用します。
• 根本的な問題が AppKit との境界にある場合は、appkit-interop を使用します。