SwiftUI ナビゲーション は何をしますか?
このスキルを使用するタイミング
以下の場合に使用します:
- ナビゲーションアーキテクチャの選択(NavigationStack vs NavigationSplitView vs TabView)
- NavigationPath を使用したプログラムによるナビゲーションの実装
- ディープリンクと URL ルーティングの設定
- ナビゲーションの状態復元の実装
- タブ/サイドバーパターンの採用(iOS 18+)
- コーディネーター/ルーターパターンの実装
- 出荷前のナビゲーション実装のコードレビューの依頼
関連スキル
axiom-swiftui-nav-diagを使用して、ナビゲーション障害の体系的なトラブルシューティングを行うaxiom-swiftui-nav-refを使用して、包括的な API リファレンス(タブのカスタマイズ、iOS 26+ の機能を含む)とすべての WWDC サンプルを参照する
プロンプト例
これらは、このスキルが回答するために設計された、開発者が実際に尋ねる質問です:
1. 「自分のアプリには NavigationStack と NavigationSplitView のどちらを使うべきですか?」
-> このスキルは、デバイスのターゲット、コンテンツ階層の深さ、マルチプラットフォームの要件に基づいた決定木を提供します
2. 「SwiftUI でプログラム的にナビゲーションするにはどうすればよいですか?」
-> このスキルは、プッシュ、ポップ、ポップトゥルート、ディープリンクのための NavigationPath 操作パターンを示します
3. 「ディープリンクが機能しません。アプリは開きますが、間違った画面が表示されます。」
-> このスキルは、URL 解析パターン、パス構築の順序、onOpenURL のタイミング問題をカバーします
4. 「アプリがバックグラウンドに移行すると、ナビゲーション状態が失われます。」
-> このスキルは、Codable NavigationPath、SceneStorage による永続化、クラッシュ耐性のある復元を実演します
5. 「SwiftUI でコーディネーターパターンを実装するにはどうすればよいですか?」
-> このスキルは、コーディネーターが価値をもたらす場合と複雑性を増す場合の指針とともに、ルーターパターンの例を提供します
レッドフラグ — 防止すべきアンチパターン
以下のいずれかを行っている場合は、直ちに止めて、このスキルのパターンを使用してください:
❌ 絶対に行ってはいけないこと
1. iOS 16+ で非推奨の NavigationView を使用する
// ❌ 間違い — 非推奨、iOS 16+ では動作が異なる
NavigationView {
List { ... }
}
.navigationViewStyle(.stack)
なぜ失敗するのか NavigationView は iOS 16 以降で非推奨です。NavigationPath をサポートしていないため、プログラムによるナビゲーションとディープリンクが信頼できません。iOS バージョン間で動作が異なり、バグの原因になります。
2. プログラムによるナビゲーションにビューベースの NavigationLink を使用する
// ❌ 間違い — プログラムで制御できない
NavigationLink("レシピ") {
RecipeDetail(recipe: recipe) // ビューの宛先、値ではない
}
なぜ失敗するのか ビューベースのリンクはプログラムで制御できません。この宛先にディープリンクしたりポップしたりする方法がありません。iOS 16 以降で非推奨です。
3. 遅延コンテナ内に navigationDestination を配置する
// ❌ 間違い — 必要なときにロードされていない可能性がある
LazyVGrid(columns: columns) {
ForEach(items) { item in
NavigationLink(value: item) { ... }
.navigationDestination(for: Item.self) { item in // こうしてはいけない
ItemDetail(item: item)
}
}
}
なぜ失敗するのか 遅延コンテナはすべてのビューを即座にロードしません。navigationDestination が NavigationStack から見えない可能性があり、ナビゲーションが黙って失敗します。
4. 復元のために完全なモデルオブジェクトを NavigationPath に保存する
// ❌ 間違い — データが重複し、復元時に古くなる
class NavigationModel: Codable {
var path: [Recipe] = [] // 完全な Recipe オブジェクト
}
なぜ失敗するのか すでにモデルにあるデータが重複します。復元時に、Recipe データが古くなっている可能性があります(他の場所で編集/削除された)。ID を使用して現在のデータに解決してください。
5. MainActor の外部で NavigationPath を変更する
// ❌ 間違い — メインスレッド外での UI 更新
Task.detached {
await viewModel.path.append(recipe) // バックグラウンドスレッド
}
なぜ失敗するのか NavigationPath は UI にバインドされています。変更は MainActor 上で行われなければならず、そうしないとナビゲーション状態が破損します。クラッシュや黙った失敗を引き起こす可能性があります。
6. ナビゲーション状態に @MainActor 分離がない
// ❌ 間違い — MainActor 分離されていない
class Router: ObservableObject {
@Published var path = NavigationPath() // @MainActor なし
}
なぜ失敗するのか Swift 6 の厳格な並行性チェックでは、SwiftUI ビューからアクセスされる @Published プロパティには MainActor 分離が必要です。データ競合の警告や潜在的なクラッシュを引き起こします。
7. マルチタブアプリでナビゲーション状態を処理しない
// ❌ 間違い — タブ間で NavigationPath が共有される
TabView {
Tab("ホーム") { HomeView() }
Tab("設定") { SettingsView() }
}
// すべてのタブが同じ NavigationStack を共有 — 間違い!
なぜ失敗するのか 各タブは独自の NavigationStack を持つべきで、タブ切り替え時にナビゲーション状態を保持します。共有状態は混乱を招く UX を引き起こします。
8. NavigationPath のデコードエラーを無視する
// ❌ 間違い — 無効なデータでクラッシュする
let path = NavigationPath(try! decoder.decode(NavigationPath.CodableRepresentation.self, from: data))
なぜ失敗するのか ユーザーがパスにあったアイテムを削除している可能性があります。スキーマが変更されている可能性があります。強制アンラップは復元時にクラッシュを引き起こします。
必須の最初のステップ
ナビゲーションを実装する前に、必ずこれらのステップを完了してください:
// ステップ 1: ナビゲーション構造を特定する
// 質問: シングルスタック?マルチカラム?タブベースでタブごとにナビゲーション?
// コードを書く前に回答を記録する
// ステップ 2: 構造に基づいてコンテナを選択する
// シングルスタック(iPhone プライマリ): NavigationStack
// マルチカラム(iPad/Mac プライマリ): NavigationSplitView
// タブベース: タブごとに NavigationStack を持つ TabView
// ステップ 3: ナビゲーションの値型を定義する
// NavigationStack にプッシュされるすべての値は Hashable でなければならない
// ディープリンク/復元の場合は、さらに Codable である必要がある
struct Recipe: Hashable, Codable, Identifiable { ... }
// ステップ 4: ディープリンク URL を計画する(必要な場合)
// myapp://recipe/{id}
// myapp://category/{name}/recipe/{id}
// ステップ 5: 状態復元を計画する(必要な場合)
// SceneStorage を使用しますか?どのデータを Codable にする必要がありますか?
クイック決定木
ナビゲーションが必要?
├─ マルチカラムインターフェース(iPad/Mac プライマリ)?
│ └─ NavigationSplitView
│ ├─ 詳細列でドリルダウンが必要?
│ │ └─ 詳細内に NavigationStack(パターン 3)
│ └─ 選択のみの詳細?
│ └─ 選択バインディングのみ(パターン 2)
├─ タブベースのアプリ?
│ └─ TabView
│ ├─ 各タブでドリルダウンが必要?
│ │ └─ タブごとに NavigationStack(パターン 4)
│ └─ iPad サイドバーエクスペリエンス?
│ └─ .tabViewStyle(.sidebarAdaptable)(パターン 5)
└─ シングルカラムスタック?
└─ NavigationStack
├─ ディープリンクが必要?
│ └─ NavigationPath を使用(パターン 1b)
└─ 単純なプッシュ/ポップ?
└─ 型付き配列パス(パターン 1a)
状態復元が必要?
└─ SceneStorage + Codable NavigationPath(パターン 6)
コーディネーターの抽象化が必要?
├─ 複雑な条件付きフロー?
├─ ナビゲーションロジックのテストが必要?
├─ 多くの画面でナビゲーションを共有する?
└─ いずれかに YES → ルーターパターン(パターン 7)
すべて NO → NavigationPath を直接使用する
パターン 1a: 基本の NavigationStack
いつ: 単純なプッシュ/ポップナビゲーション、すべての宛先が同じ型
所要時間: 5〜10 分
struct RecipeList: View {
@State private var path: [Recipe] = []
var body: some View {
NavigationStack(path: $path) {
List(recipes) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationTitle("レシピ")
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
}
// プログラムによるナビゲーション
func showRecipe(_ recipe: Recipe) {
path.append(recipe)
}
func popToRoot() {
path.removeAll()
}
}
重要なポイント:
- すべての値が同じ型の場合は型付き配列
[Recipe] - 値ベースの
NavigationLink(title, value:) navigationDestination(for:)は遅延コンテナの外側に
パターン 1b: ディープリンク付き NavigationStack
いつ: 複数の宛先型、URL ベースのディープリンク
所要時間: 15〜20 分
struct ContentView: View {
@State private var path = NavigationPath()
var body: some View {
NavigationStack(path: $path) {
HomeView()
.navigationDestination(for: Category.self) { category in
CategoryView(category: category)
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
.onOpenURL { url in
handleDeepLink(url)
}
}
func handleDeepLink(_ url: URL) {
// URL: myapp://category/desserts/recipe/apple-pie
path.removeLast(path.count) // 最初にルートにポップ
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return }
let segments = components.path.split(separator: "/").map(String.init)
var index = 0
while index < segments.count - 1 {
switch segments[index] {
case "category":
if let category = Category(rawValue: segments[index + 1]) {
path.append(category)
}
index += 2
case "recipe":
if let recipe = dataModel.recipe(named: segments[index + 1]) {
path.append(recipe)
}
index += 2
default:
index += 1
}
}
}
}
重要なポイント:
- 異種型には
NavigationPath - ディープリンクパスを構築する前にルートにポップ
- 正しい順序(親 → 子)でパスを構築する
パターン 2: NavigationSplitView 選択ベース
いつ: 詳細に選択されたアイテムを表示するマルチカラムレイアウト
所要時間: 10〜15 分
struct MultiColumnView: View {
@State private var selectedCategory: Category?
@State private var selectedRecipe: Recipe?
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("カテゴリ")
} content: {
if let category = selectedCategory {
List(recipes(in: category), selection: $selectedRecipe) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationTitle(category.name)
} else {
Text("カテゴリを選択")
}
} detail: {
if let recipe = selectedRecipe {
RecipeDetail(recipe: recipe)
} else {
Text("レシピを選択")
}
}
}
}
重要なポイント:
- List の
selection: $bindingが列の選択に接続 - 値を提示するリンクは選択を自動的に更新
- iPhone ではシングルスタックに適応
パターン 3: 詳細にスタックを持つ NavigationSplitView
いつ: 詳細でドリルダウン機能を持つマルチカラム
所要時間: 20〜25 分
struct GridWithDrillDown: View {
@State private var selectedCategory: Category?
@State private var path: [Recipe] = []
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("カテゴリ")
} detail: {
NavigationStack(path: $path) {
if let category = selectedCategory {
RecipeGrid(category: category)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
} else {
Text("カテゴリを選択")
}
}
}
}
}
重要なポイント:
- 詳細列内の NavigationStack
- サイドバーを保持しながら Grid → Detail のドリルダウン
- ドリルダウン用の個別のパス、サイドバー用の選択
パターン 4: タブごとの NavigationStack を持つ TabView
いつ: 各タブが独自のナビゲーションを持つタブベースのアプリ
所要時間: 15〜20 分
struct TabBasedApp: View {
var body: some View {
TabView {
Tab("ホーム", systemImage: "house") {
NavigationStack {
HomeView()
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item)
}
}
}
Tab("検索", systemImage: "magnifyingglass") {
NavigationStack {
SearchView()
}
}
Tab("設定", systemImage: "gear") {
NavigationStack {
SettingsView()
}
}
}
}
}
重要なポイント:
- 各タブに独自の NavigationStack
- タブ切り替え時にナビゲーション状態が保持される
- iOS 18+ の systemImage 付き Tab 構文
パターン 5: サイドバー適応型 TabView(iOS 18+)
いつ: iPhone ではタブバー、iPad ではサイドバー
所要時間: 20〜25 分
struct AdaptableApp: View {
var body: some View {
TabView {
Tab("今すぐ見る", systemImage: "play") {
WatchNowView()
}
Tab("ライブラリ", systemImage: "books.vertical") {
LibraryView()
}
TabSection("コレクション") {
Tab("お気に入り", systemImage: "star") {
FavoritesView()
}
Tab("最近追加", systemImage: "clock") {
RecentView()
}
}
Tab(role: .search) {
SearchView()
}
}
.tabViewStyle(.sidebarAdaptable)
}
}
重要なポイント:
.tabViewStyle(.sidebarAdaptable)により iPad でサイドバーが有効になるTabSectionはサイドバーに折りたたみ可能なグループを作成するTab(role: .search)は特別な配置を得る
パターン 6: 状態の復元
いつ: アプリがバックグラウンドまたは終了後にナビゲーション状態を維持する必要がある場合
所要時間: 20〜30 分
struct RestorableApp: View {
@SceneStorage("navigationPath") private var pathData: Data?
@State private var path = NavigationPath()
var body: some View {
NavigationStack(path: $path) {
ContentView()
}
.onAppear {
restorePath()
}
.onChange(of: path) { _, _ in
savePath()
}
}
private func savePath() {
guard let representation = path.codable else { return }
pathData = try? JSONEncoder().encode(representation)
}
private func restorePath() {
guard let data = pathData,
let representation = try? JSONDecoder().decode(
NavigationPath.CodableRepresentation.self, from: data
) else { return }
path = NavigationPath(representation)
}
}
重要なポイント:
- SceneStorage は状態の復元に使用される
- CodableRepresentation で安全にデコードする(強制アンラップはしない)
- Codable でない型の場合は、可逆的 ID ベースのエンコーディングを検討する
- このパターンはパス内のすべての値が Codable であることを前提とする
パターン 7: ルーターパターン
いつ: 複雑な条件付きフロー、テスト容易性、複数画面にわたる共有ナビゲーションロジック
所要時間: 30〜45 分
@MainActor
@Observable
final class Router {
var path = NavigationPath()
func navigate(to destination: AppDestination) {
path.append(destination)
}
func popToRoot() {
path.removeLast(path.count)
}
func handleDeepLink(_ url: URL) {
popToRoot()
// ディープリンクロジックをここに
// パス内に適切な AppDestination 値を追加
}
}
struct RouterView: View {
@State private var router = Router()
var body: some View {
NavigationStack(path: $router.path) {
HomeView()
.environment(router)
.navigationDestination(for: AppDestination.self) { destination in
// Switch ケースをここに配置
switch destination {
case .recipeDetail(let recipe):
RecipeDetail(recipe: recipe)
case .settings:
SettingsView()
}
}
}
}
}
enum AppDestination: Hashable {
case recipeDetail(Recipe)
case settings
}
重要なポイント:
- @Observable と @MainActor は Swift 6 の並行性要件のために必須
- 共通のアプリケーションディスティネーション enum が型安全性を提供
- ルーターは条件とビュー構築を集中管理する
- コーディネーターではなくルーターを優先する(SwiftUI ではよりシンプル)
パターン 8: タブベースのディープリンク
いつ: 特定のタブの特定のビューにディープリンクする必要があるタブベースのアプリ
所要時間: 25〜35 分
struct TabDeepLinkApp: View {
@State private var selectedTab: Tab = .home
@State private var homePath = NavigationPath()
@State private var searchPath = NavigationPath()
@State private var settingsPath = NavigationPath()
enum Tab: String, Hashable {
case home, search, settings
}
var body: some View {
TabView(selection: $selectedTab) {
Tab("ホーム", systemImage: "house", value: Tab.home) {
NavigationStack(path: $homePath) {
HomeView()
.navigationDestination(for: DeepLinkDestination.self) { ... }
}
}
Tab("検索", systemImage: "magnifyingglass", value: Tab.search) {
NavigationStack(path: $searchPath) {
SearchView()
.navigationDestination(for: DeepLinkDestination.self) { ... }
}
}
Tab("設定", systemImage: "gear", value: Tab.settings) {
NavigationStack(path: $settingsPath) {
SettingsView()
.navigationDestination(for: DeepLinkDestination.self) { ... }
}
}
}
.onOpenURL { url in handleDeepLink(url) }
}
func handleDeepLink(_ url: URL) {
guard let tab = parseTab(from: url) else { return }
selectedTab = tab
// 適切なパスにディープリンク宛先を追加
}
}
重要なポイント:
- タブごとに個別の NavigationPath
- selectedTab を設定して正しいタブに切り替える
- 各タブスタックに適切なディープリンク宛先を追加する
よくある質問
Q: NavigationStack と NavigationSplitView のどちらを選ぶべきですか?
A: クイック決定木を使用してください。iPhone を主なターゲットとする単一列のアプリには NavigationStack を。iPad/Mac でマルチカラムレイアウトが必要な場合、またはアプリが異なるデバイスサイズに適応する必要がある場合は NavigationSplitView を選択してください。
Q: プログラムでルートにポップするにはどうすればよいですか?
A: パス配列で path.removeAll()(型付きパスの場合)、または NavigationPath で path.removeLast(path.count) を使用します。
Q: ディープリンクが機能しないのはなぜですか?
A: 一般的な問題: (1) ディープリンクパスを構築する前にルートにポップしていない、(2) navigationDestination が遅延コンテナ内にある、(3) パスの値が正しく Hashable/Codable でない、(4) onOpenURL のタイミングの問題。
Q: タブビューアプリでナビゲーション状態を復元するにはどうすればよいですか?
A: 各タブで SceneStorage を、そのタブのナビゲーションパスに対して使用します。タブの選択も SceneStorage に保存します。
Q: iOS 18 の新しいタブAPIは、より複雑なサイドバー構成を可能にしますか?
A: はい。TabSection と .sidebarAdaptable タブビュースタイルにより、セクション化された折りたたみ可能なサイドバーが可能になり、macOS の経験をより適切に模倣できます。
深堀りトピック
-
並行性とナビゲーション: Swift 6 では、NavigationPath と @Published プロパティには @MainActor 分離が必要です。これによりデータ競合のバグが防止されます。
-
パフォーマンスの考慮事項: 各 navigationDestination 修飾子はコストを追加します。可能な限りまとめて、遅延コンテナ内には配置しないでください。
-
テスト: Router パターンを使用すると、ナビゲーションロジックをビューから分離して単体テストできます。
-
アクセシビリティ: NavigationStack はナビゲーションポイント間の VoiceOver フォーカスの移動を自動的に処理しますは、カスタム遷移は追加の作業が必要な場合があります。
-
Braze などのサードパーティ SDK: プッシュ通知経由のディープリンクは、動的な URL を処理するためにカスタム routing 層が必要な場合があります。
関連リソース
- [SwiftUI ナビゲーション API リファレンス(axiom-swiftui-nav-ref)]
- [ナビゲーション障害の診断(axiom-swiftui-nav-diag)]
- WWDC 2022: ナビゲーションの最新情報
- WWDC 2023: SwiftUI の進化