Communitygithub.com

ComeOnOliver/skillshub

リファレンス — NavigationStack(iOS 16+)、NavigationSplitView(iOS 16+)、NavigationPath、ディープリンク、状態復元、Tab+ナビゲーション統合(iOS 18+)、Liquid Glassナビゲーション(iOS 26+)、コーディネーターパターンを網羅した包括的なSwiftUIナビゲーションガイド

skillshub とは?

このスキルは、iOS 16以降で導入されたSwiftUIのナビゲーションAPIに関する包括的なリファレンスを提供します。NavigationStack、NavigationSplitView、NavigationPathといったデータ駆動型のプログラム可能なナビゲーションを中心に、ディープリンク、状態復元、iOS 18のTab/Sidebar統合、そしてiOS 26のLiquid Glassデザインに至るまでの進化をカバーしています。各APIの具体的なコード例、ベストプラクティス、アンチパターンが詳細に説明されており、開発者はデータ駆動型のナビゲーションパターンを迅速に実装できます。また、UIKitのUINavigationControllerを使用すべき複雑なコーディネーターパターンとの比較も含まれており、プロジェクトの要件に応じた適切なアーキテクチャ選択を支援します。このスキルは、Claude Code、Cursor、CodexなどのAIエージェントと組み合わせて使用することを想定しており、SwiftUIナビゲーションの実装やトラブルシューティングを効率化します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-nav-ref

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

SwiftUI ナビゲーション API リファレンス

概要

SwiftUI のナビゲーション API は、シンプルなスタックから複雑なマルチカラムレイアウトまで拡張可能な、データ駆動型でプログラム可能なナビゲーションを提供します。iOS 16(2022年)で NavigationStack と NavigationSplitView が導入され、iOS 18(2024年)で Tab/Sidebar の統合が進化し、iOS 26(2025年)で Liquid Glass デザインが洗練されました。

進化のタイムライン

  • 2022(iOS 16) NavigationStack、NavigationSplitView、NavigationPath、値ベースの NavigationLink
  • 2024(iOS 18) Tab/Sidebar の統合、sidebarAdaptable スタイル、ズームナビゲーション遷移
  • 2025(iOS 26) Liquid Glass ナビゲーションチャーム、ボトムアラインド検索、フローティングタブバー、backgroundExtensionEffect

主な機能

  • データ駆動型ナビゲーション NavigationPath はスタック状態を表現し、プログラムによるプッシュ/ポップやディープリンクを可能にします
  • マルチカラムレイアウト NavigationSplitView は自動的に適応します(iPad では3カラム、iPhone ではシングルスタック)
  • 状態復元 Codable 準拠の NavigationPath + SceneStorage でアプリ起動間の永続化を実現
  • Tab 統合 タブごとの NavigationStack でタブ切り替え時の状態を保持(iOS 18+)
  • Liquid Glass 自動ガラスナビゲーションバー、サイドバー、ツールバー(iOS 26+)

UIKit と比較した使用タイミング

  • SwiftUI ナビゲーション 新規アプリ、マルチプラットフォーム、シンプルなナビゲーションフロー → NavigationStack/SplitView を使用
  • UINavigationController 複雑なコーディネーターパターン、レガシーコード、特定の UIKit 機能 → UIKit を検討

関連スキル

  • axiom-swiftui-nav はアンチパターン、決定木、プレッシャーシナリオに使用
  • axiom-swiftui-nav-diag はナビゲーション問題の体系的なトラブルシューティングに使用

このスキルを使用すべきタイミング

このスキルは以下の場合に使用します:

  • ナビゲーション API の実装 NavigationStack、NavigationSplitView、NavigationPath、Tab+ナビゲーション
  • ディープリンクまたは状態復元 URL ルーティング、Codable 準拠 NavigationPath、SceneStorage
  • iOS 26+ の機能採用 Liquid Glass ナビゲーション、ボトムアラインド検索、タブバーの最小化
  • ナビゲーションアーキテクチャの選択 スタック vs SplitView vs コーディネーターパターン

API の進化

タイムライン

年iOS バージョン主な機能
2020iOS 14NavigationView(iOS 16で非推奨)
2022iOS 16NavigationStack、NavigationSplitView、NavigationPath、値ベースの NavigationLink
2024iOS 18Tab/Sidebar の統合、sidebarAdaptable、TabSection、ズーム遷移
2025iOS 26Liquid Glass ナビゲーション、backgroundExtensionEffect、tabBarMinimizeBehavior

NavigationView(非推奨)

NavigationView は iOS 16 以降で非推奨です。新しいコードでは NavigationStack(シングルカラムのプッシュ/ポップ)または NavigationSplitView(マルチカラム)のみを使用してください。主な改善点:単一の NavigationPath がリンクごとの isActive バインディングを置き換え、値ベースの型安全性、組み込みの Codable 状態復元。詳細は「新しいナビゲーションタイプへの移行」のドキュメントを参照してください。


NavigationStack 完全リファレンス

NavigationStack は、iPhone の設定や macOS のシステム設定のようなプッシュ/ポップインターフェースを表現します。

1.1 NavigationStack の作成

基本の NavigationStack

NavigationStack {
    List(Category.allCases) { category in
        NavigationLink(category.name, value: category)
    }
    .navigationTitle("Categories")
    .navigationDestination(for: Category.self) { category in
        CategoryDetail(category: category)
    }
}

パスバインディングを使用する方法(WWDC 2022, 6:05)

struct PushableStack: View {
    @State private var path: [Recipe] = []
    @StateObject private var dataModel = DataModel()

    var body: some View {
        NavigationStack(path: $path) {
            List(Category.allCases) { category in
                Section(category.localizedName) {
                    ForEach(dataModel.recipes(in: category)) { recipe in
                        NavigationLink(recipe.name, value: recipe)
                    }
                }
            }
            .navigationTitle("Categories")
            .navigationDestination(for: Recipe.self) { recipe in
                RecipeDetail(recipe: recipe)
            }
        }
        .environmentObject(dataModel)
    }
}

パスバインディング + 値を提示する NavigationLink + navigationDestination(for:) が、データ駆動型ナビゲーションパターンの核となります。

1.2 NavigationLink(値ベース)

値を提示する NavigationLink

// 正しい:値ベース(iOS 16+)
NavigationLink(recipe.name, value: recipe)

// 正しい:カスタムラベル付き
NavigationLink(value: recipe) {
    RecipeTile(recipe: recipe)
}

// 非推奨:ビューベース(iOS 13-15)
NavigationLink(recipe.name) {
    RecipeDetail(recipe: recipe)  // 新しいコードでは使用しないでください
}

NavigationLink と NavigationStack の動作メカニズム

  1. NavigationStack は path コレクションを保持する
  2. 値を提示するリンクをタップすると、その値が path に追加される
  3. NavigationStack は navigationDestination 修飾子を path の値にマッピングする
  4. 宛先マッピングに基づいてビューがスタックにプッシュされる

1.3 navigationDestination 修飾子

単一タイプ

.navigationDestination(for: Recipe.self) { recipe in
    RecipeDetail(recipe: recipe)
}

複数タイプ

NavigationStack(path: $path) {
    RootView()
        .navigationDestination(for: Recipe.self) { recipe in
            RecipeDetail(recipe: recipe)
        }
        .navigationDestination(for: Category.self) { category in
            CategoryList(category: category)
        }
        .navigationDestination(for: Chef.self) { chef in
            ChefProfile(chef: chef)
        }
}

ナビゲーションのアンチパターン

  • 同じ NavigationStack 階層内で navigationDestination(for:) と NavigationLink(destination:) を混在させないでください — 未定義動作の原因となります
  • データタイプごとに navigationDestination(for:) を1回だけ登録してください — 重複すると誤ったビューが表示されます

配置ルール

  • navigationDestination は遅延コンテナの外側に配置してください(ForEach の内部には配置しない)
  • コードの整理のため、関連する NavigationLink の近くに配置してください
  • NavigationStack の階層内に配置する必要があります
// 正しい:遅延コンテナの外側
ScrollView {
    LazyVGrid(columns: columns) {
        ForEach(recipes) { recipe in
            NavigationLink(value: recipe) {
                RecipeTile(recipe: recipe)
            }
        }
    }
}
.navigationDestination(for: Recipe.self) { recipe in
    RecipeDetail(recipe: recipe)
}

// 間違い:ForEach の内部(ロードされない可能性があります)
ForEach(recipes) { recipe in
    NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
        .navigationDestination(for: Recipe.self) { r in  // こうしないでください
            RecipeDetail(recipe: r)
        }
}

1.4 NavigationPath

NavigationPath は、異種混在のナビゲーションスタックのための型消去されたコレクションです。

型付き配列 vs NavigationPath

// 型付き配列:すべての値が同じ型
@State private var path: [Recipe] = []

// NavigationPath:異なる型が混在可能
@State private var path = NavigationPath()

NavigationPath の操作

// 値を追加
path.append(recipe)

// ひとつ前へ戻る
path.removeLast()

// ルートに戻る
path.removeLast(path.count)
// または
path = NavigationPath()

// カウントを確認
if path.count > 0 { ... }

// ディープリンク:複数の値を設定
path.append(category)
path.append(recipe)

Codable サポート

// NavigationPath は、すべての値が Codable の場合に Codable に準拠します
@State private var path = NavigationPath()

// エンコード
let data = try JSONEncoder().encode(path.codable)

// デコード
let codableRep = try JSONDecoder().decode(NavigationPath.CodableRepresentation.self, from: data)
path = NavigationPath(codableRep)

NavigationSplitView 完全リファレンス

NavigationSplitView は、デバイスの画面サイズに応じて適応するマルチカラムレイアウトを作成します。

2.1 2カラムレイアウト

基本の2カラム(WWDC 2022, 10:40)

struct MultipleColumns: View {
    @State private var selectedCategory: Category?
    @State private var selectedRecipe: Recipe?
    @StateObject private var dataModel = DataModel()

    var body: some View {
        NavigationSplitView {
            List(Category.allCases, selection: $selectedCategory) { category in
                NavigationLink(category.localizedName, value: category)
            }
            .navigationTitle("Categories")
        } detail: {
            if let recipe = selectedRecipe {
                RecipeDetail(recipe: recipe)
            } else {
                Text("Select a recipe")
            }
        }
    }
}

2.2 3カラムレイアウト

サイドバーと詳細の間に content: クロージャを追加して中央のカラムを配置します:

NavigationSplitView {
    List(Category.allCases, selection: $selectedCategory) { category in
        NavigationLink(category.localizedName, value: category)
    }
} content: {
    List(dataModel.recipes(in: selectedCategory), selection: $selectedRecipe) { recipe in
        NavigationLink(recipe.name, value: recipe)
    }
} detail: {
    RecipeDetail(recipe: selectedRecipe)
}

2.3 NavigationSplitView と NavigationStack の組み合わせ

詳細カラム内に NavigationStack(path:) を配置して、サイドバーの選択状態を保持しながらグリッドから詳細へのドリルダウンを実現します:

NavigationSplitView {
    List(Category.allCases, selection: $selectedCategory) { ... }
} detail: {
    NavigationStack(path: $path) {
        RecipeGrid(category: selectedCategory)
            .navigationDestination(for: Recipe.self) { recipe in
                RecipeDetail(recipe: recipe)
            }
    }
}

2.4 カラムの表示状態

@State private var columnVisibility: NavigationSplitViewVisibility = .all

NavigationSplitView(columnVisibility: $columnVisibility) {
    Sidebar()
} content: {
    Content()
} detail: {
    Detail()
}

// プログラムで表示状態を制御
columnVisibility = .detailOnly  // サイドバーとコンテンツを非表示
columnVisibility = .all          // すべてのカラムを表示
columnVisibility = .automatic    // システムが決定

2.5 自動適応

NavigationSplitView は自動的に適応します:

  • iPad ランドスケープ すべてのカラムを表示(設定に依存)
  • iPad ポートレート / Slide Over オーバーレイまたはシングルカラムに折りたたむ
  • iPhone シングルナビゲーションスタック
  • Apple Watch / TV シングルナビゲーションスタック

選択の変更は iPhone では自動的にプッシュ/ポップに変換されます。

2.6 iOS 26+ Liquid Glass サイドバー(WWDC 2025, 323)

NavigationSplitView {
    List { ... }
} detail: {
    DetailView()
}
// サイドバーは iPad/macOS で自動的に Liquid Glass 外観になります

// コンテンツをガラスサイドバーの背後に拡張
.backgroundExtensionEffect()  // セーフエリア外のコンテンツをミラーリングし、ぼかします

ディープリンクと URL ルーティング

3.1 ディープリンクパターン

.onOpenURL を使用して URL を受信し、URLComponents で解析してから NavigationPath を操作します:

.onOpenURL { url in
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
          let host = components.host else { return }
    path.removeLast(path.count)  // 最初にルートに戻る
    // host/path を解析して宛先を決定し、path.append(value) を実行
}

マルチステップのディープリンク(myapp://category/desserts/recipe/apple-pie)の場合は、URL パスコンポーネントを反復処理し、それぞれの解決された値を追加して完全なナビゲーションスタックを構築します。

包括的なディープリンクの例、エラー診断、テストワークフローについては、axiom-swiftui-nav-diag(パターン3)を参照してください。


状態復元

4.1 完全な状態復元(WWDC 2022, 18:12)

struct UseSceneStorage: View {
    @StateObject private var navModel = NavigationModel()
    @SceneStorage("navigation") private var data: Data?
    @StateObject private var dataModel = DataModel()

    var body: some View {
        NavigationSplitView {
            List(Category.allCases, selection: $navModel.selectedCategory) { category in
                NavigationLink(category.localizedName, value: category)
            }
            .navigationTitle("Categories")
        } detail: {
            NavigationStack(path: $navModel.recipePath) {
                RecipeGrid(category: navModel.selectedCategory)
            }
        }
        .task {
            // 表示時に復元
            if let data = data {
                navModel.jsonData = data
            }
            // 変更時に保存
            for await _ in navModel.objectWillChangeSequence {
                data = navModel.jsonData
            }
        }
        .environmentObject(dataModel)
    }
}

4.2 Codable NavigationModel

class NavigationModel: ObservableObject, Codable {
    @Published var selectedCategory: Category?
    @Published var recipePath: [Recipe] = []

    enum CodingKeys: String, CodingKey {
        case selectedCategory
        case recipePathIds  // 完全なオブジェクトではなく ID を保存
    }

    func encode(to encoder: Encoder) throws {
        var container = encoder.container(keyedBy: CodingKeys.self)
        try container.encodeIfPresent(selectedCategory, forKey: .selectedCategory)
        try container.encode(recipePath.map(\.id), forKey: .recipePathIds)
    }

    init() {}

    required init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        self.selectedCategory = try container.decodeIfPresent(Category.self, forKey: .selectedCategory)
        let recipePathIds = try container.decode([Recipe.ID].self, forKey: .recipePathIds)
        self.recipePath = recipePathIds.compactMap { DataModel.shared[$0] } // 削除されたアイテムは破棄
    }
}

完全なモデルオブジェクトではなく ID を保存し、compactMap を使用して削除されたアイテムを適切に処理します。4.1 で示したように、SceneStorage 統合用の jsonData 計算プロパティと objectWillChangeSequence を追加します。


Tab + ナビゲーション統合

5.1 Tab 構文(iOS 18+)(WWDC 2024, 4:27)

TabView {
    Tab("Watch Now", systemImage: "play") {
        WatchNowView()
    }
    Tab("Library", systemImage: "books.vertical") {
        LibraryView()
    }
    ...
}

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

関連スキル