メインコンテンツまでスキップ
For the complete documentation index, see llms.txt.

Navigation Screen

The NAVIGATION screen is the main screen for the Android Auto navigation experience. It combines Free Drive, Route Preview, and Active Guidance in a single map screen and is available starting with Car API Level 7.

The screen observes the state of your app's MapboxNavigation instance and reacts to route changes automatically. You do not need to replace the screen when moving between previewing a route and navigating along it.

Choose the entry screen​

On lower Car API levels, use the FREE_DRIVE screen as the entry point to navigation:

val initialScreen = if (carContext.supportsUnifiedNavigation()) {
    MapboxScreen.NAVIGATION
} else {
    MapboxScreen.FREE_DRIVE
}

Keep the map setup, location permission checks, and navigation lifecycle management described in Get Started. Selecting NAVIGATION does not replace those setup steps.

React to navigation state​

Internally, the screen's routes provider attaches to MapboxNavigation through MapboxNavigationApp. It reads the current active routes and route preview when attached, then listens for updates through RoutesObserver and RoutesPreviewObserver.

The screen chooses its mode from that state, in the following order:

Navigation stateScreen modeCamera mode
Active navigation routes are availableActive GuidanceFollowing
No active routes, but preview routes are availableRoute PreviewOverview
Neither active nor preview routes are availableFree DriveFollowing

Active routes take precedence over preview routes. If a preview exists while MapboxNavigation has active routes, the screen continues showing Active Guidance. Clearing active routes returns to Route Preview if preview routes still exist, or Free Drive if they do not.

Changes made to the same MapboxNavigation instance elsewhere in your app, including on the phone, are reflected in the car screen. For example:

  • Updating preview routes with setRoutesPreview() shows Route Preview when there are no active routes.
  • Setting active routes with setNavigationRoutes() switches to Active Guidance.
  • Clearing preview routes returns to Free Drive only when there are no active routes.

The screen updates its template when the mode or preview route list changes. Guidance information updates independently through CarNavigationInfoProvider, which requests a template refresh when its information changes.

Free Drive​

Free Drive uses a NavigationTemplate without turn-by-turn guidance. The camera follows the user's location, while map components display the location, road label, and speed limit.

Route Preview​

Route Preview uses a MapWithContentTemplate containing a route list alongside the map. The camera switches to Overview so the driver can inspect the route.

The driver can select a route from the list or tap a route line on the map. Both interactions update the primary preview route. A map selection also refreshes the template so the list reflects the selected route. The number of routes shown in the list respects the car system's route-list content limit.

Selecting the navigation action starts guidance on the chosen preview route, retaining the other preview routes as alternatives. Pressing Back while previewing clears the preview instead of leaving the screen.

Active Guidance​

Active Guidance uses a NavigationTemplate with turn-by-turn information and the car system's native travel-estimate card. The camera switches to Following. The route line, guidance markers, and navigation information update using the active navigation routes and guidance data.

Outside Route Preview, pressing Back delegates to MapboxScreenManager to navigate back.

Map components and lifecycle​

The screen reuses the same map components across all three modes:

  • CarLocationRenderer: Displays the user's location.
  • CarRoadLabelRenderer: Displays the road label.
  • CarSpeedLimitRenderer: Displays speed-limit information.
  • CarNavigationCamera: Handles Following and Overview camera modes and map gestures.
  • CarRouteLineRenderer: Displays routes and handles route-line taps during preview.
  • CarActiveGuidanceMarkers: Displays navigation markers.
  • CarNavigationInfoProvider: Supplies guidance information for the template.

Switching modes does not detach and recreate these components. They stay registered while the screen is resumed, keeping the map in place as the navigation experience changes.

When the screen pauses, it unregisters the map components, clears the gesture handler, and unregisters its arrival trigger. It registers them again on resume and restores the camera mode appropriate to the current state. The routes provider remains registered for the screen's lifetime, from creation until destruction, so it can continue observing route state while another screen is on top.

Customize the screen​

The screen reads route-line options and action-strip configuration from MapboxCarContext. Set these options when creating the context, before the screen is created, as shown in Get Started.

Route-line configuration​

Set routeLineRendererOptions in the context's customize block. The screen passes these options to CarRouteLineRenderer when constructing it. A single renderer displays both preview routes and active navigation routes, so the configuration applies across Route Preview and Active Guidance.

import com.mapbox.maps.extension.androidauto.MapboxCarMap
import com.mapbox.navigation.base.ExperimentalPreviewMapboxNavigationAPI
import com.mapbox.navigation.ui.androidauto.MapboxCarContext
import com.mapbox.navigation.ui.androidauto.preview.CarRouteLineRendererOptions
import com.mapbox.navigation.ui.androidauto.screenmanager.prepareScreens

// Inside your Session class. Keep the map setup described in Get Started.
@OptIn(ExperimentalPreviewMapboxNavigationAPI::class)
private val mapboxCarContext = MapboxCarContext(lifecycle, MapboxCarMap())
    .prepareScreens()
    .customize {
        routeLineRendererOptions = CarRouteLineRendererOptions.Builder()
            .build()
    }

This example uses the default route-line options. Supply your configured CarRouteLineRendererOptions to customize rendering without replacing the navigation screen. Route-line configuration controls rendering, not route calculation or which routes are active: those still come from the observed MapboxNavigation state.

The renderer's route-click callback is connected to the screen's preview selection logic. Tapping a different preview route selects it and refreshes the route list; tapping a route outside Route Preview does not change the selection.

Mode-specific action strips​

Set actionsStripProvider in the context's customize block to supply your action-strip provider. The screen reads the configured provider as options.actionStripProvider.

Although the screen is registered as MapboxScreen.NAVIGATION, it requests actions using the key for its current mode:

  • MapboxScreen.FREE_DRIVE
  • MapboxScreen.ROUTE_PREVIEW
  • MapboxScreen.ACTIVE_GUIDANCE

Use these keys to supply different actions for each mode, such as search during Free Drive or a stop-navigation action during Active Guidance. Handle the button callbacks in your provider; adding an action does not by itself change navigation state.

この{Type}は役に立ちましたか？