Gezinme 3

Navigation 3, Jetpack Compose için sıfırdan tasarlanmış bir gezinme kitaplığıdır. Bu kılavuzda, Wear OS uygulamalarında Navigation 3'ün nasıl uygulanacağı açıklanmaktadır.

Temel Kavramlar

  • NavKey: Uygulamanızdaki bir hedef (ekran) için tür güvenli, serileştirilebilir tanımlayıcı.
  • NavBackStack: Gezinme geçmişini temsil eden NavKey örneklerinin değiştirilebilir listesi. Öğeleri doğrudan bu listeden gönderip kaldırabilirsiniz.
  • rememberNavBackStack: Yapılandırma değişiklikleri ve işlem sonlandırma boyunca eski yığını oluşturan ve kalıcı hale getiren bir composable.
  • NavDisplay: Geri yığınını gözlemleyen ve etkin ekranı oluşturan temel kullanıcı arayüzü bileşeni.
  • EntryProvider: Bir NavKey öğesini gerçek @Composable kullanıcı arayüzüne bağlayan bir eşleme DSL'si.
  • SwipeDismissableSceneStrategy: Ekranlarınızı kaydırarak kapatma hareketiyle sarmalayan ve yerleşik geri animasyonlarını işleyen Wear'a özel strateji.

1. adım: Bağımlılıkları ekleyin

Projenize gerekli Navigation 3, Wear Compose ve Serialization bağımlılıklarını ekleyin.

Modern

dependencies {
    // Core Navigation 3 APIs
    implementation "androidx.navigation3:navigation3-runtime:1.2.0-alpha02"
    implementation "androidx.navigation3:navigation3-ui:1.2.0-alpha02"

    // Wear OS specific Navigation 3 integration
    implementation "androidx.wear.compose:compose-navigation3:1.6.1"

    // Kotlinx Serialization for type-safe routing
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0"
}

Kotlin

dependencies {
    // Core Navigation 3 APIs
    implementation("androidx.navigation3:navigation3-runtime:1.2.0-alpha02")
    implementation("androidx.navigation3:navigation3-ui:1.2.0-alpha02")

    // Wear OS specific Navigation 3 integration
    implementation("androidx.wear.compose:compose-navigation3:1.6.1")

    // Kotlinx Serialization for type-safe routing
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0")
}

2. adım: Hedefleri tanımlayın (NavKey)

Ekranlar, NavKey arayüzünü uygulayan, kesin türü belirlenmiş, serileştirilebilir nesneler veya veri sınıfları olarak tanımlanır.

@Serializable
sealed interface Screen : NavKey {
    @Serializable
    data object Home : Screen

    @Serializable
    data class Details(val itemId: String) : Screen
}

3. adım: NavDisplay ve geri yığını kurulumu

Uygulamanızın kök dizininde geri yığınını ve Wear OS sahne stratejisini ilk kullanıma hazırlayın, ardından bunları NavDisplay'ye bağlayın.

// 1. Create the persistent back stack starting at the Home screen
val backStack = rememberNavBackStack(Screen.Home)

// 2. Initialize the Wear OS swipe-to-dismiss strategy
val strategy = rememberSwipeDismissableSceneStrategy<NavKey>()

// 3. Render the NavDisplay
NavDisplay(
    backStack = backStack,
    sceneStrategies = listOf(strategy),
    entryProvider = entryProvider {
        // 4. Map keys to Composables
        entry<Screen.Home> {
            HomeScreen(
                onNavigateToDetails = { id -> backStack.add(Screen.Details(id)) }
            )
        }
        entry<Screen.Details> { key ->
            DetailsScreen(
                itemId = key.itemId,
                onBack = { backStack.removeAt(backStack.lastIndex) }
            )
        }
    }
)

4. adım: Gezinme işlemlerini gerçekleştirin

Geri yığını yalnızca özelleştirilmiş bir MutableList olduğundan gezinme işlemi son derece basittir. İşlemleri doğrudan backStack örneğinde yaparsınız:

  • İleri Git: backStack.add(Screen.Details("123"))
  • Geri gitme: backStack.removeLast() veya backStack.removeLastOrNull()
  • Temizle ve Sıfırla: backStack.clear(); backStack.add(Screen.Home) (veya yığını değiştirmek için liste işlemlerini kullanın).

5. adım: (İsteğe bağlı) ViewModel'leri hedeflere göre kapsamlandırın

Varsayılan olarak, ViewModel'ler Activity ile sınırlandırılır. Navigation 3, ViewModel kapsamını eski yığındaki bir NavEntry ile güvenli bir şekilde sınırlamak için belirli bir yapı (lifecycle-viewmodel-navigation3) sağlar. Hedef eski yığından çıkarıldığında ViewModel temizlenir.

  1. Bağımlılığı ekleyin:

    implementation("androidx.lifecycle:lifecycle-viewmodel-navigation3:...")

  2. ViewModel mağaza parametresini NavDisplay öğenizin entryDecorators bölümüne ekleyin. Compose rememberSaveable durumunu korumak için özel dekoratörler sağlarken SaveableStateHolderNavEntryDecorator öğesini de açıkça eklemeniz gerekir:

    NavDisplay(
    backStack = backStack,
    sceneStrategies = listOf(strategy),
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberViewModelStoreNavEntryDecorator()
    ),
    entryProvider = entryProvider {
        entry<Screen.Home> {
            // Any viewModel() requested here will be scoped to this NavEntry
            val viewModel: HomeViewModel = viewModel()
        }
    }
)