Jetpack 탐색을 Navigation Compose로 이전

Navigation Compose API를 사용하면 Jetpack Navigation의 구성요소, 인프라, 기능을 활용하면서 Compose 앱에서 컴포저블 간에 이동할 수 있습니다.

이 페이지에서는 Jetpack Compose로의 대규모 뷰 기반 UI 이전의 일환으로 프래그먼트 기반 Jetpack Navigation에서 Navigation Compose로 이전하는 방법을 설명합니다.

참고: Navigation Compose를 처음 사용하는 경우 먼저 Compose를 통해 이동을 참고하세요. 이 문서에서는 탐색 이벤트 또는 복잡한 데이터를 전달하고 인수로 컴포저블을 설정하는 방법과 같은 Navigation Compose의 기본사항을 설명합니다.

이전 사전 요구사항

모든 프래그먼트를 상응하는 화면 컴포저블로 교체할 수 있게 되면 Navigation Compose로 이전할 수 있습니다. 화면 컴포저블은 Compose와 뷰 콘텐츠의 조합을 포함할 수 있지만 Navigation Compose 이전을 사용 설정하려면 모든 탐색 대상이 컴포저블이어야 합니다. 그때까지는 상호 운용성 뷰 및 Compose 코드베이스에서 프래그먼트 기반 탐색 구성요소를 계속 사용해야 합니다. 자세한 내용은 탐색 상호 운용성 문서를 참고하세요.

Compose 전용 앱에서 Navigation Compose를 사용하는 것이 기본 요건은 아닙니다. 구성 가능한 콘텐츠를 호스팅하기 위해 프래그먼트를 유지하는 한 프래그먼트 기반 탐색 구성요소를 계속 사용할 수 있습니다.

참고: 현재는 단일 형식의 탐색 구성요소를 사용하여 혼합된 Fragment와 컴포저블 대상 간에 이동할 수 없습니다. 모든 대상은 균일하게 프래그먼트 (Jetpack Navigation 사용) 또는 컴포저블 (Navigation Compose 사용)이어야 합니다.

이전 단계

권장되는 이전 전략을 따르든 다른 접근 방식을 사용하든 모든 탐색 대상이 화면 컴포저블이고 Fragment는 구성 가능한 컨테이너 역할만 하는 지점에 도달하게 됩니다. 이 단계에서는 Navigation Compose로 이전할 수 있습니다.

앱이 이미 UDF 디자인 패턴 및 아키텍처 가이드를 따르고 있다면 Jetpack Compose 및 Navigation Compose로 이전할 때 UI 레이어 외에 앱의 다른 레이어를 크게 리팩터링할 필요가 없습니다.

Navigation Compose로 이전하려면 다음 단계를 따르세요.

1. 앱에 Navigation Compose 종속 항목을 추가합니다.

2. App-level 컴포저블을 만들고 Activity에 Compose 진입점으로 추가하여 뷰 레이아웃 설정을 바꿉니다.

   class SampleActivity : ComponentActivity() {
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
           // setContentView<ActivitySampleBinding>(this, R.layout.activity_sample)
           setContent {
               SampleApp(/* ... */)
           }
       }
   }
   MigrationCommonScenariosSnippets.kt

3. NavController를 참조해야 하는 모든 컴포저블이 액세스할 수 있는 위치에 설정합니다 (일반적으로 App 컴포저블 내에 있음). 이 접근 방식은 상태 호이스팅 원칙을 따르며, 이를 통해 컴포저블 화면 간 이동과 백 스택 유지를 위한 정보 소스로 NavController를 사용할 수 있습니다.

   @Composable
   fun SampleApp() {
       val navController = rememberNavController()
       // ...
   }
   MigrationCommonScenariosSnippets.kt

4. App 컴포저블 내에서 앱의 NavHost를 만들고 navController를 전달합니다.

   @Composable
   fun SampleApp() {
       val navController = rememberNavController()
   
       SampleNavHost(navController = navController)
   }
   
   @Composable
   fun SampleNavHost(
       navController: NavHostController
   ) {
       NavHost(navController = navController, startDestination = "first") {
           // ...
       }
   }
   MigrationCommonScenariosSnippets.kt

5. composable 대상을 추가하여 탐색 그래프를 빌드합니다. 각 화면이 이전에 Compose로 이전되었다면 이 단계는 이러한 화면 컴포저블을 Fragment에서 composable 대상으로 추출하는 것으로만 구성됩니다.

   class FirstFragment : Fragment() {
   
       override fun onCreateView(
           inflater: LayoutInflater,
           container: ViewGroup?,
           savedInstanceState: Bundle?
       ): View {
           return ComposeView(requireContext()).apply {
               setContent {
                   // FirstScreen(...) EXTRACT FROM HERE
               }
           }
       }
   }
   
   @Composable
   fun SampleNavHost(
       navController: NavHostController
   ) {
       NavHost(navController = navController, startDestination = "first") {
           composable("first") {
               FirstScreen(/* ... */) // EXTRACT TO HERE
           }
           composable("second") {
               SecondScreen(/* ... */)
           }
           // ...
       }
   }
   MigrationCommonScenariosSnippets.kt

6. Compose UI 설계에 관한 안내, 특히 ViewModel 및 탐색 이벤트를 컴포저블에 전달하는 방법을 따랐다면 다음 단계는 ViewModel를 각 화면 컴포저블에 제공하는 방법을 변경하는 것입니다. 종종 hiltViewModel를 통해 Compose 및 Navigation과 Hilt 삽입 및 통합 지점을 사용할 수 있습니다.

   @Composable
   fun FirstScreen(
       // viewModel: FirstViewModel = viewModel(),
       viewModel: FirstViewModel = hiltViewModel(),
       onButtonClick: () -> Unit = {},
   ) {
       // ...
   }
   MigrationCommonScenariosSnippets.kt

7. 모든 findNavController() 탐색 호출을 navController 호출로 바꾸고 전체 navController를 전달하는 대신 각 컴포저블 화면에 탐색 이벤트로 전달합니다. 이 접근 방식은 구성 가능한 함수의 이벤트를 호출자에 노출하는 권장사항을 따르고 navController를 단일 정보 소스로 유지합니다.

   1. 이전에 Safe Args 플러그인을 사용하여 탐색 경로 및 작업을 생성했다면 경로(대상별로 고유한 컴포저블의 문자열 경로)로 바꿉니다.
   2. 데이터를 전달할 때 Safe Args를 교체하려면 인수로 탐색을 참고하세요.

   3. Navigation Compose의 유형 안전성은 아래의 Safe Args 섹션을 참고하세요.

      @Composable
      fun SampleNavHost(
          navController: NavHostController
      ) {
          NavHost(navController = navController, startDestination = "first") {
              composable("first") {
                  FirstScreen(
                      onButtonClick = {
                          // findNavController().navigate(firstScreenToSecondScreenAction)
                          navController.navigate("second_screen_route")
                      }
                  )
              }
              composable("second") {
                  SecondScreen(
                      onIconClick = {
                          // findNavController().navigate(secondScreenToThirdScreenAction)
                          navController.navigate("third_screen_route")
                      }
                  )
              }
              // ...
          }
      }
      MigrationCommonScenariosSnippets.kt

8. 모든 Fragment, 관련 XML 레이아웃, 불필요한 탐색 및 기타 리소스, 오래된 Fragment 및 Jetpack Navigation 종속 항목을 삭제합니다.

설정 문서의 더 많은 Navigation Compose 관련 세부정보에서 동일한 단계를 확인할 수 있습니다.

일반적인 사용 사례

어떤 탐색 구성요소를 사용하든 동일한 탐색 원칙이 적용됩니다.

이전 시 일반적인 사용 사례는 다음과 같습니다.

• 컴포저블로 이동
• 인수로 탐색
• 딥 링크
• 중첩 탐색
• 하단 탐색 메뉴와 통합
• 맞춤 탐색 구성요소와 통합

이러한 사용 사례에 관한 자세한 내용은 Compose를 통해 이동을 참고하세요.

Safe Args

Jetpack Navigation과 달리 Navigation Compose는 코드 생성에 Safe Args 플러그인 사용을 지원하지 않습니다. 대신 런타임에 유형 안전성을 갖추도록 코드를 구조화하여 Navigation Compose로 유형 안전성을 달성할 수 있습니다.

탐색 시 복잡한 데이터 검색

Navigation Compose는 문자열 경로 기반이며 Jetpack Navigation과 달리 맞춤 Parcelable 및 Serializable을 인수로 전달하는 것을 지원하지 않습니다.

탐색 시 복잡한 데이터 객체는 전달하지 않는 것이 좋습니다. 대신, 탐색 작업을 실행할 때 고유 식별자나 다른 형식의 ID와 같이 필요한 최소한의 정보를 인수로 전달하세요. 복잡한 객체는 데이터 영역과 같은 단일 정보 소스에 데이터로 저장해야 합니다. 자세한 내용은 탐색 시 복잡한 데이터 검색을 참조하세요.

Fragment가 복잡한 객체를 인수로 전달하는 경우, 데이터 영역에서 이러한 객체를 저장하고 가져올 수 있는 방식으로 코드를 먼저 리팩터링하는 것이 좋습니다. 예는 Now in Android 저장소를 참고하세요.

제한사항

이 섹션에서는 Navigation Compose의 현재 제한사항을 설명합니다.

Navigation Compose로 증분 이전

현재 코드에서 프래그먼트를 대상으로 사용하면서 Navigation Compose를 사용할 수는 없습니다. Navigation Compose를 사용하려면 모든 대상이 컴포저블이어야 합니다. Issue Tracker에서 이 기능 요청을 추적할 수 있습니다.

전환 애니메이션

Navigation 2.7.0-alpha01부터 이전에 AnimatedNavHost의 맞춤 전환 설정 지원이 이제 NavHost에서 직접 지원됩니다. 자세한 내용은 출시 노트를 참조하세요.

자세히 알아보기

Navigation Compose로 이전에 관한 자세한 내용은 다음 리소스를 참고하세요.

• Navigation Compose Codelab: 실습 Codelab을 통해 Navigation Compose의 기본사항을 알아봅니다.
• Now in Android 저장소: Kotlin과 Jetpack Compose로 완전히 빌드된 완전한 기능을 갖춘 Android 앱으로, Android 디자인 및 개발 권장사항을 따르고 Navigation Compose를 포함합니다.
• Sunflower에서 Jetpack Compose로 이전: 뷰에서 Compose로의 Sunflower 샘플 앱 이전 과정을 설명하는 블로그 게시물입니다. 여기에는 Navigation Compose로의 이전도 포함되어 있습니다.
• 모든 화면에 적용되는 Jetnews: Jetpack Compose와 Navigation Compose가 있는 모든 화면을 지원하기 위한 Jetnews 샘플의 리팩터링과 이전을 설명하는 블로그 게시물입니다.