navigation3

  
Navigation 3는 Compose와 함께 작동하도록 설계된 새로운 탐색 라이브러리입니다.
최근 업데이트 안정화 버전 출시 후보 버전 베타 버전 알파 버전
2025년 10월 8일 - - - 1.0.0-alpha11

종속 항목 선언

navigation3의 종속 항목을 추가하려면 프로젝트에 Google Maven 저장소를 추가해야 합니다. 자세한 내용은 Google Maven 저장소를 읽어보세요.

다음과 같이 앱 또는 모듈의 build.gradle 파일에 필요한 아티팩트의 종속 항목을 추가합니다.

Groovy

dependencies {
    implementation "androidx.navigation3:navigation3-runtime:1.0.0-alpha11"
    implementation "androidx.navigation3:navigation3-ui:1.0.0-alpha11"
}

Kotlin

dependencies {
    implementation("androidx.navigation3:navigation3-runtime:1.0.0-alpha11")
    implementation("androidx.navigation3:navigation3-ui:1.0.0-alpha11")
}

종속 항목에 관한 자세한 내용은 빌드 종속 항목 추가를 참고하세요.

의견

제출하신 의견은 Jetpack을 개선하는 데 도움이 됩니다. 새로운 문제를 발견하거나 라이브러리 개선을 위한 아이디어가 있다면 Google에 알려 주세요. 새 문제를 제출하기 전에 이 라이브러리의 기존 문제를 살펴보시기 바랍니다. 별표 버튼을 클릭하여 기존 문제에 투표할 수 있습니다.

새로운 문제 제출하기

자세한 내용은 Issue Tracker 문서를 참고하세요.

이 아티팩트의 출시 노트는 없습니다.

버전 1.0

버전 1.0.0-alpha11

2025년 10월 8일

androidx.navigation3:navigation3-*:1.0.0-alpha11이 출시되었습니다. 버전 1.0.0-alpha11에는 이러한 커밋이 포함되어 있습니다.

API 변경사항

  • SceneStrategy의 calculateScene 메서드가 더 이상 @Composable이 아닙니다. 대신 이 작업을 rememberSaveable 값 또는 키 remember 문의 수명을 올바른 값에서 완전히 정의할 수 있는 SceneStrategy 메서드 (즉, rememberMySceneStrategy() 메서드)의 생성으로 이동하는 것이 좋습니다. (If1733, b/448709506)
  • SceneStrategy.calculateScene의 onBack 매개변수가 SceneStrategyScope의 새 수신기 범위로 이동하여 선택적 매개변수임을 더 명확하게 나타내고 향후 Navigation3 기능의 확장 지점을 제공합니다. (I3aea3, b/448460407)
  • NavDisplay 및 SceneStrategy에 전달된 onBack 람다는 더 이상 여러 항목을 팝해야 하는 시점을 나타내는 count: Int 매개변수를 제공하지 않습니다. 대신 장면에서 여러 항목이 표시되도록 요청하는 드문 경우에 () -> Unit 람다가 연속으로 여러 번 호출됩니다. (Idedb5, b/446989346)
  • NavEntryWrapper 클래스를 삭제하고 새 콘텐츠가 있는 NavEntry를 사용하는 새 보조 생성자가 있는 최종 NavEntry 클래스로 기능을 대체합니다. 이렇게 하면 새 콘텐츠로 항목을 래핑하는 작업을 계속 지원할 수 있습니다. (I7da2a, b/444447130)
  • NavEntryDecorator를 생성하고 반환하는 navEntryDecorator 함수가 삭제되고 이제 공개되고 하위 클래스화할 수 있는 NavEntryDecorator 클래스로 대체되었습니다. (If81f8, b/444447434, b/447381176)
  • SaveableStateHolder로 항목을 데코레이션하므로 SavedStateNavEntryDecorator의 이름이 SaveableStateHolderNavEntryDecorator로 바뀌었습니다. 데코레이터는 기능적으로 NavEntryDecorator의 팩터리이므로 함수에서 클래스로 리팩터링되었습니다. (Ie6013, b/447381176)
  • NavDisplay 대신 SceneState를 사용하는 맞춤 디스플레이는 더 이상 LocalEntriesToRenderInCurrentScene 컴포지션 로컬을 사용할 필요가 없습니다. 이제 LocalEntriesToRenderInCurrentScene는 내부적으로 사용됩니다. (Ic40ef, b/414668196)
  • 공개 API 노출 영역에서 SceneSetupNavEntryDecorator 및 rememberSceneSetupNavEntryDecorator()가 삭제되었습니다. 이제 이 기능은 수동으로 포함하지 않아도 기본적으로 포함됩니다. (Ieae42, b/444479133)
  • 이제 NavEntry, DialogScene, SinglePaneScene, SceneState가 모두 equals를 구현합니다. (I96121)
  • 장면 인터페이스에 NavDisplay의 장면별 메타데이터를 연결하는 새로운 메타데이터 필드가 있습니다. 이를 통해 장면이 전환과 같은 NavDisplay의 메타데이터를 재정의할 수 있습니다. (I1fd96, b/443955625)
  • 중복된 일반 유형 매개변수를 삭제하여 rememberNavBackStack 서명 단순화 이제 함수에서 vararg elements: NavKey을 허용합니다. (I03e45)
  • 이제 NavDisplay의 기본 애니메이션이 공통 API의 일부가 되어 모든 플랫폼에서 호출할 수 있습니다. (I71af9, b/447147159)
  • 클래스가 NavEntries를 빌드하는 범위를 제공하는 Kotlin DSL임을 정확하게 반영하도록 EntryProviderBuilder를 EntryProviderScope으로 이름을 바꿉니다. (Ia7465)

버그 수정

  • 이제 rememberNavBackStack()은 NavKey에 다형성 직렬화를 적용하고 올바른 상태 복원을 보장하도록 구성된 맞춤 SavedStateConfiguration가 필요합니다. 모든 NavKey 하위 유형이 제공된 SerializersModule에 등록되어야 한다는 요구사항을 반영하도록 KDoc이 업데이트되었습니다. (I6de37,I782f2, b/446664383)

버전 1.0.0-alpha10

2025년 9월 24일

androidx.navigation3:navigation3-*:1.0.0-alpha10이 출시되었습니다. 버전 1.0.0-alpha10에는 이 커밋이 포함되어 있습니다.

API 변경사항

  • rememberDecoratedNavEntries로 데코레이션된 NavEntry<T> 목록을 가져오는 새 NavDisplay 오버로드 추가 (I4025b, b/441940314)
  • DialogScene을 새 패키지로 이동했습니다. (Ia5840)
  • 공개 API DecorateNavEntry 삭제 대신 rememberDecoratedNavEntries를 사용하여 장식자 목록으로 NavEntry를 래핑하세요. (Id8c09)
  • 이제 Navigation3 UI에서 새로운 기본 transitionSpec 속성을 제공합니다. (Ibcabd)
  • 장면을 관리하는 데 도움이 되는 새로운 SceneState 객체가 추가되었습니다. 또한 SceneState 및 NavigationEventState를 사용하는 새로운 NavDisplay 오버로드를 제공합니다. (Idfb46, b/444479133)
  • NavDisplay에서는 이제 Transition의 currentState 및 targetState를 살펴보고 Scene의 이동 방향을 파악하여 전환을 맞춤설정할 수 있습니다. (I906cc, b/443872322)
  • 이제 NavigationEventInfo은 interface이 아닌 abstract class입니다. 클래스 (예: data class MyInfo : NavigationEventInfo())에서 상속받도록 모든 맞춤 구현을 업데이트합니다. (I1e59c, b/444734264)
  • navigationevent-compose 핸들러 API가 업데이트됩니다. 이제 NavigationEventHandler 및 NavigationBackHandler (및 변형)에서 호이스팅된 NavigationEventState를 허용하는 새로운 오버로드를 지원합니다. currentInfo를 사용하는 간단한 오버로드는 유지되며 이제 이 새로운 상태 모델을 내부적으로 사용합니다. (Ic3251, b/444734264)
  • 모든 장면 API가 navigation3-ui에서 navigation3-runtime으로 이동되었습니다. 즉, 이제 navigation3-runtime에서 지원하는 모든 플랫폼에서 사용할 수 있습니다. (I431d0, b/444449993)
  • 장식할 NavEntry 목록을 가져오는 새 rememberDecoratedNavEntries 오버로드가 추가되었습니다. 입력 항목은 이미 다른 항목 데코레이터로 장식되어 있을 수 있습니다. (I5a034, b/444230270)
  • navigation3 와일드카드 유형 매개변수 삭제 (I02540)
  • entryProvider DSL의 제네릭 처리가 개선되었습니다. 이전에 androidx.navigation3.runtime.entry을 가져온 경우 더 이상 그럴 필요가 없습니다. (I299fc)
  • 리플렉션 기반 NavBackStackSerializer 오버로드를 Android로 제한 이렇게 하면 다중 플랫폼 코드에서 명시적 SavedStateConfiguration 오버로드를 사용하도록 강제하여 Android가 아닌 플랫폼에서 암시적 런타임 직렬화 실패를 방지할 수 있습니다. (I73313, b/420443609)
  • NavigationEvent의 swipeEdge을 @IntDef로 만듦 (Icee54, b/443950342)
  • NavBackStack 직렬화를 Android로 제한 이렇게 하면 Android가 아닌 플랫폼에서 런타임 오류가 방지됩니다. 멀티 플랫폼 상태 저장을 위해 명시적 SavedStateConfiguration와 함께 rememberNavBackStack 오버로드를 사용합니다. (I1e418, b/420443609)

버그 수정

  • 중첩된 NavDisplay에 단일 하위 항목이 있는 경우 뒤로 탐색 예측 중에 발생하는 비정상 종료 수정 (I2cdc0, b/441933162)

버전 1.0.0-alpha09

2025년 9월 10일

androidx.navigation3:navigation3-*:1.0.0-alpha09이 출시되었습니다. 버전 1.0.0-alpha09에는 이 커밋이 포함되어 있습니다.

API 변경사항

  • DecoratedNavEntryProvider가 제공된 데코레이터 목록으로 데코레이션된 NavEntry를 생성하고 반환하는 rememberDecoratedNavEntries로 대체되었습니다 (I0fe1c, b/441328236).
  • 이제 NavBackStack이 NavKey 유형에 대해 일반화됩니다. 이를 통해 앱과 라이브러리는 NavKey에 제한되지 않고 백 스택의 맞춤 키 유형을 정의할 수 있습니다. (I4d190,Iad2f4, b/420443609)
  • 이제 NavBackStack이 @kotlinx.serialization.Serializable이므로 추가 상용구 없이 프로세스 종료 및 구성 변경 간에 탐색 상태를 저장하고 복원할 수 있습니다. (I2c3cf, b/420443609)
  • RememberNavBackStack가 모든 플랫폼 타겟에 제공되도록 commonMain로 이동했습니다. (Id69e7, b/420443609)

버그 수정

  • 이제 NavDisplay가 각 개별 NavEntry를 올바른 Lifecycle.State로 올바르게 이동합니다. (I30aac, b/440145700)
  • NavDisplay가 NavigationEvent 라이브러리의 LocalNavigationEventDispatcherOwner를 통해 설정된 중첩된 NavigationEventDispatcherOwner를 무시하는 문제가 수정되었습니다. (I6224a)

종속 항목 변경사항

버전 1.0.0-alpha08

2025년 8월 27일

androidx.navigation3:navigation3-*:1.0.0-alpha08이 출시되었습니다. 버전 1.0.0-alpha08에는 이 커밋이 포함되어 있습니다.

새로운 기능

  • Navigation3 Runtime 아티팩트에 새로운 Kotlin MultiPlatform (KMP) 타겟이 추가되었습니다. 이제 Navigation3 Runtime는 JVM (Android 및 데스크톱), 네이티브 (Linux, iOS, watchOS, macOS, MinGW), 웹 (JavaScript, WasmJS) 등 총 3가지 플랫폼을 지원합니다. (I55078, b/424410398, b/419294028, b/419046226) 참고: Navigation3 UI 아티팩트의 KMP 타겟은 제공되지 않습니다. 다른 플랫폼에서는 자체 맞춤 NavDisplay를 구현해야 합니다. 이 기능이 지원되기를 원한다면 여기에서 Jetbrains 문제를 투표하고 진행 상황을 추적하여 추가 지원을 받으세요.
  • 이제 NavDisplayInfo 객체가 공개되어 NavDisplay에서 표시되는 항목 목록을 검색하는 데 사용할 수 있습니다. (Ibc91f)

API 변경사항

  • 상태 복원을 실행하기 위해 rememberNavBackStack와 함께 사용할 새로운 NavBackStackSerializer가 추가되었습니다. 이제 rememberNavBackStack()는 자체 구성을 제공하는 데 사용할 수 있는 SavedStateConfiguration도 사용합니다. (I2f4d2, I4cd58, b/420443609)

버그 수정

알려진 문제

  • I8bf6d로 인해 도입된 버그로 인해 수명 주기가 개별 항목 대신 장면을 기반으로 하여 NavEntry에 제공된 key가 String이 아니거나 NavEntry가 contentKey을 재정의하여 key와 동일하게 설정하지 않은 경우 (이렇게 하면 키가 Bundle에 저장될 수 있음) 수명 주기가 중단되었습니다. 이 문제는 다음 출시에서 수정되었습니다. (b/440145700)

버전 1.0.0-alpha07

2025년 8월 13일

androidx.navigation3:navigation3-*:1.0.0-alpha07이 출시되었습니다. 버전 1.0.0-alpha07에는 이러한 커밋이 포함되어 있습니다.

MinSdk 업데이트

API 변경사항

  • 이제 SavedStateNavEntryDecorator는 SaveableStateProvider에 내장된 SaveableStateRegistry를 사용하여 상태를 저장하고 복원합니다. (If8d9a)
  • 이제 predictivePopTransitionSpec에 스와이프 가장자리가 매개변수로 제공되므로 사용자가 뒤로 탐색 예측 동작을 시작한 가장자리에 따라 전환을 맞춤설정할 수 있습니다. (I753a8)

버그 수정

  • 최근 장면이 기억되지 않아 맞춤 장면이 무한히 다시 계산되는 문제가 해결되었습니다. (I7ba84, b/418153031)

종속 항목 업데이트

버전 1.0.0-alpha06

2025년 7월 30일

androidx.navigation3:navigation3-*:1.0.0-alpha06이 출시되었습니다. 버전 1.0.0-alpha06에는 이 커밋이 포함되어 있습니다.

종속 항목 업데이트

버전 1.0.0-alpha05

2025년 7월 2일

androidx.navigation3:navigation3-*:1.0.0-alpha05이 출시되었습니다. 버전 1.0.0-alpha05에는 이 커밋이 포함되어 있습니다.

동작 변경사항

  • 이제 NavEntry의 상태는 NavDisplay에 전달된 현재 장식자 목록을 엄격하게 기반으로 합니다. 즉, 백 스택의 NavEntry 상태를 유지하려면 여러 백 스택의 경우 백 스택을 따라 데코레이터를 스왑해야 합니다. 그렇지 않으면 항목이 스왑되는 대신 팝된 것처럼 상태가 삭제됩니다. (I7a759, b/428033667)

버전 1.0.0-alpha04

2025년 6월 18일

androidx.navigation3:navigation3-*:1.0.0-alpha04이 출시되었습니다. 버전 1.0.0-alpha04에는 이러한 커밋이 포함되어 있습니다.

API 변경사항

  • 이제 NavEntry.content이 비공개로 설정되었습니다. NavEntry 콘텐츠를 호출하려면 더 이상 호출에 key 매개변수가 필요하지 않은 새 NavEntry.Content() API를 호출하세요. (Icd0fd, b/420991203)
  • 이제 NavEntry.key가 비공개 필드입니다. NavEntry 및 관련 상태는 새로운 contentKeyFactory 람다에서 생성되고 NavEntry.key에서 생성된 저장 가능한 해시로 기본 설정되는 새로운 contentKey 필드로 식별해야 합니다. (I81a6c, b/422001357, b/420991203 I2d7d4, b/420991203, b/422841812)

종속 항목 변경사항

  • 이제 Navigation3가 새로운 androidx.navigationevent.compose 아티팩트에 종속됩니다.

버전 1.0.0-alpha03

2025년 6월 4일

androidx.navigation3:navigation3-*:1.0.0-alpha03이 출시되었습니다. 버전 1.0.0-alpha03에는 이 커밋이 포함되어 있습니다.

버그 수정

  • Navigation3는 더 이상 스왑되고 다른 backStack 인스턴스로 대체된 backStacks의 데코레이터 상태를 지우지 않습니다. (I28a42, b/415076044)

버전 1.0.0-alpha02

2022년 5월 23일

androidx.navigation3:navigation3-*:1.0.0-alpha02이 출시되었습니다. 버전 1.0.0-alpha02에는 이 커밋이 포함되어 있습니다.

버그 수정

  • 동일한 속성 값을 가진 여러 데이터 클래스의 충돌을 일으키는 SavedStateNavEntryDecorator 문제가 수정되었습니다. (b/418070648, Iff4775)
  • 명시적 종속 항목을 선언하지 않고 실행할 때 비정상 종료를 일으키는 누락된 클래스 문제가 수정되었습니다. (b/419049149, I4b4ed)

버전 1.0.0-alpha01

2025년 5월 20일

androidx.navigation3:navigation3-*:1.0.0-alpha01이 출시되었습니다. 버전 1.0.0-alpha01에는 이 커밋이 포함되어 있습니다.

새로운 기능

Navigation3은 Jetpack Compose 인앱 탐색을 처리하기 위해 특별히 빌드된 새로운 탐색 라이브러리입니다. androidx.navigation3.runtime 아티팩트는 빌드 블록을 제공하고 androidx.navigation3.ui 아티팩트는 NavDisplay API를 통해 UI 레이어를 제공합니다. 개발자는 NavDisplay 컴포저블 함수에 자체 상태를 직접 제공할 수 있으며, 개발자 상태의 변경에 따라 콘텐츠가 변경됩니다.

@Serialiable object Home : NavKey
@Serialiable object Chat : NavKey

val backStack = rememberNavBackStack(Home)

NavDisplay(backStack, entryProvider = entryProvider {
  entry<Home> {
    Column {
      Text(“Home”)
      Button(onClick = { backStack.add(Chat) } ) {
        Text(“Go to Chat”)
      } 
    }
  }
  entry<Chat> { /* My Composable Content */ }
})

자세한 내용은 Navigation3 가이드를 참고하세요.