SwiftUI UI パターン

クイックスタート

目標に基づいてトラックを選択します：

既存プロジェクト

• 機能またはスクリーンと主要なインタラクションモデル（リスト、詳細、エディタ、設定、タブ付き）を特定します。
• rg "TabView\(" のような検索でリポジトリ内の近い例を見つけ、最も近い SwiftUI ビューを読みます。
• ローカルの規約を適用します。SwiftUI ネイティブの状態を優先し、可能な限り状態をローカルに保ち、共有依存関係に環境注入を使用します。
• references/components-index.md から関連するコンポーネントリファレンスを選択し、そのガイダンスに従います。
• インタラクションが主要コンテンツをドラッグまたはスクロールして secondary content を明かす場合、ジェスチャーを手動で実装する前に references/scroll-reveal.md を読みます。
• 小さく焦点を絞ったサブビューと SwiftUI ネイティブなデータフローでビューを構築します。

新規プロジェクトスカフォルディング

• references/app-wiring.md を使用して TabView + NavigationStack + sheets をワイアリングします。
• 提供されているスケルトンに基づいて、最小限の AppTab と RouterPath を追加します。
• 最初に必要な UI に基づいてコンポーネントリファレンスを選択します（TabView、NavigationStack、Sheets）。
• 新しいスクリーンが追加されるに従い、route と sheet enum を拡張します。

従うべき一般的なルール

• モダン SwiftUI state（@State、@Binding、@Observable、@Environment）を使用し、不要なビューモデルを避けます。
• デプロイメントターゲットが iOS 16 以前を含み、iOS 17 で導入された Observation API を使用できない場合、root 所有に対して @StateObject を、注入された観察に対して @ObservedObject を、真に共有されるアプリレベルの状態に対してのみ @EnvironmentObject を使用する ObservableObject にフォールバックします。
• 構成を優先します。ビューを小さく焦点を絞ったままにします。
• async/await を .task で使用し、明示的なローディング/エラー状態を使用します。リスタート、キャンセル、デバウンシングのガイダンスについては、references/async-state.md を読んでください。
• 共有アプリサービスを @Environment に保ちますが、機能ローカルの依存関係とモデルには明示的なイニシャライザ注入を優先します。root ワイアリングパターンについては、references/app-wiring.md を読んでください。
• デプロイメントターゲットに適合する最新の SwiftUI API を優先し、パターンがそれに依存する場合は常に最小 OS を明記します。
• レガシーファイルを編集する場合のみ既存のレガシーパターンを保ちます。
• プロジェクトのフォーマッタとスタイルガイドに従います。
• Sheets: 状態が選択されたモデルを表す場合、.sheet(isPresented:) よりも .sheet(item:) を優先します。sheet body 内での if let を避けます。Sheet は自身のアクションを所有し、onCancel/onConfirm クロージャを転送する代わりに、内部で dismiss() を呼び出すべきです。
• スクロール駆動のリビール: スクロールオフセットから正規化された進捗値を導出し、その単一の真実のソースからビジュアル状態を駆動することを優先します。スクロール単独では相互作用を表現できない限り、並列ジェスチャーステートマシンを避けます。

状態所有権サマリー

所有権モデルに合致する最も狭い状態ツールを使用します：

シナリオ	推奨パターン
1 つのビューが所有するローカル UI 状態	@State
子が親所有の値状態を変異させる	@Binding
iOS 17+ で root が所有する参照モデル	@Observable タイプの @State
iOS 17+ で子が注入された @Observable モデルを読む、または変異させる	明示的に stored property として渡す
共有アプリサービスまたは設定	@Environment(Type.self)
iOS 16 以前のレガシー参照モデル	root では @StateObject、注入時には @ObservedObject

まず所有権の位置を選択してから、ラッパーを選びます。プレーンな値状態で十分な場合、参照モデルを導入しないでください。

クロスカッティングリファレンス

• references/navigationstack.md: ナビゲーション所有権、タブごとの履歴、および enum ルーティング。
• references/sheets.md: 一元的なモーダルプレゼンテーションと enum 駆動の sheet。
• references/deeplinks.md: URL ハンドリングとルーティング外部リンクをアプリの宛先に。
• references/app-wiring.md: root 依存関係グラフ、環境使用法、およびアプリシェルワイアリング。
• references/async-state.md: .task、.task(id:)、キャンセル、デバウンシング、および非同期 UI 状態。
• references/previews.md: #Preview、フィクスチャ、モック環境、および分離されたプレビュー設定。
• references/performance.md: 安定した識別、観察スコープ、遅延コンテナ、およびレンダーコストのガードレール。

アンチパターン

• レイアウト、ビジネスロジック、ネットワーキング、ルーティング、フォーマットを 1 つのファイルで混在させた巨大なビュー。
• 相互に排他的な sheet、alert、またはナビゲーション宛先に対する複数のブール値フラグ。
• ビュー ライフサイクルフックまたは注入されたモデル/サービスの代わりに、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 を新しいエントリで更新します。