This topic shows you how to set up and work with the Navigation component. For
a high level overview of the Navigation component, see the
Navigation overview.

Set up your environment

To import the Navigation libraries into your Android project, follow the
steps to declare dependencies in the Navigation release notes.

Create a navigation graph

Navigation occurs between your app’s destinations—that
is, anywhere in your app to which users can navigate. These destinations are
connected via actions.

A navigation graph is a resource file that contains all of your destinations
and actions. The graph represents all of your app’s navigation paths.

Figure 1 shows a visual representation of a navigation graph for a sample app
containing six destinations connected by five actions. Each destination is
represented by a preview thumbnail, and connecting actions are represented by
arrows that show how users can navigate from one destination to another.

Figure 1. A navigation graph that shows previews of
six different destinations that are connected via five actions.
  1. Destinations are the different content areas in your app.
  2. Actions are logical connections between your destinations that
    represent paths that users can take.

To add a navigation graph to your project, do the following:

  1. In the Project window, right-click on the res directory and select
    New > Android Resource File. The New Resource File dialog appears.
  2. Type a name in the File name field, such as “nav_graph”.
  3. Select Navigation from the Resource type drop-down list, and then
    click OK.

When you add your first navigation graph, Android Studio creates a navigation
resource directory within the res directory. This directory contains your
navigation graph resource file (nav_graph.xml, for example).

After adding a graph, Android Studio opens the graph in the Navigation Editor.
In the Navigation Editor, you can visually edit navigation graphs or directly
edit the underlying XML.


Figure 2. The Navigation Editor
  1. Destinations panel: Lists your navigation host and all destinations
    currently in the Graph Editor.
  2. Graph Editor: Contains a visual representation of your navigation
    graph. You can switch between Design view and the
    underlying XML representation in the Text view.
  3. Attributes: Shows attributes for the currently-selected item in the
    navigation graph.

Click the Text tab to see the corresponding XML, which should look similar
to the following snippet:

<?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>

The <navigation> element is the root element of a navigation graph. As you
add destinations and connecting actions to your graph, you can see the
corresponding <destination> and <action> elements here as child elements.
If you have
nested graphs,
they appear as child <navigation> elements.

One of the core parts of the Navigation component is the navigation host. The
navigation host is an empty container where destinations are swapped in and out
as a user navigates through your app.

A navigation host must derive from
NavHost. The Navigation
component’s default NavHost implementation,
NavHostFragment,
handles swapping fragment destinations.

Add a NavHostFragment via XML

The XML example below shows a NavHostFragment as part of an app’s main
activity:

<?xml version="1.0" encoding="utf-8"?>
<android.support.constraint.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
        .../>

    <fragment
        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
        .../>

</android.support.constraint.ConstraintLayout>

Note the following:

  • The android:name attribute contains the class name of your NavHost
    implementation.
  • The app:navGraph attribute associates the NavHostFragment with a
    navigation graph. The navigation graph specifies all of the destinations in
    this NavHostFragment to which users can navigate.
  • The app:defaultNavHost="true" attribute ensures that your NavHostFragment
    intercepts the system Back button. Note that only one NavHost can be the
    default. If you have multiple hosts in the same layout (two-pane layouts, for
    example), be sure to specify only one default NavHost.

You can also use the Layout Editor to add a
NavHostFragment to an activity by doing the following:

  1. In your list of project files, double-click on your activity’s layout XML
    file to open it in the Layout Editor.
  2. Within the Palette pane, choose the Containers category, or alternatively
    search for “NavHostFragment”.
  3. Drag the NavHostFragment view onto your activity.
  4. Next, in the Navigation Graphs dialog that appears, choose the
    corresponding navigation graph to associate with this NavHostFragment, and
    then click OK.

There are three different ways to add destinations to your navigation graph.
You can create a destination from an existing fragment or activity, create a
new destination, or create a placeholder to later replace with a fragment or
activity.

Create a destination from an existing fragment or activity

If you have an existing destination type that you’d like to add to your
navigation graph, click New Destination
,
and then click on the corresponding destination in the dropdown that appears.
You can now see a preview of the destination in the Design view along with
the corresponding XML in the Text view of your navigation graph.

Create a new destination

To add a new destination type using the Navigation Editor, do the following:

  1. In the Navigation Editor, click the New Destination icon
    ,
    and then click Create new destination.
  2. In the New Android Component dialog that appears, create your fragment.
    For more information on fragments, see the fragment documentation.

Back in the Navigation Editor, notice that Android Studio has added this
destination to the graph.

Figure 3 shows an example of a destination and a
placeholder destination.

Figure 3. A destination and a placeholder

Placeholder destinations

You can use placeholders to represent unimplemented destinations.
A placeholder serves as a visual representation of a destination. Within the
Navigation Editor, you can use placeholders just as you would any
other destination.

Anatomy of a destination

Click on any destination to select it, and note the following attributes in the
Attributes panel:

  • The Type field indicates whether the destination is implemented as a
    fragment, activity, or other custom class in your source code.
  • The Label field contains the name of the destination’s XML layout file.
  • The ID field contains the ID of the destination which is used to refer
    to the destination in code.
  • The Class dropdown shows the name of the class that is associated with the
    destination. You can click this dropdown to change the associated class to
    another destination type.

Click the Text tab to show the XML view of your navigation graph. The XML
contains the same id, name, label, and layout attributes for the
destination, as shown below:

<?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="Blank"
        tools:layout="@layout/fragment_blank" />
</navigation>

Designate a screen as the start destination

The start destination
is the first screen users see when opening your app, and it’s the last screen
users see when exiting your app. The Navigation editor uses a house icon

to indicate the start destination.

Once you have all of your destinations in place, you can choose a start
destination by doing the following:

  1. In the Design tab, click on the destination to highlight it.

  2. Click the Assign start destination button .
    Alternatively, you can right-click on the destination and click
    Set as Start Destination.

Connect destinations

An action is a logical connection between destinations. Actions are
represented in the navigation graph as arrows. Actions usually connect one
destination to another, though you can also create
global actions
that take you to a specific destination from anywhere in your app.

With actions, you’re representing the different paths that users can take
through your app. Note that to actually navigate to destinations, you still need
to write the code to perform the navigation. This is covered in the
Navigate to a destination section later in this topic.

You can use the Navigation Editor to connect two destinations by doing the
following:

  1. In the Design tab, hover over the right side of the destination that you
    want users to navigate from. A circle appears over the right side of the
    destination.

    Figure 4. A destination with an action connection
    circle
  2. Click and drag your cursor over the destination you want users to
    navigate to, and release. The resulting line between the two destinations
    represents an action.

    Figure 5. Connecting destinations with an action
  3. Click on the arrow to highlight the action. The following attributes appear
    in the Attributes panel:

    • The Type field contains “Action”.
    • The ID field contains the ID for the action.
    • The Destination field contains the ID for the destination fragment or
      activity.
  4. Click the Text tab to toggle to the XML view. An action element is now
    added to the source destination. The action has an ID and a destination
    attribute that contains the ID of the next destination, as shown in the
    example below:

    <?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="fragment_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="fragment_blank_fragment2"
            tools:layout="@layout/fragment_blank_fragment2" />
    </navigation>
    

In your navigation graph, actions are represented by <action> elements. At a
minimum, an action contains its own ID and the ID of the destination to which a
user should be taken.

Navigating to a destination is done using a
NavController, an object
that manages app navigation within a NavHost. Each NavHost has its own
corresponding NavController.

To retrieve the NavController for a fragment, activity, or view, use one of
the following methods:

Kotlin:

Java:

Once you retrieve a
NavController, use its
navigate()
method to navigate to a destination. The
navigate()
method accepts a resource ID of either an action or a destination.

The following code snippet shows how to navigate to the
ViewTransactionsFragment:

Kotlin

viewTransactionsButton.setOnClickListener { view ->
   view.findNavController().navigate(R.id.viewTransactionsAction)
}

Java

viewTransactionsButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View view) {
        Navigation.findNavController(view).navigate(R.id.viewTransactionsAction);
    }
});

For buttons, you can also use the
Navigation class’s
createNavigateOnClickListener()
convenience method to navigate to a destination, as shown in the following
example:

Kotlin

button.setOnClickListener(Navigation.createNavigateOnClickListener(R.id.next_fragment, null))

Java

button.setOnClickListener(Navigation.createNavigateOnClickListener(R.id.next_fragment, null));

To handle other common UI components, such as the top app bar and bottom
navigation, see
Update UI components with NavigationUI.

Android maintains a back stack
that contains the destinations you’ve visited. The first destination of your app
is placed on the stack when the user opens the app. Each call to the
navigate()
method puts another destination on top of the stack. Pressing Up or Back calls
the
NavController.navigateUp()
and NavController.popBackStack()
methods, respectively, to remove (or pop) the top destination off of the
stack.

popUpTo and popUpToInclusive

When navigating using an action, you can optionally pop additional destinations
off of the back stack. For example, if your app has an initial login flow, once
a user has logged in, you should pop all of the login-related destinations off
of the back stack so that the Back button doesn’t take users back into the login
flow.

To pop destinations when navigating from one destination to another, add a
app:popUpTo attribute to the associated <action> element. app:popUpTo
tells the Navigation library to pop some destinations off of the back stack as
part of the call to navigate(). The attribute value is the ID of the most
recent destination that should remain on the stack.

You can also include app:popUpToInclusive="true" to indicate that the
destination specified in app:popUpTo should also be removed from the back
stack.

Let’s say that your app has three destinations—A, B, and C—along
with actions that lead from A to B, B to C, and C back to A. The corresponding
navigation graph is shown in figure 6:

Figure 6. A circular navigation graph with three destinations: A, B, and C.

With each navigation action, a destination is added to the back stack. If you
were to navigate repeatedly through this flow, your back stack would then
contain multiple sets of each destination (A, B, C, A, B, C, A, and so on).
To avoid this repetition, you can specify app:popUpTo and
app:popUpToInclusive in the action that takes you from destination C to
destination A, as shown in the following example:

<fragment
    android:id="@+id/c"
    android:name="com.example.myapplication.C"
    android:label="fragment_c"
    tools:layout="@layout/fragment_c">

    <action
        android:id="@+id/action_c_to_a"
        app:destination="@id/a"
        app:popUpTo="@+id/a"
        app:popUpToInclusive="true"/>
</fragment>

After reaching destination C, the back stack contains one instance of each
destination (A, B, C). When navigating back to destination A, we also popUpTo
A, which means that we remove B and C from the stack while navigating. With
app:popUpToInclusive="true", we also pop that first A off of the stack,
effectively clearing it. Notice here that if you don’t use
app:popUpToInclusive, your back stack would contain two instances of
destination A.

More information

If you encounter any issues with Navigation, please submit feedback via one
of the following channels:

For information on how to provide the most helpful information in bug reports,
see the following links:



Source link

LEAVE A REPLY

Please enter your comment!
Please enter your name here