使用方法
- 复制安装命令，在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物，并对照来源检查输出。
npx skills add https://github.com/new-silvermoon/awesome-android-agent-skills --skill navigation3开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况，不等于独立质量或安全测试。
按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。
Navigation 3
Overview
Implement state-driven navigation in Jetpack Compose using Navigation 3. Unlike Navigation Compose, Navigation 3 models navigation as application state rather than through a NavController. This skill covers navigation keys, back stack management, ViewModel scoping, entry decorators, adaptive layouts, deep links, animations, state restoration, and testing.
Setup
Add the Navigation 3 dependencies:
// build.gradle.kts
dependencies {
implementation("androidx.navigation3:navigation3-runtime:1.0.0-alpha08")
implementation("androidx.navigation3:navigation3-ui:1.0.0-alpha08")
// Lifecycle integration
implementation("androidx.lifecycle:lifecycle-viewmodel-navigation3:2.9.2")
// Serialization
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.1")
}
// Enable serialization plugin
plugins {
kotlin("plugin.serialization") version "2.2.0"
}Core Concepts
1. Define Navigation Keys
Navigation destinations are represented by immutable serializable objects.
import kotlinx.serialization.Serializable
@Serializable
data object Home
@Serializable
data class Profile(
val userId: String
)
@Serializable
data class Product(
val productId: String,
val showReviews: Boolean = false
)
@Serializable
data object SettingsKeys become your navigation state.
2. Create the Back Stack
Navigation 3 replaces NavController with a mutable state back stack.
@Composable
fun MyApp() {
val backStack = remember {
mutableStateListOf<Any>(Home)
}
AppNavDisplay(backStack)
}3. Create NavDisplay
@Composable
fun AppNavDisplay(
backStack: SnapshotStateList<Any>
) {
NavDisplay(
backStack = backStack,
onBack = {
if (backStack.size > 1) {
backStack.removeLast()
}
}
) { key ->
when (key) {
Home ->
HomeScreen(
onProfileClick = {
backStack += Profile(it)
}
)
is Profile ->
ProfileScreen(
userId = key.userId
)
is Product ->
ProductScreen(
productId = key.productId,
showReviews = key.showReviews
)
Settings ->
SettingsScreen()
}
}
}Navigation Patterns
Navigate Forward
backStack += Profile("user123")Navigate Back
backStack.removeLast()Replace Current Screen
backStack[backStack.lastIndex] = HomeClear Back Stack
backStack.clear()
backStack += HomePop To Root
while (backStack.size > 1) {
backStack.removeLast()
}Argument Handling
Retrieve Arguments
Arguments already exist inside the navigation key.
when (val key = currentKey) {
is Profile -> {
ProfileScreen(
userId = key.userId
)
}
is Product -> {
ProductScreen(
productId = key.productId
)
}
}Pass IDs, Not Objects
// CORRECT
backStack += Profile(user.id)
// Fetch object inside ViewModel
class ProfileViewModel(
savedStateHandle: SavedStateHandle,
repository: UserRepository
) : ViewModel() {
val profile = savedStateHandle.toRoute<Profile>()
val user =
repository.getUser(profile.userId)
}// INCORRECT
backStack += User(...)
backStack += ProductRepository(...)
backStack += ProductViewModel(...)ViewModel Integration
Navigation 3 scopes ViewModels using entry decorators.
NavDisplay(
backStack = backStack,
entryDecorators = listOf(
rememberSceneSetupNavEntryDecorator(),
rememberSavedStateNavEntryDecorator(),
rememberViewModelStoreNavEntryDecorator()
)
) { key ->
// destinations
}ViewModel Example
class ProfileViewModel(
savedStateHandle: SavedStateHandle
) : ViewModel() {
val profile =
savedStateHandle.toRoute<Profile>()
}Entry Decorators
Navigation 3 uses decorators to attach lifecycle functionality.
Scene Setup
rememberSceneSetupNavEntryDecorator()Creates the navigation scene for each entry.
Saved State
rememberSavedStateNavEntryDecorator()Automatically restores destination state after process recreation.
ViewModel Store
rememberViewModelStoreNavEntryDecorator()Scopes ViewModels to each navigation entry.
Adaptive Navigation
Navigation 3 integrates with Material Adaptive layouts.
NavDisplay(
backStack = backStack,
sceneStrategy = rememberListDetailSceneStrategy()
)Use adaptive scene strategies to automatically switch between:
- Single pane (phones)
- Two pane (tablets)
- Foldables
Deep Links
Deep links should resolve into navigation keys.
fun handleDeepLink(uri: Uri) {
val userId =
uri.lastPathSegment ?: return
backStack += Profile(userId)
}Avoid manually constructing route strings.
Animations
Navigation transitions are defined using scene transitions.
NavDisplay(
backStack = backStack,
transitionSpec = {
fadeIn() togetherWith fadeOut()
}
)Navigation 3 animation APIs may evolve while in alpha.
State Restoration
Navigation keys are serializable and automatically restored.
val backStack = rememberSaveable(
saver = navBackStackSaver()
) {
mutableStateListOf(Home)
}Always ensure keys are serializable.
Testing
Navigation becomes simple because it is state-driven.
Example
@Test
fun navigateToProfile() {
val backStack =
mutableStateListOf<Any>(Home)
backStack += Profile("123")
assertEquals(
Profile("123"),
backStack.last()
)
}Compose UI tests can verify screen rendering by inspecting the current back stack.
Migration from Navigation Compose
| Navigation Compose | Navigation 3 |
|---|---|
NavController | Mutable back stack |
NavHost | NavDisplay |
navigate() | backStack += Key |
popBackStack() | removeLast() |
| String routes | Serializable keys |
composable() | when(key) |
| Navigation graph | State-driven destinations |
Recommended Project Structure
navigation/
AppNavigation.kt
NavigationKeys.kt
NavigationDisplay.kt
feature/
home/
profile/
settings/Critical Rules
DO
- Use immutable serializable keys
- Keep navigation state inside Compose
- Pass IDs instead of complex objects
- Scope ViewModels using entry decorators
- Use
rememberSaveablefor state restoration - Model navigation as observable application state
DON'T
- Use string routes
- Pass repositories or ViewModels through navigation
- Mutate navigation keys
- Store business objects in the back stack
- Recreate the back stack on recomposition
- Mix Navigation Compose APIs with Navigation 3 APIs
References
- Android Navigation 3 documentation
- Navigation 3 samples
- Lifecycle ViewModel Navigation 3 documentation
- Material 3 Adaptive Navigation documentation
