Platform Android Studio Google Play Jetpack Kotlin Docs News
Visão geral Guias Referência Amostras Design & Quality
Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

NavigationUI

class NavigationUI
kotlin.Any
   ↳ androidx.navigation.ui.NavigationUI

Class which hooks up elements typically in the 'chrome' of your application such as global navigation patterns like a navigation drawer or bottom nav bar with your NavController.

Summary

Public methods
static Boolean
navigateUp(@NonNull navController: NavController, @Nullable drawerLayout: DrawerLayout?)

Handles the Up button by delegating its behavior to the given NavController.
static Boolean
navigateUp(@NonNull navController: NavController, @NonNull configuration: AppBarConfiguration)

Handles the Up button by delegating its behavior to the given NavController.
static Boolean
onNavDestinationSelected(@NonNull item: MenuItem, @NonNull navController: NavController)

Attempt to navigate to the NavDestination associated with the given MenuItem.
static Unit
setupActionBarWithNavController(@NonNull activity: AppCompatActivity, @NonNull navController: NavController)

Sets up the ActionBar returned by AppCompatActivity#getSupportActionBar() for use with a NavController.
static Unit
setupActionBarWithNavController(@NonNull activity: AppCompatActivity, @NonNull navController: NavController, @Nullable drawerLayout: DrawerLayout?)

Sets up the ActionBar returned by AppCompatActivity#getSupportActionBar() for use with a NavController.
static Unit
setupActionBarWithNavController(@NonNull activity: AppCompatActivity, @NonNull navController: NavController, @NonNull configuration: AppBarConfiguration)

Sets up the ActionBar returned by AppCompatActivity#getSupportActionBar() for use with a NavController.
static Unit
setupWithNavController(@NonNull toolbar: Toolbar, @NonNull navController: NavController)

Sets up a Toolbar for use with a NavController.
static Unit
setupWithNavController(@NonNull toolbar: Toolbar, @NonNull navController: NavController, @Nullable drawerLayout: DrawerLayout?)

Sets up a Toolbar for use with a NavController.
static Unit
setupWithNavController(@NonNull toolbar: Toolbar, @NonNull navController: NavController, @NonNull configuration: AppBarConfiguration)

Sets up a Toolbar for use with a NavController.
static Unit
setupWithNavController(@NonNull collapsingToolbarLayout: CollapsingToolbarLayout, @NonNull toolbar: Toolbar, @NonNull navController: NavController)

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.
static Unit
setupWithNavController(@NonNull collapsingToolbarLayout: CollapsingToolbarLayout, @NonNull toolbar: Toolbar, @NonNull navController: NavController, @Nullable drawerLayout: DrawerLayout?)

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.
static Unit
setupWithNavController(@NonNull collapsingToolbarLayout: CollapsingToolbarLayout, @NonNull toolbar: Toolbar, @NonNull navController: NavController, @NonNull configuration: AppBarConfiguration)

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.
static Unit
setupWithNavController(@NonNull navigationView: NavigationView, @NonNull navController: NavController)

Sets up a NavigationView for use with a NavController.
static Unit
setupWithNavController(@NonNull bottomNavigationView: BottomNavigationView, @NonNull navController: NavController)

Sets up a BottomNavigationView for use with a NavController.

Public methods

navigateUp

static fun navigateUp(@NonNull navController: NavController, @Nullable drawerLayout: DrawerLayout?): Boolean

Handles the Up button by delegating its behavior to the given NavController. This should generally be called from AppCompatActivity#onSupportNavigateUp().

If you do not have a DrawerLayout, you should call NavController#navigateUp() directly.

Parameters
navController NavController: The NavController that hosts your content.
drawerLayout NavController: The DrawerLayout that should be opened if you are on the topmost level of the app.
Return
Boolean: True if the NavController was able to navigate up.

navigateUp

static fun navigateUp(@NonNull navController: NavController, @NonNull configuration: AppBarConfiguration): Boolean

Handles the Up button by delegating its behavior to the given NavController. This is an alternative to using NavController#navigateUp() directly when the given AppBarConfiguration needs to be considered when determining what should happen when the Up button is pressed.

In cases where no Up action is available, the AppBarConfiguration#getFallbackOnNavigateUpListener() will be called to provide additional control.

Parameters
navController NavController: The NavController that hosts your content.
configuration NavController: Additional configuration options for determining what should happen when the Up button is pressed.
Return
Boolean: True if the NavController was able to navigate up.

onNavDestinationSelected

static fun onNavDestinationSelected(@NonNull item: MenuItem, @NonNull navController: NavController): Boolean

Attempt to navigate to the NavDestination associated with the given MenuItem. This MenuItem should have been added via one of the helper methods in this class.

Importantly, it assumes the menu item id matches a valid action id or destination id to be navigated to.

By default, the back stack will be popped back to the navigation graph's start destination. Menu items that have android:menuCategory="secondary" will not pop the back stack.

Parameters
item MenuItem: The selected MenuItem.
navController MenuItem: The NavController that hosts the destination.
Return
Boolean: True if the NavController was able to navigate to the destination associated with the given MenuItem.

setupActionBarWithNavController

static fun setupActionBarWithNavController(@NonNull activity: AppCompatActivity, @NonNull navController: NavController): Unit

Sets up the ActionBar returned by AppCompatActivity#getSupportActionBar() for use with a NavController.

By calling this method, the title in the action bar will automatically be updated when the destination changes (assuming there is a valid label).

The start destination of your navigation graph is considered the only top level destination. On all other destinations, the ActionBar will show the Up button. Call NavController#navigateUp() to handle the Up button.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
activity AppCompatActivity: The activity hosting the action bar that should be kept in sync with changes to the NavController.
navController AppCompatActivity: The NavController that supplies the secondary menu. Navigation actions on this NavController will be reflected in the title of the action bar.

setupActionBarWithNavController

static fun setupActionBarWithNavController(@NonNull activity: AppCompatActivity, @NonNull navController: NavController, @Nullable drawerLayout: DrawerLayout?): Unit

Sets up the ActionBar returned by AppCompatActivity#getSupportActionBar() for use with a NavController.

By calling this method, the title in the action bar will automatically be updated when the destination changes (assuming there is a valid label).

The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the ActionBar will show the drawer icon if the given DrawerLayout is non null. On all other destinations, the ActionBar will show the Up button. Call navigateUp(NavController, DrawerLayout) to handle the Up button.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
activity AppCompatActivity: The activity hosting the action bar that should be kept in sync with changes to the NavController.
navController AppCompatActivity: The NavController whose navigation actions will be reflected in the title of the action bar.
drawerLayout AppCompatActivity: The DrawerLayout that should be toggled from the home button

setupActionBarWithNavController

static fun setupActionBarWithNavController(@NonNull activity: AppCompatActivity, @NonNull navController: NavController, @NonNull configuration: AppBarConfiguration): Unit

Sets up the ActionBar returned by AppCompatActivity#getSupportActionBar() for use with a NavController.

By calling this method, the title in the action bar will automatically be updated when the destination changes (assuming there is a valid label).

The AppBarConfiguration you provide controls how the Navigation button is displayed. Call navigateUp(NavController, AppBarConfiguration) to handle the Up button.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
activity AppCompatActivity: The activity hosting the action bar that should be kept in sync with changes to the NavController.
navController AppCompatActivity: The NavController whose navigation actions will be reflected in the title of the action bar.
configuration AppCompatActivity: Additional configuration options for customizing the behavior of the ActionBar

setupWithNavController

static fun setupWithNavController(@NonNull toolbar: Toolbar, @NonNull navController: NavController): Unit

Sets up a Toolbar for use with a NavController.

By calling this method, the title in the Toolbar will automatically be updated when the destination changes (assuming there is a valid label).

The start destination of your navigation graph is considered the only top level destination. On all other destinations, the Toolbar will show the Up button. This method will call NavController#navigateUp() when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
toolbar Toolbar: The Toolbar that should be kept in sync with changes to the NavController.
navController Toolbar: The NavController that supplies the secondary menu. Navigation actions on this NavController will be reflected in the title of the Toolbar.

setupWithNavController

static fun setupWithNavController(@NonNull toolbar: Toolbar, @NonNull navController: NavController, @Nullable drawerLayout: DrawerLayout?): Unit

Sets up a Toolbar for use with a NavController.

By calling this method, the title in the Toolbar will automatically be updated when the destination changes (assuming there is a valid label).

The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the Toolbar will show the drawer icon if the given DrawerLayout is non null. On all other destinations, the Toolbar will show the Up button. This method will call navigateUp(NavController, DrawerLayout) when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
toolbar Toolbar: The Toolbar that should be kept in sync with changes to the NavController.
navController Toolbar: The NavController whose navigation actions will be reflected in the title of the Toolbar.
drawerLayout Toolbar: The DrawerLayout that should be toggled from the Navigation button

setupWithNavController

static fun setupWithNavController(@NonNull toolbar: Toolbar, @NonNull navController: NavController, @NonNull configuration: AppBarConfiguration): Unit

Sets up a Toolbar for use with a NavController.

By calling this method, the title in the Toolbar will automatically be updated when the destination changes (assuming there is a valid label).

The AppBarConfiguration you provide controls how the Navigation button is displayed and what action is triggered when the Navigation button is tapped. This method will call navigateUp(NavController, AppBarConfiguration) when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
toolbar Toolbar: The Toolbar that should be kept in sync with changes to the NavController.
navController Toolbar: The NavController whose navigation actions will be reflected in the title of the Toolbar.
configuration Toolbar: Additional configuration options for customizing the behavior of the Toolbar

setupWithNavController

static fun setupWithNavController(@NonNull collapsingToolbarLayout: CollapsingToolbarLayout, @NonNull toolbar: Toolbar, @NonNull navController: NavController): Unit

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.

By calling this method, the title in the CollapsingToolbarLayout will automatically be updated when the destination changes (assuming there is a valid label).

The start destination of your navigation graph is considered the only top level destination. On all other destinations, the Toolbar will show the Up button. This method will call NavController#navigateUp() when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
collapsingToolbarLayout CollapsingToolbarLayout: The CollapsingToolbarLayout that should be kept in sync with changes to the NavController.
toolbar CollapsingToolbarLayout: The Toolbar that should be kept in sync with changes to the NavController.
navController CollapsingToolbarLayout: The NavController that supplies the secondary menu. Navigation actions on this NavController will be reflected in the title of the Toolbar.

setupWithNavController

static fun setupWithNavController(@NonNull collapsingToolbarLayout: CollapsingToolbarLayout, @NonNull toolbar: Toolbar, @NonNull navController: NavController, @Nullable drawerLayout: DrawerLayout?): Unit

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.

By calling this method, the title in the CollapsingToolbarLayout will automatically be updated when the destination changes (assuming there is a valid label).

The start destination of your navigation graph is considered the only top level destination. On the start destination of your navigation graph, the Toolbar will show the drawer icon if the given DrawerLayout is non null. On all other destinations, the Toolbar will show the Up button. This method will call navigateUp(NavController, DrawerLayout) when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
collapsingToolbarLayout CollapsingToolbarLayout: The CollapsingToolbarLayout that should be kept in sync with changes to the NavController.
toolbar CollapsingToolbarLayout: The Toolbar that should be kept in sync with changes to the NavController.
navController CollapsingToolbarLayout: The NavController whose navigation actions will be reflected in the title of the Toolbar.
drawerLayout CollapsingToolbarLayout: The DrawerLayout that should be toggled from the Navigation button

setupWithNavController

static fun setupWithNavController(@NonNull collapsingToolbarLayout: CollapsingToolbarLayout, @NonNull toolbar: Toolbar, @NonNull navController: NavController, @NonNull configuration: AppBarConfiguration): Unit

Sets up a CollapsingToolbarLayout and Toolbar for use with a NavController.

By calling this method, the title in the CollapsingToolbarLayout will automatically be updated when the destination changes (assuming there is a valid label).

The AppBarConfiguration you provide controls how the Navigation button is displayed and what action is triggered when the Navigation button is tapped. This method will call navigateUp(NavController, AppBarConfiguration) when the Navigation button is clicked.

Destinations that implement androidx.navigation.FloatingWindow will be ignored.

Parameters
collapsingToolbarLayout CollapsingToolbarLayout: The CollapsingToolbarLayout that should be kept in sync with changes to the NavController.
toolbar CollapsingToolbarLayout: The Toolbar that should be kept in sync with changes to the NavController.
navController CollapsingToolbarLayout: The NavController whose navigation actions will be reflected in the title of the Toolbar.
configuration CollapsingToolbarLayout: Additional configuration options for customizing the behavior of the Toolbar

setupWithNavController

static fun setupWithNavController(@NonNull navigationView: NavigationView, @NonNull navController: NavController): Unit

Sets up a NavigationView for use with a NavController. This will call onNavDestinationSelected(MenuItem, NavController) when a menu item is selected. The selected item in the NavigationView will automatically be updated when the destination changes.

If the NavigationView is directly contained with a DrawerLayout, the drawer will be closed when a menu item is selected.

Similarly, if the NavigationView has a BottomSheetBehavior associated with it (as is the case when using a com.google.android.material.bottomsheet.BottomSheetDialog), the bottom sheet will be hidden when a menu item is selected.

Parameters
navigationView NavigationView: The NavigationView that should be kept in sync with changes to the NavController.
navController NavigationView: The NavController that supplies the primary and secondary menu. Navigation actions on this NavController will be reflected in the selected item in the NavigationView.

setupWithNavController

static fun setupWithNavController(@NonNull bottomNavigationView: BottomNavigationView, @NonNull navController: NavController): Unit

Sets up a BottomNavigationView for use with a NavController. This will call onNavDestinationSelected(MenuItem, NavController) when a menu item is selected. The selected item in the BottomNavigationView will automatically be updated when the destination changes.

Parameters
bottomNavigationView BottomNavigationView: The BottomNavigationView that should be kept in sync with changes to the NavController.
navController BottomNavigationView: The NavController that supplies the primary menu. Navigation actions on this NavController will be reflected in the selected item in the BottomNavigationView.