Skip to content

Latest commit

 

History

History
50 lines (40 loc) · 9.97 KB

NavigationSplitView_Implementation_Guide.md

File metadata and controls

50 lines (40 loc) · 9.97 KB

Руководство по внедрению NavigationSplitView в приложения на SwiftUI

Это руководство описывает пошаговый процесс внедрения адаптивного интерфейса на базе NavigationSplitView для приложений под macOS, iPadOS и iOS. Оно основано на рабочем примере из этого репозитория и показывает, как организовать данные, состояние и пользовательские представления, чтобы добиться одинаково предсказуемого поведения на разных платформах и при разных size class.

1. Подготовьте модель данных

  1. Создайте типы, которые поддерживают протоколы Identifiable и Hashable, чтобы их можно было безопасно использовать в списках и навигации.
  2. В примере используется структура CustomColor, описывающая элемент каталога цветов, и структура CustomColorCategory, группирующая цвета по категориям.【F:XcodeProject/NewNav/DTO/CustomColor.swift†L1-L15】【F:XcodeProject/NewNav/DTO/CustomColorCategory.swift†L1-L8】
  3. Организуйте источник данных (например, синглтон, сервис или репозиторий), который возвращает список категорий с вложенными элементами. В демо проекте это упрощённый объект Data с предзаполненными категориями.【F:XcodeProject/NewNav/ContentView.swift†L1-L20】

2. Определите состояние корневого представления

  1. В корневом ContentView храните текущее состояние выбора категории и элемента, путь навигации (если нужно поддерживать глубокие переходы) и видимость дополнительных панелей интерфейса.
  2. Для адаптации к размеру экрана запросите horizontalSizeClass через @Environment и храните выбранную конфигурацию столбцов в @State параметре columnVisibility.
  3. Базовый набор состояний показан в примере: selectedCategory, selectedColor, columnVisibility, pathCategory, pathColor и showInspector.【F:XcodeProject/NewNav/ContentView.swift†L22-L31】

3. Постройте NavigationSplitView

  1. Оберните основной контент в NavigationSplitView, передав биндинг к columnVisibility, чтобы управлять числом отображаемых столбцов (например, двойной или тройной режим).
  2. Реализуйте три секции: «Sidebar» (первый блок), «Content» (второй блок) и «Detail» (третий блок).
    • Sidebar: List с NavigationLink, использующая selection для поддержки синхронизации выбранного объекта и navigationTitle для локализации заголовка.【F:XcodeProject/NewNav/ContentView.swift†L33-L40】
    • Content: отдельное представление CategoryView, отвечающее за показ элементов выбранной категории.【F:XcodeProject/NewNav/ContentView.swift†L40-L45】
    • Detail: представление DetailView, которое отображает подробности по текущему элементу (или плейсхолдер, если элемент не выбран).【F:XcodeProject/NewNav/ContentView.swift†L45-L49】
  3. Примените .navigationSplitViewStyle(.automatic), чтобы предоставить системе решать, как компоновать столбцы на разных устройствах.【F:XcodeProject/NewNav/ContentView.swift†L49-L50】

4. Адаптируйте контент под разные size class

  1. Создайте вспомогательный контейнер, который меняет разметку в зависимости от horizontalSizeClass. В примере используется SizeClassAdaptiveView, который выводит разные представления для regular/compact режимов.【F:XcodeProject/NewNav/SizeClassAdaptiveView.swift†L1-L24】
  2. В CategoryView примените этот контейнер: для regular режима оставляйте список цветов, а в compact режиме добавляйте навигационные переходы (navigationDestination) для отображения деталей в стековом интерфейсе.【F:XcodeProject/NewNav/CategoryView.swift†L8-L23】
  3. Используйте navigationTitle, чтобы синхронизировать заголовок в средней колонке или в стеке навигации.【F:XcodeProject/NewNav/CategoryView.swift†L21-L22】

5. Реализуйте детальный экран и дополнительную панель

  1. DetailView должен принимать биндинг к выбранному элементу и отображать его содержимое. При отсутствии выбора выводите плейсхолдер (например, ColorPlaceholder).【F:XcodeProject/NewNav/DetailView.swift†L1-L20】【F:XcodeProject/NewNav/InspectorPanel.swift†L1-L21】
  2. Если требуется боковая панель инспектора, добавьте .inspector(isPresented:) к NavigationSplitView и передайте туда отдельное представление (например, InspectorPanel).【F:XcodeProject/NewNav/ContentView.swift†L50-L52】【F:XcodeProject/NewNav/InspectorPanel.swift†L23-L71】

6. Реагируйте на изменения выбора и размера экрана

  1. Используйте .onAppear, чтобы настроить начальное состояние компонентов в зависимости от size class (например, сразу показывать инспектор в regular режиме).【F:XcodeProject/NewNav/ContentView.swift†L53-L57】
  2. Отслеживайте изменения выбранной категории и обновляйте связанный элемент. В compact режиме обнуляйте выбор, чтобы не перескакивать на третий экран без участия пользователя.【F:XcodeProject/NewNav/ContentView.swift†L58-L65】
  3. Подписывайтесь на изменения horizontalSizeClass, чтобы динамически менять состояние интерфейса (например, скрывать инспектор в compact режиме).【F:XcodeProject/NewNav/ContentView.swift†L65-L71】

7. Интегрируйте компонент в своё приложение

  1. В существующем проекте добавьте файлы, описанные выше, или адаптируйте собственные модели/представления под те же требования (Identifiable, Hashable, @State/@Binding).
  2. Подключите NavigationSplitView в корневой точке (например, внутри WindowGroup) и передайте в него данные приложения.
  3. Настройте дополнительные панели (инспекторы, футеры и т. д.) при помощи соответствующих модификаторов SwiftUI.
  4. Проверьте работу на целевых платформах в Xcode Previews и на устройстве/симуляторе, обращая внимание на переключение между compact/regular режимами и глубину навигации.

8. Полезные советы

  • Для macOS и iPadOS важно настроить columnVisibility, чтобы пользователь мог управлять отображением колонок вручную.
  • Если требуется программно открыть/закрыть определённую колонку, используйте NavigationSplitViewVisibility и обновляйте его состояние в ответ на пользовательские действия.
  • Используйте NavigationPath, когда нужно поддерживать сложную иерархию переходов или deep-linking; в простых сценариях достаточно selection.
  • В compact интерфейсе избегайте автоматического выбора элементов, чтобы не скрывать пользовательский список после загрузки.
  • Для тестирования отображения инспектора на iPad и Mac используйте модификатор .inspector, который появится только при достаточной ширине окна или в соответствии с настройками платформы.

Следуя этим шагам, вы сможете быстро интегрировать NavigationSplitView в любое приложение и обеспечить правильную работу навигации на всех поддерживаемых платформах.