guide-swiftui-ui-patterns

Guide Skill — これは API リファレンスドキュメントではなく、専門的なワークフロー／パターンガイドです。 もとは Thomas Ricouard による Dimillian/Skills です。MIT License。

SwiftUI UI パターン

クイックスタート

目標に合わせて、トラックを選択してください。

既存のプロジェクト

• 機能または画面と、主要なインタラクションモデル（リスト、詳細、エディター、設定、タブ）を特定します。
• rg "TabView\(" などを使ってリポジトリ内の近い例を探し、最も近い SwiftUI ビューを読みます。
• ローカルの規約を適用します。SwiftUI ネイティブの状態管理を優先し、可能な場合は状態をローカルに保ち、共有依存関係には環境インジェクションを使用します。
• references/components-index.md から該当するコンポーネントのリファレンスを選び、そのガイダンスに従います。
• ドラッグや、プライマリコンテンツをスクロールして画面外に移動する操作によって副次的なコンテンツが表示される場合は、ジェスチャーを手動で実装する前に references/scroll-reveal.md を読みます。
• 小さく、役割を絞ったサブビューと、SwiftUI ネイティブのデータフローを使ってビューを構築します。

新規プロジェクトのスキャフォールディング

• references/app-wiring.md から始め、TabView + NavigationStack + シートを接続します。
• 提供されているスケルトンを基に、最小限の AppTab と RouterPath を追加します。
• 最初に必要な UI に応じて、次のコンポーネントリファレンス（TabView、NavigationStack、シート）を選びます。
• 画面を追加するたびに、ルートとシートの enum を拡張します。

一般的なルール

• 最新の SwiftUI 状態管理（@State、@Binding、@Observable、@Environment）を使用し、不要なビューモデルは避けます。
• デプロイメントターゲットに iOS 16 以前が含まれ、iOS 17 で導入された Observation API を使用できない場合は、ObservableObject に切り替えます。ルートでの所有には @StateObject、注入されたオブジェクトの監視には @ObservedObject、本当にアプリレベルで共有される状態に限って @EnvironmentObject を使用します。
• 合成を優先し、ビューは小さく、役割を絞ったものにします。
• .task と明示的な読み込み／エラー状態を使って async/await を使用します。再起動、キャンセル、デバウンスのガイダンスについては、references/async-state.md を読みます。
• 共有アプリサービスは @Environment に保持しますが、機能ローカルの依存関係とモデルには、明示的なイニシャライザーによるインジェクションを優先します。ルートの接続パターンについては、references/app-wiring.md を読みます。
• デプロイメントターゲットに適合する最新の SwiftUI API を優先し、パターンが依存する最小 OS バージョンを明記します。
• レガシーファイルを編集する場合に限り、既存のレガシーパターンを維持します。
• プロジェクトのフォーマッターとスタイルガイドに従います。
• シート：状態が選択されたモデルを表す場合は、.sheet(isPresented:) より .sheet(item:) を優先します。シートの本文内で if let を使うのは避けます。シートは自身のアクションを持たせ、onCancel／onConfirm クロージャーを渡すのではなく、内部で dismiss() を呼び出すようにします。
• スクロール駆動の表示：スクロールオフセットから正規化された進捗値を導出し、その単一の信頼できる情報源からビジュアル状態を制御することを優先します。スクロールだけではインタラクションを表現できない場合を除き、並行するジェスチャー状態マシンは避けます。

状態の所有権の概要

所有権モデルに合った、最も適用範囲の狭い状態管理手段を使用します。

シナリオ	推奨パターン
1 つのビューが所有するローカル UI 状態	@State
子ビューが親所有の値型の状態を変更する	@Binding
iOS 17 以降でルートが所有する参照モデル	@Observable 型を使った @State
iOS 17 以降で、子ビューが注入された @Observable モデルを読み書きする	保存プロパティとして明示的に渡す
共有アプリサービスまたは設定	@Environment(Type.self)
iOS 16 以前のレガシー参照モデル	ルートでは @StateObject、注入時は @ObservedObject

まず所有権の場所を決め、そのあとでラッパーを選びます。通常の値型状態で十分な場合に、参照モデルを導入しないでください。

横断的なリファレンス

• references/navigationstack.md：ナビゲーションの所有権、タブごとの履歴、列挙型によるルーティング。
• references/sheets.md：モーダル表示の一元管理、列挙型によるシートの制御。
• references/deeplinks.md：URL の処理、外部リンクからアプリ内の画面へのルーティング。
• references/app-wiring.md：ルート依存関係グラフ、環境の使用方法、アプリシェルの接続。
• references/async-state.md：.task、.task(id:)、キャンセル、デバウンス、非同期 UI の状態。
• references/previews.md：#Preview、フィクスチャ、モック環境、独立したプレビューのセットアップ。
• references/performance.md：安定した識別子、監視のスコープ、遅延コンテナー、レンダリングコストのガードレール。

アンチパターン

• レイアウト、ビジネスロジック、ネットワーク通信、ルーティング、書式設定を 1 つのファイルに混在させた巨大なビュー。
• 相互排他的なシート、アラート、ナビゲーション先の制御に、複数のブール値フラグを使うこと。
• ビューのライフサイクルフックや注入されたモデル／サービスではなく、body によって駆動されるコードパス内で直接、サービスを呼び出すこと。
• より適切なコンポジションで解決すべき型の不一致を回避するために、AnyView を使うこと。
• 明確な所有権上の理由がないまま、共有依存関係をすべて @EnvironmentObject やグローバルルーターにすること。

新しい SwiftUI ビューのワークフロー

1. UI コードを書く前に、ビューの状態、所有権の所在、最低 OS 要件を定義します。
2. @Environment に含める依存関係と、イニシャライザーの明示的な入力として扱う依存関係を特定します。
3. ビュー階層、ルーティングモデル、表示箇所の概要をまとめ、繰り返し使う部分はサブビューに切り出します。複雑なナビゲーションについては、references/navigationstack.md、references/sheets.md、references/deeplinks.md を参照してください。先に進む前にビルドし、コンパイラーエラーがないことを確認してください。
4. 必要に応じて、明示的な読み込み状態とエラー状態を加え、.task または .task(id:) で非同期読み込みを実装します。入力の変更やキャンセルに関わる作業では、references/async-state.md を参照してください。
5. 主要な状態と副次的な状態のプレビューを追加し、UI が操作可能な場合はアクセシビリティラベルまたは識別子を追加します。フィクスチャや注入されたモック依存関係が必要なビューでは、references/previews.md を参照してください。
6. ビルドで検証します。コンパイラーエラーがないこと、プレビューがクラッシュせずに表示されること、状態の変更が正しく伝播することを確認し、リストの識別子や監視スコープが不要な再描画を引き起こさないかを確認します。画面が大規模、スクロール量が多い、または更新頻度が高い場合は、references/performance.md を参照してください。SwiftUI でよくあるコンパイルエラー（@State 注釈の欠落、ViewBuilder クロージャーの曖昧さ、ジェネリック型の不一致など）は、呼び出し側を更新する前に解決してください。ビルドに失敗した場合： エラーメッセージをよく読み、特定された問題を修正してから、次の手順に進む前に再ビルドしてください。プレビューがクラッシュする場合は、問題のサブビューを切り分け、その状態の初期化が有効であることを確認し、続行する前にプレビューを再実行してください。

コンポーネントのリファレンス

エントリーポイントとして references/components-index.md を使用します。各コンポーネントのリファレンスには、以下を含めてください。

• 目的と最適な使用シナリオ。
• ローカルの規約に沿った最小限の使用例。
• 注意点とパフォーマンスに関する注記。
• 現在のリポジトリ内にある既存の例へのパス。

新しいコンポーネントリファレンスの追加

• references/<component>.md を作成します。
• 簡潔で実用的な内容にし、現在のリポジトリ内の具体的なファイルにリンクします。
• references/components-index.md を更新して、新しい項目を追加します。