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 バージョン | 主な機能 |
|---|---|---|
| 2020 | iOS 14 | NavigationView(iOS 16で非推奨) |
| 2022 | iOS 16 | NavigationStack、NavigationSplitView、NavigationPath、値ベースの NavigationLink |
| 2024 | iOS 18 | Tab/Sidebar の統合、sidebarAdaptable、TabSection、ズーム遷移 |
| 2025 | iOS 26 | Liquid 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 の動作メカニズム
- NavigationStack は
pathコレクションを保持する - 値を提示するリンクをタップすると、その値が path に追加される
- NavigationStack は
navigationDestination修飾子を path の値にマッピングする - 宛先マッピングに基づいてビューがスタックにプッシュされる
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()
}
...
}