navigationevent

  
탐색 이벤트 라이브러리는 시스템 뒤로 버튼과 뒤로 탐색을 처리하기 위한 KMP 우선 API를 제공합니다.
최근 업데이트 안정화 버전 출시 후보 버전 베타 버전 알파 버전
2025년 7월 30일 - - - 1.0.0-alpha05

종속 항목 선언

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

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

Groovy

dependencies {
    implementation "androidx.navigationevent:navigationevent:1.0.0-alpha04"
}

Kotlin

dependencies {
    implementation("androidx.navigationevent:navigationevent:1.0.0-alpha04")
}

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

의견

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

새로운 문제 제출하기

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

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

버전 1.0

버전 1.0.0-alpha05

2025년 7월 30일

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

상위-하위 계층 구조 지원:

이제 NavigationEventDispatcher에 상위 및 하위 디스패처가 있어 계층적 트리 구조를 형성할 수 있습니다. 이렇게 하면 체인으로 연결된 디스패처를 통해 UI의 구조적 계층 구조를 반영하여 복잡한 Compose UI 구성요소에서 탐색 이벤트가 더 유연하게 전파되고 관리될 수 있습니다. (I194ac)

  // Create a parent dispatcher that will manage navigation events at a higher level.
  val parentDispatcher = NavigationEventDispatcher()

  // Create a child dispatcher linked to the parent, forming a hierarchy.
  val childDispatcher = NavigationEventDispatcher(parentDispatcher)

계층적 isEnabled 속성을 사용하면 디스패처를 하향식으로 제어할 수 있습니다. 디스패처에서 isEnabled가 false로 설정되면 모든 하위 디스패처가 자동으로 사용 중지됩니다. 이 기능을 사용하면 탐색 이벤트 시스템의 전체 브랜치를 효율적으로 전환할 수 있습니다. (I9e985)

  // Disabling the child dispatcher disables all its callbacks and any of its children recursively.
  childDispatcher.isEnabled = false

또한 NavigationEventCallback의 isEnabled 속성이 이제 연결된 디스패처의 사용 설정 상태를 따릅니다. 즉, 콜백 자체와 디스패처 (상위 요소 포함)가 모두 사용 설정된 경우에만 콜백이 사용 설정된 것으로 간주되므로 콜백 활성화에 대한 일관된 계층적 제어가 보장됩니다. (I1799a)

  // Create a test callback and add it to the child dispatcher.
  val callback1 = TestNavigationEventCallback(isEnabled = true)
  childDispatcher.addCallback(callback1)

  // Since the childDispatcher is disabled, the callback is effectively disabled as well.
  assertThat(callback1.isEnabled).isFalse()

디스패처와 그 하위 요소를 적절하게 정리하기 위한 새로운 dispose() 메서드가 도입되었습니다. dispose()를 호출하면 메모리 누수를 방지하기 위해 리스너가 중지되고, 모든 하위 디스패처가 재귀적으로 삭제되고, 디스패처에 등록된 모든 콜백이 삭제되고, 상위 요소에서 연결이 해제됩니다. 이렇게 하면 디스패처가 더 이상 필요하지 않을 때 리소스가 올바르게 해제됩니다. (I9e985)

  // Dispose the child dispatcher to clean up resources.
  childDispatcher.dispose()

처리된 디스패처에서 공개 메서드가 호출되면 IllegalStateException가 즉시 발생합니다. 이렇게 하면 자동 실패를 방지하고 개발자가 개발 중에 부적절한 사용을 식별하는 데 도움이 됩니다. (Ic2dc3)

  val callback2 = TestNavigationEventCallback()

  // Attempting to use a disposed dispatcher will throw an exception.
  assertThrows<IllegalStateException> {
      childDispatcher.addCallback(callback2)
  }

참고: aosp/3692572에서 Compose UI 내의 하위 디스패처를 자동으로 관리하는 새로운 NavigationEventDispatcherOwner 컴포저블이 도입됩니다. 하지만 이 변경사항은 현재 출시 버전에는 포함되지 않았으며 다음 버전에 포함될 예정입니다.

탐색 테스트 라이브러리

  • navigationevent 라이브러리에 전용 테스트 유틸리티를 제공하는 navigationevent-testing 모듈 추가 (0e50b6)
  • 테스트를 위해 TestNavigationEventCallback 가짜 유틸리티 클래스 추가 확인을 지원하기 위해 콜백 메서드 호출을 기록하고 수신된 NavigationEvent 항목을 저장합니다. (4a0246)
  • 기본값으로 NavigationEvent 인스턴스를 만드는 TestNavigationEvent 모의 유틸리티 함수를 추가하여 탐색 이벤트 처리에 관한 단위 테스트를 간소화합니다. (3b63f5)
  • 테스트를 위해 TestNavigationEventDispatcherOwner 가짜 유틸리티 클래스 추가 테스트에서 상호작용 확인을 지원하기 위해 대체 및 사용 설정 상태 변경 이벤트 수를 추적합니다. (c8753e)

API 변경사항

  • NavigationEventInputHandler를 androidMain에서 commonMain로 이동하여 KMP 공통 코드에서 사용할 수 있도록 합니다. 이벤트를 디스패치하기 위한 새 public send* 메서드 추가 NavigationEventDispatcher의 디스패치 함수를 public에서 internal로 변경합니다. 이제 사용자는 NavigationEventInputHandler를 사용하여 이벤트를 전송해야 합니다. (Ia7114)
  • NavigationInputHandler의 이름을 OnBackInvokedInputHandler로 바꿉니다. (I63405)

버그 수정

  • 중간 목록 할당을 방지하고 콜백 디스패치 성능을 개선하여 오버헤드를 줄이도록 NavigationEventDispatcher 리팩터링 (I82702, I1a9d9)
  • 컴파일 시간에 유효한 값 범위를 적용하고 API 안전성을 개선하기 위해 NavigationEvent의 touchX, touchY, progress 필드에 @FloatRange 주석 추가 (Iac0ec)

버전 1.0.0-alpha04

2025년 7월 2일

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

버그 수정

  • implementedInJetBrainsFork를 navigationevent-compose로 사용하고 Compose 규칙에 맞게 commonStubs 타겟을 추가했습니다. JetBrains에서 요청한 변경사항입니다. (f60c79)
  • 올바른 스텁 생성을 위해 Kotlin/Native용 Compose 컴파일러 플러그인 적용이 수정되었습니다. 공개 API나 동작에 영향을 미치지 않습니다. (1890c9)

버전 1.0.0-alpha03

2025년 6월 18일

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

새로운 기능

  • navigationevent 라이브러리에서 Jetpack Compose 기능을 지원하는 새로운 navigationevent-compose 모듈을 도입했습니다. (980d78)
  • NavigationEvent Compose에 새로운 LocalNavigationEventDispatcherOwner 로컬 컴포지션이 추가되었습니다. 현재 컴포지션에서 사용할 수 있는지 더 효과적으로 판단할 수 있도록 null을 허용하는 값을 반환합니다. 이제 기본 소유자를 찾을 수 없는 경우 NavigationEventHandler에서 오류가 발생합니다. (62ffda)
  • NavigationEvent Compose에 (뒤로 탐색 예측 동작) 이벤트를 처리하는 새로운 NavigationEventHandler 컴포저블이 추가되었습니다. 제공하는 정지 람다에서 수집해야 하는 NavigationEvent 객체의 Flow을 제공합니다(c42ba6).
NavigationEventHandler { progress: Flow<NavigationEvent> ->
  // This block is executed when the back gesture begins.
  try {
    progress.collect { backEvent ->
      // Handle gesture progress updates here.
    }
    // This block is executed if the gesture completes successfully.
  } catch (e: CancellationException) {
    // This block is executed if the gesture is cancelled
    throw e
  } finally {
    // This block is executed either the gesture is completed or cancelled
  }
}

API 변경사항

  • 이제 각 NavigationEventCallback는 한 번에 하나의 NavigationEventDispatcher에만 등록할 수 있습니다. 여러 디스패처에 추가하면 IllegalStateException가 발생합니다. 이 동작은 여러 디스패처를 허용하는 OnBackPressedDispatcher와 다릅니다. (e82c19)
  • 내비게이션 중에 변이가 발생하여 NavigationEvent의 디스패치가 중단될 수 있으므로 isPassThrough를 val로 만들었습니다. (I0b287)

버전 1.0.0-alpha02

2025년 6월 4일

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

API 변경사항

  • NavigationEventDispatcher의 보조 생성자를 기본 인수로 바꿉니다. (I716a0)
  • NavigationEventCallback에서 우선순위 속성을 삭제합니다. 대신 NavigationEventDispatcher.addCallback()에 우선순위를 전달하세요. (I13cae)

버그 수정

  • 내부 닫을 수 있는 항목 목록을 동시에 수정하여 NavigationEventCallback.remove()가 호출될 때 발생할 수 있는 ConcurrentModificationException를 수정했습니다. (b/420919815)

버전 1.0.0-alpha01

2025년 5월 20일

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

새로운 기능

  • androidx.navigationevent 라이브러리는 시스템 뒤로 버튼과 뒤로 탐색 예측을 처리하기 위한 KMP 우선 API를 제공합니다. NavigationEventDispatcher는 시스템 뒤로 이벤트를 수신하기 위해 하나 이상의 NavigationEventCallback 인스턴스를 등록하는 공통 API 역할을 합니다.
  • 이 레이어는 이전에 출시된 androidx.activity의 API 아래에 있으며, 상위 수준 구성요소에서 Activity API를 사용하거나 Android 프레임워크 OnBackInvokedDispatcher API를 직접 사용하는 것을 대체하는 데 목적이 있습니다. androidx.activity API는 Activity 1.12.0-alpha01의 일부로 탐색 이벤트 API를 기반으로 다시 작성되었습니다.