탐색 구성요소 시작하기

이 주제는 탐색 구성요소를 설정하고 사용하는 방법을 설명합니다. 탐색 구성요소의 대략적인 개요는 탐색 개요를 참고하세요.

환경 설정

프로젝트에 탐색 지원을 포함하려면 앱의 build.gradle 파일에 다음 종속 항목을 추가합니다.

Groovy

dependencies {
  def nav_version = "2.5.3"

  // Java language implementation
  implementation "androidx.navigation:navigation-fragment:$nav_version"
  implementation "androidx.navigation:navigation-ui:$nav_version"

  // Kotlin
  implementation "androidx.navigation:navigation-fragment-ktx:$nav_version"
  implementation "androidx.navigation:navigation-ui-ktx:$nav_version"

  // Feature module Support
  implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version"

  // Testing Navigation
  androidTestImplementation "androidx.navigation:navigation-testing:$nav_version"

  // Jetpack Compose Integration
  implementation "androidx.navigation:navigation-compose:$nav_version"
}

Kotlin

dependencies {
  val nav_version = "2.5.3"

  // Java language implementation
  implementation("androidx.navigation:navigation-fragment:$nav_version")
  implementation("androidx.navigation:navigation-ui:$nav_version")

  // Kotlin
  implementation("androidx.navigation:navigation-fragment-ktx:$nav_version")
  implementation("androidx.navigation:navigation-ui-ktx:$nav_version")

  // Feature module Support
  implementation("androidx.navigation:navigation-dynamic-features-fragment:$nav_version")

  // Testing Navigation
  androidTestImplementation("androidx.navigation:navigation-testing:$nav_version")

  // Jetpack Compose Integration
  implementation("androidx.navigation:navigation-compose:$nav_version")
}

다른 아키텍처 구성요소를 프로젝트에 추가하는 방법에 관한 자세한 내용은 프로젝트에 구성요소 추가를 참고하세요.

탐색 그래프 만들기

앱의 대상(즉, 사용자가 이동할 수 있는 앱의 어느 곳이든) 간에 탐색이 발생합니다. 이러한 대상은 작업을 통해 연결됩니다.

탐색 그래프는 모든 대상 및 작업을 포함하는 리소스 파일입니다. 그래프는 앱의 모든 탐색 경로를 나타냅니다.

그림 1은 5개의 작업으로 연결된 6개의 대상을 포함하는 샘플 앱의 탐색 그래프를 시각적으로 보여줍니다. 각 대상은 미리보기 이미지로 표시되며 연결 작업은 사용자가 한 대상에서 다른 대상으로 이동할 수 있는 방법을 나타내는 화살표로 표시됩니다.

그림 1. 5개의 작업을 통해 연결된 서로 다른 대상 6개의 미리보기를 보여주는 탐색 그래프
  1. 대상은 앱의 다양한 콘텐츠 영역입니다.
  2. 작업은 사용자가 택할 수 있는 경로를 나타내는 대상 간의 논리적 연결입니다.

프로젝트에 탐색 그래프를 추가하려면 다음 단계를 따르세요.

  1. Project 창에서 res 디렉터리를 마우스 오른쪽 버튼으로 클릭하고 New > Android Resource File을 선택합니다. New Resource File 대화상자가 나타납니다.
  2. File name 필드에 'nav_graph'와 같은 이름을 입력합니다.
  3. Resource type 드롭다운 목록에서 Navigation을 선택한 후 OK를 클릭합니다.

첫 번째 탐색 그래프를 추가할 때 Android 스튜디오에서 res 디렉터리 내에 navigation 리소스 디렉터리를 만듭니다. 이 디렉터리에는 탐색 그래프 리소스 파일(예: nav_graph.xml)이 포함됩니다.

그래프를 추가한 후 Android 스튜디오는 Navigation Editor에서 그래프를 엽니다. Navigation Editor에서 탐색 그래프를 시각적으로 편집하거나 기본 XML을 직접 편집할 수 있습니다.

그림 2. Navigation Editor
  1. Destinations 패널: 현재 Graph Editor에 있는 탐색 호스트와 모든 대상을 나열합니다.
  2. Graph Editor: 탐색 그래프를 시각적으로 표시합니다. Design 뷰와 기본 XML 표현이 있는 Text 뷰를 전환할 수 있습니다.
  3. Attributes: 탐색 그래프에서 현재 선택된 항목의 속성을 보여줍니다.

Text 탭을 클릭하면 다음 스니펫과 비슷한 XML을 확인할 수 있습니다.

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:android="http://schemas.android.com/apk/res/android"
            xmlns:app="http://schemas.android.com/apk/res-auto"
            android:id="@+id/nav_graph">

</navigation>

<navigation> 요소는 탐색 그래프의 루트 요소입니다. 대상 및 연결 작업을 그래프에 추가할 때 여기에서 해당하는 <destination> 및 <action> 요소를 하위 요소로 확인할 수 있습니다. 중첩된 그래프가 있다면 하위 <navigation> 요소로 표시됩니다.

활동에 NavHost 추가

탐색 구성요소의 핵심 부분 중 하나는 탐색 호스트입니다. 탐색 호스트는 빈 컨테이너로, 사용자가 앱을 탐색하는 동안 여기서 대상이 교체됩니다.

탐색 호스트는 NavHost에서 파생되어야 합니다. 탐색 구성요소의 기본 NavHost 구현인 NavHostFragment는 프래그먼트 대상의 교체를 처리합니다.

XML을 통한 NavHostFragment 추가

아래의 XML 예에서는 앱 기본 활동의 일부로 NavHostFragment를 보여줍니다.

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.appcompat.widget.Toolbar
        .../>

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintBottom_toBottomOf="parent"

        app:defaultNavHost="true"
        app:navGraph="@navigation/nav_graph" />

    <com.google.android.material.bottomnavigation.BottomNavigationView
        .../>

</androidx.constraintlayout.widget.ConstraintLayout>

다음 내용을 참고하세요.

  • android:name 속성은 NavHost 구현의 클래스 이름을 포함합니다.
  • app:navGraph 속성은 NavHostFragment를 탐색 그래프와 연결합니다. 탐색 그래프는 사용자가 이동할 수 있는 이 NavHostFragment의 모든 대상을 지정합니다.
  • app:defaultNavHost="true" 속성을 사용하면 NavHostFragment가 시스템 뒤로 버튼을 가로챕니다. 하나의 NavHost만 기본값으로 지정할 수 있습니다. 동일한 레이아웃에 여러 호스트가 있다면(예: 창이 2개인 레이아웃) 한 호스트만 기본 NavHost로 지정해야 합니다.

또한 다음과 같은 방법으로 Layout Editor를 사용하여 NavHostFragment를 활동에 추가할 수 있습니다.

  1. 프로젝트 파일 목록에서 활동의 레이아웃 XML 파일을 더블클릭하여 Layout Editor에서 엽니다.
  2. Palette 창 내에서 Containers 카테고리를 선택하거나 'NavHostFragment'를 검색합니다.
  3. 활동으로 NavHostFragment 뷰를 드래그합니다.
  4. 다음으로, 표시되는 Navigation Graphs 대화상자에서 해당 탐색 그래프를 선택하여 이 NavHostFragment와 연결한 후 OK를 클릭합니다.

탐색 그래프에 대상 추가

기존 프래그먼트 또는 활동에서 대상을 만들 수 있습니다. 또한 Navigation Editor를 사용하여 새 대상을 만들거나 자리표시자를 만들어 나중에 프래그먼트 또는 활동으로 교체할 수도 있습니다.

이 예에서는 새 대상을 만들어 보겠습니다. Navigation Editor를 사용하여 새 대상을 추가하려면 다음 단계를 따르세요.

  1. 탐색 편집기에서 New Destination 아이콘 을 클릭한 다음 Create new destination을 클릭합니다.
  2. New Android Component 대화상자가 표시되면 프래그먼트를 만듭니다. 프래그먼트에 관한 자세한 내용은 프래그먼트 문서를 참조하세요.

다시 탐색 편집기에서 Android 스튜디오가 이 대상을 그래프에 추가한 것을 확인할 수 있습니다.

그림 3은 대상 및 자리표시자 대상의 예를 보여줍니다.

그림 3. 대상 및 자리표시자

대상을 탐색 그래프에 추가하는 다른 방법은 대상 만들기를 참고하세요.

대상의 구성

대상을 클릭하여 선택하고 Attributes 패널에서 다음 속성을 확인합니다.

  • Type 필드는 대상이 소스 코드에서 프래그먼트, 활동 또는 기타 맞춤 클래스로 구현되는지 여부를 나타냅니다.
  • Label 필드는 사용자가 읽을 수 있는 대상 이름을 포함합니다. NavGraph를 setupWithNavController()를 사용하여 Toolbar에 연결한 경우와 같이 UI에 이 필드 값이 표시될 수 있습니다. 이런 이유로 이 값에 리소스 문자열을 사용하는 것이 좋습니다.
  • ID 필드에는 코드에서 대상을 참조하는 데 사용되는 대상의 ID가 포함됩니다.
  • Class 드롭다운에는 대상과 연결된 클래스의 이름이 표시됩니다. 이 드롭다운을 클릭하면 연결된 클래스를 다른 대상 유형으로 변경할 수 있습니다.

Text 탭을 클릭하면 탐색 그래프의 XML 뷰를 확인할 수 있습니다. XML에는 아래와 같이 대상의 id, name, label 및 layout 속성이 포함되어 있습니다.

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:android="http://schemas.android.com/apk/res/android"
    app:startDestination="@id/blankFragment">
    <fragment
        android:id="@+id/blankFragment"
        android:name="com.example.cashdog.cashdog.BlankFragment"
        android:label="@string/label_blank"
        tools:layout="@layout/fragment_blank" />
</navigation>

시작 대상으로 화면 지정

시작 대상은 사용자가 앱을 열 때 처음으로 표시되는 화면이며 사용자가 앱을 종료할 때 마지막으로 보게 되는 화면입니다. 탐색 편집기는 홈 아이콘 을 사용하여 시작 대상을 나타냅니다.

대상이 모두 준비되면 다음과 같은 방법으로 시작 대상을 선택할 수 있습니다.

  1. Design 탭에서 대상을 클릭하여 강조표시합니다.

  2. Assign start destination 버튼 을 클릭합니다. 또는 대상을 마우스 오른쪽 버튼으로 클릭하고 Set as Start Destination을 클릭합니다.

대상 연결

작업은 대상 간의 논리적 연결입니다. 작업은 탐색 그래프에서 화살표로 표시됩니다. 일반적으로 작업은 한 대상을 다른 대상에 연결합니다. 그러나 앱의 어디에서나 특정 대상으로 이동할 수 있는 전역 작업을 만들 수도 있습니다.

작업을 사용하여 사용자가 앱에서 선택할 수 있는 다양한 경로를 표시합니다. 실제로 대상으로 이동하려면 탐색을 실행하기 위한 코드를 작성해야 합니다. 이 내용은 이 주제 뒷부분의 대상으로 이동 섹션에서 다룹니다.

Navigation Editor를 사용하여 두 대상을 연결하는 방법은 다음과 같습니다.

  1. Design 탭에서 사용자가 이동해 올 대상의 오른쪽 위로 마우스를 가져갑니다. 그림 4와 같이 대상의 오른쪽에 원이 나타납니다.

    그림 4. 작업 연결 원이 있는 대상

  2. 커서를 클릭하고 사용자가 이동해 갈 대상 위로 드래그한 후 놓습니다. 그림 5와 같이 두 대상 사이의 결과 선이 작업을 나타냅니다.

    그림 5. 작업으로 대상 연결

  3. 화살표를 클릭하여 작업을 강조표시합니다. 다음 속성은 Attributes 패널에 표시됩니다.

    • Type 필드에는 '작업'이 포함됩니다.
    • ID 필드에는 작업의 ID가 포함됩니다.
    • Destination 필드에는 대상 프래그먼트 또는 활동의 ID가 포함됩니다.

  4. Text 탭을 클릭하여 XML 뷰로 전환합니다. 이제 작업 요소가 소스 대상에 추가되었습니다. 아래 예와 같이 작업에는 ID와 다음 대상의 ID가 포함된 대상 속성이 있습니다.

    <?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:android="http://schemas.android.com/apk/res/android"
    app:startDestination="@id/blankFragment">
    <fragment
        android:id="@+id/blankFragment"
        android:name="com.example.cashdog.cashdog.BlankFragment"
        android:label="@string/label_blank"
        tools:layout="@layout/fragment_blank" >
        <action
            android:id="@+id/action_blankFragment_to_blankFragment2"
            app:destination="@id/blankFragment2" />
    </fragment>
    <fragment
        android:id="@+id/blankFragment2"
        android:name="com.example.cashdog.cashdog.BlankFragment2"
        android:label="@string/label_blank_2"
        tools:layout="@layout/fragment_blank_fragment2" />
</navigation>

탐색 그래프에서 작업은 <action> 요소로 표시됩니다. 최소한 작업에는 자체 ID와 사용자가 탐색해야 하는 대상의 ID가 포함됩니다.

대상으로 이동하는 것은 NavController 객체를 사용하여 실행되며 이 객체는 NavHost 내에서 앱 탐색을 관리합니다. 각 NavHost에는 해당하는 자체 NavController가 있습니다. 다음 메서드 중 하나를 사용하여 NavController를 검색할 수 있습니다.

Kotlin:

자바:

FragmentContainerView를 사용하여 NavHostFragment를 만들 때 또는 FragmentTransaction을 통해 NavHostFragment를 활동에 수동으로 추가할 경우 Navigation.findNavController(Activity, @IdRes int)를 통해 활동의 onCreate()에서 NavController를 검색하려고 하면 실패합니다. 대신 NavHostFragment에서 직접 NavController를 검색해야 합니다.

Kotlin

val navHostFragment =
        supportFragmentManager.findFragmentById(R.id.nav_host_fragment) as NavHostFragment
val navController = navHostFragment.navController

자바

NavHostFragment navHostFragment =
        (NavHostFragment) getSupportFragmentManager().findFragmentById(R.id.nav_host_fragment);
NavController navController = navHostFragment.getNavController();

Safe Args를 사용하여 유형 안전성 보장

대상 간 이동을 위해 Safe Args Gradle 플러그인을 사용하는 것이 좋습니다. 이 플러그인은 대상 간 유형 안전 탐색 및 인수 전달을 사용 설정하는 간단한 객체 및 빌더 클래스를 생성합니다.

프로젝트에 Safe Args를 추가하려면 최상위 build.gradle 파일에 다음의 classpath를 포함합니다.

Groovy

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.5.3"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

Kotlin

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.5.3"
        classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version")
    }
}

또한 사용 가능한 두 가지 플러그인 중 하나를 적용해야 합니다.

자바 모듈 또는 자바와 Kotlin 혼합 모듈에 적합한 자바 언어 코드를 생성하려면 앱 또는 모듈의 build.gradle 파일에 다음 행을 추가합니다.

Groovy

plugins {
  id 'androidx.navigation.safeargs'
}

Kotlin

plugins {
    id("androidx.navigation.safeargs")
}

또는 Kotlin 전용 모듈에 적합한 Kotlin 코드를 생성하려면 다음을 추가하세요.

Groovy

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

Kotlin

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

AndroidX로 이전에 따라 gradle.properties 파일에 android.useAndroidX=true가 있어야 합니다.

Safe Args를 사용 설정하면 플러그인은 정의된 각 작업의 클래스 및 메서드가 포함된 코드를 생성합니다. Safe Args는 각 작업마다 작업이 탐색을 시작하는 대상인 각 발신 대상의 클래스도 생성합니다. 생성된 클래스 이름은 발신 대상 클래스 이름과 'Directions'라는 단어의 조합입니다. 예를 들어 대상의 이름이 SpecifyAmountFragment라면 생성된 클래스의 이름은 SpecifyAmountFragmentDirections입니다. 생성된 클래스에는 발신 대상에서 정의한 각 작업의 정적 메서드가 포함됩니다. 이 메서드는 정의된 작업 매개변수를 인수로 사용하고 navigate()에 전달할 수 있는 NavDirections 객체를 반환합니다.

예를 들어 발신 대상(SpecifyAmountFragment)을 수신 대상(ConfirmationFragment)에 연결하는 단일 작업이 포함된 탐색 그래프가 있다고 가정해 보겠습니다.

Safe Args는 NavDirections 객체를 반환하는 actionSpecifyAmountFragmentToConfirmationFragment()라는 단일 메서드가 있는 SpecifyAmountFragmentDirections 클래스를 생성합니다. 그런 다음, 아래 예에 나와 있는 것처럼 이 반환된 NavDirections 객체를 navigate()에 직접 전달할 수 있습니다.

Kotlin

override fun onClick(view: View) {
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment()
    view.findNavController().navigate(action)
}

자바

@Override
public void onClick(View view) {
    NavDirections action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment();
    Navigation.findNavController(view).navigate(action);
}

Safe Args를 사용하여 대상 간에 데이터를 전달하는 방법에 관한 자세한 내용은 Safe Args를 사용하여 유형 안전성을 갖춘 데이터 전달을 참고하세요.

추가 정보

탐색에 문제가 있다면 다음 채널 중 하나를 통해 의견을 제출하세요.

버그 신고에 가장 유용한 정보를 제공하는 방법은 다음 링크를 참고하세요.