Poruszanie się po trasie obejmującej jedno miejsce docelowe

Uwaga: fromLatLng() i fromPlaceId() zostały wycofane, ale pozostaną dostępne bez dalszych aktualizacji. Zalecamy przejście na nową wersję Waypoint.Builder.

Z tego przewodnika dowiesz się, jak wytyczyć trasę w swojej aplikacji za pomocą pakietu SDK nawigacji na Androida. W tym przewodniku przyjęto, że masz już zintegrowany pakiet SDK nawigacji z aplikacją zgodnie z opisem w sekcji Konfigurowanie projektu.

Podsumowanie

1. Dodaj element interfejsu do aplikacji, np. fragment nawigacji lub widok nawigacyjny. Ten element interfejsu dodaje do Twojej aktywności interaktywną mapę i szczegółowy interfejs nawigacji.
2. Poproś o dostęp do lokalizacji. Aplikacja musi poprosić o dostęp do lokalizacji, aby określić lokalizację urządzenia.
3. Zainicjuj pakiet SDK za pomocą klasy NavigationApi.

4. Ustaw miejsce docelowe i kontroluj nawigację zakręt po zakręcie za pomocą klasy Navigator. Składa się on z 3 kroków:

   • Ustaw miejsce docelowe, używając setDestination().
   • Rozpocznij nawigację, klikając startGuidance().
   • getSimulator() pozwala symulować poruszanie się pojazdu na trasie oraz w celu testowania, debugowania i prezentowania aplikacji.

5. Stwórz i uruchom aplikację.

Wyświetl kod

< > Pokaż lub ukryj kod Java na potrzeby aktywności związanej z nawigacją w jednym miejscu docelowym.

package com.example.navsdksingledestination;

import android.content.pm.PackageManager;
import android.os.Bundle;
import android.support.v4.app.ActivityCompat;
import android.support.v4.content.ContextCompat;
import android.support.v7.app.AppCompatActivity;
import android.util.Log;
import android.widget.Toast;
import androidx.annotation.NonNull;
import com.google.android.libraries.navigation.Camera;
import com.google.android.libraries.navigation.ListenableResultFuture;
import com.google.android.libraries.navigation.NavigationApi;
import com.google.android.libraries.navigation.Navigator;
import com.google.android.libraries.navigation.RoutingOptions;
import com.google.android.libraries.navigation.SimulationOptions;
import com.google.android.libraries.navigation.SupportNavigationFragment;
import com.google.android.libraries.navigation.Waypoint;

/**
 * An activity that displays a map and a navigation UI, guiding the user
 * from their current location to a single, given destination.
 */
public class NavigationActivitySingleDestination extends AppCompatActivity {

    private static final String TAG = NavigationActivitySingleDestination.class.getSimpleName();
    private Navigator mNavigator;
    private SupportNavigationFragment mNavFragment;
    private RoutingOptions mRoutingOptions;

    // Define the Sydney Opera House by specifying its place ID.
    private static final String SYDNEY_OPERA_HOUSE = "ChIJ3S-JXmauEmsRUcIaWtf4MzE";

    // Set fields for requesting location permission.
    private static final int PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION = 1;
    private boolean mLocationPermissionGranted;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Initialize the Navigation SDK.
        initializeNavigationSdk();
    }

    /**
     * Starts the Navigation SDK and sets the camera to follow the device's location.
     * Calls the navigateToPlace() method when the navigator is ready.
     */
    private void initializeNavigationSdk() {
        /*
         * Request location permission, so that we can get the location of the
         * device. The result of the permission request is handled by a callback,
         * onRequestPermissionsResult.
         */
        if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
                android.Manifest.permission.ACCESS_FINE_LOCATION)
                    == PackageManager.PERMISSION_GRANTED) {
            mLocationPermissionGranted = true;
        } else {
            ActivityCompat.requestPermissions(this,
                    new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION },
                    PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
        }

        if (!mLocationPermissionGranted) {
            displayMessage("Error loading Navigation SDK: "
                    + "The user has not granted location permission.");
            return;
        }

        // Get a navigator.
        NavigationApi.getNavigator(this, new NavigationApi.NavigatorListener() {
                    /**
                     * Sets up the navigation UI when the navigator is ready for use.
                     */
                    @Override
                    public void onNavigatorReady(Navigator navigator) {
                        displayMessage("Navigator ready.");
                        mNavigator = navigator;
                        mNavFragment = (SupportNavigationFragment) getFragmentManager()
                                .findFragmentById(R.id.navigation_fragment);

                        // Set the last digit of the car's license plate to get route restrictions
                        // in supported countries. (optional)
                        // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ");

                        // Set the camera to follow the device location with 'TILTED' driving view.
                        mNavFragment.getCamera().followMyLocation(Camera.Perspective.TILTED);

                        // Set the travel mode (DRIVING, WALKING, CYCLING, or TWO_WHEELER).
                        mRoutingOptions =  new RoutingOptions();
                        mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING);

                        // Navigate to a place, specified by Place ID.
                        navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions);
                    }

                    /**
                     * Handles errors from the Navigation SDK.
                     * @param errorCode The error code returned by the navigator.
                     */
                    @Override
                    public void onError(@NavigationApi.ErrorCode int errorCode) {
                        switch (errorCode) {
                            case NavigationApi.ErrorCode.NOT_AUTHORIZED:
                                displayMessage("Error loading Navigation SDK: Your API key is "
                                        + "invalid or not authorized to use the Navigation SDK.");
                                break;
                            case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                                displayMessage("Error loading Navigation SDK: User did not accept "
                                        + "the Navigation Terms of Use.");
                                break;
                            case NavigationApi.ErrorCode.NETWORK_ERROR:
                                displayMessage("Error loading Navigation SDK: Network error.");
                                break;
                            case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                                displayMessage("Error loading Navigation SDK: Location permission "
                                        + "is missing.");
                                break;
                            default:
                                displayMessage("Error loading Navigation SDK: " + errorCode);
                        }
                    }
                });
    }

    /**
     * Requests directions from the user's current location to a specific place (provided
     * by the Google Places API).
     */
    private void navigateToPlace(String placeId, RoutingOptions travelMode) {
        Waypoint destination;
        try {
            destination = Waypoint.builder().setPlaceIdString(placeId).build();
        } catch (Waypoint.UnsupportedPlaceIdException e) {
            displayMessage("Error starting navigation: Place ID is not supported.");
            return;
        }

        // Create a future to await the result of the asynchronous navigator task.
        ListenableResultFuture<Navigator.RouteStatus> pendingRoute =
                mNavigator.setDestination(destination, travelMode);

        // Define the action to perform when the SDK has determined the route.
        pendingRoute.setOnResultListener(
                new ListenableResultFuture.OnResultListener<Navigator.RouteStatus>() {
                    @Override
                    public void onResult(Navigator.RouteStatus code) {
                        switch (code) {
                            case OK:
                                // Hide the toolbar to maximize the navigation UI.
                                if (getActionBar() != null) {
                                    getActionBar().hide();
                                }

                                // Enable voice audio guidance (through the device speaker).
                                mNavigator.setAudioGuidance(
                                        Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE);

                                // Simulate vehicle progress along the route for demo/debug builds.
                                if (BuildConfig.DEBUG) {
                                    mNavigator.getSimulator().simulateLocationsAlongExistingRoute(
                                            new SimulationOptions().speedMultiplier(5));
                                }

                                // Start turn-by-turn guidance along the current route.
                                mNavigator.startGuidance();
                                break;
                            // Handle error conditions returned by the navigator.
                            case NO_ROUTE_FOUND:
                                displayMessage("Error starting navigation: No route found.");
                                break;
                            case NETWORK_ERROR:
                                displayMessage("Error starting navigation: Network error.");
                                break;
                            case ROUTE_CANCELED:
                                displayMessage("Error starting navigation: Route canceled.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }

    /**
     * Handles the result of the request for location permissions.
     */
    @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String permissions[],
                                           @NonNull int[] grantResults) {
        mLocationPermissionGranted = false;
        switch (requestCode) {
            case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: {
                // If request is canceled, the result arrays are empty.
                if (grantResults.length > 0
                        && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                    mLocationPermissionGranted = true;
                }
            }
        }
    }

    /**
     * Shows a message on screen and in the log. Used when something goes wrong.
     * @param errorMessage The message to display.
     */
    private void displayMessage(String errorMessage) {
        Toast.makeText(this, errorMessage, Toast.LENGTH_LONG).show();
        Log.d(TAG, errorMessage);
    }
}

Dodaj element interfejsu do aplikacji

W tej sekcji omawiamy 2 sposoby dodawania interaktywnej mapy i interfejsu do wyświetlania szczegółowej nawigacji.

Używanie fragmentu nawigacji

SupportNavigationFragment to komponent interfejsu, który wyświetla wizualne dane wyjściowe nawigacji, m.in. interaktywną mapę i szczegółowe wskazówki. Możesz zadeklarować ten fragment w pliku układu XML, jak w przykładzie poniżej:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.navigation.SupportNavigationFragment"
    android:id="@+id/navigation_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Fragment możesz też utworzyć automatycznie, zgodnie z opisem w dokumentacji Androida, używając narzędzia FragmentActivity.getSupportFragmentManager().

Korzystanie z widoku nawigacyjnego

Zamiast fragmentu można użyć komponentu UI, który wyświetla mapę na potrzeby nawigacji. Dostępny jest też komponent NavigationView.

Uwaga: zapoznaj się ze wskazówkami u góry opisu klasy NavigationView, w szczególności ze wskazówkami dotyczącymi prawidłowego przekazywania dalej i wywoływania metod cyklu życia z aktywności lub fragmentu zawierającego widok.

Poproś o dostęp do lokalizacji

W tej sekcji dowiesz się, jak poprosić o dostęp do dokładnej lokalizacji. Więcej informacji znajdziesz w przewodniku dotyczącym uprawnień Androida.

1. Dodaj uprawnienie jako element podrzędny elementu <manifest> w pliku manifestu Androida:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="com.example.navsdksingledestination">
       <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   </manifest>
   

2. Wysyłanie w aplikacji prośby o uprawnienia w czasie działania, dając użytkownikowi możliwość przyznania lub odmowy dostępu do lokalizacji. Ten kod sprawdza, czy użytkownik przyznał dostęp do dokładnej lokalizacji. W przeciwnym razie prosi o odpowiednie uprawnienia:

   if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
           android.Manifest.permission.ACCESS_FINE_LOCATION)
               == PackageManager.PERMISSION_GRANTED) {
       mLocationPermissionGranted = true;
   } else {
       ActivityCompat.requestPermissions(this,
               new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION },
               PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
   }
   
   if (!mLocationPermissionGranted) {
       displayMessage("Error loading Navigation SDK: "
               + "The user has not granted location permission.");
       return;
   }
   

3. Zastąp wywołanie zwrotne onRequestPermissionsResult(), aby obsłużyć wynik prośby o uprawnienia:

   @Override
   public void onRequestPermissionsResult(int requestCode, @NonNull String permissions[],
                                          @NonNull int[] grantResults) {
       mLocationPermissionGranted = false;
       switch (requestCode) {
           case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: {
               // If request is canceled, the result arrays are empty.
               if (grantResults.length > 0
                       && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                   mLocationPermissionGranted = true;
               }
           }
       }
   }
   

Inicjowanie pakietu SDK nawigacji

Klasa NavigationApi udostępnia logikę inicjowania, która upoważnia aplikację do korzystania z nawigacji w Google. W tej sekcji opisujemy, jak uruchomić nawigator, a także inne konfiguracje, które można włączyć w aplikacji:

1. Zainicjuj pakiet SDK nawigacji i zastąp wywołanie zwrotne onNavigatorReady(), aby rozpocząć nawigację, gdy nawigator będzie gotowy.

2. Opcjonalnie. Skonfiguruj aplikację tak, aby powiadomienia o wskazówkach i usługi w tle wyłączały się, gdy użytkownik zamknie aplikację na urządzeniu. Wybór zależy od modelu biznesowego. Możesz użyć domyślnego sposobu nawigacji, który wyświetla informacje o zakręcie i aktualizacje lokalizacji nawet po zamknięciu aplikacji. Użyj tej konfiguracji, jeśli chcesz wyłączyć aktualizacje nawigacji i lokalizacji po zamknięciu aplikacji przez użytkownika.

3. Opcjonalnie. Włącz ograniczenia ruchu w obsługiwanych krajach. Ustaw ostatnią cyfrę tablicy rejestracyjnej. Wywołanie to należy wykonać tylko raz: kolejne żądania wskazówki dojazdu nadal będą z niego korzystać. Ta rozmowa działa tylko w obsługiwanych regionach. Sprawdź kraje, w których dostępny jest pakiet nawigacyjny SDK.

   NavigationApi.getNavigator(this, new NavigationApi.NavigatorListener() {
               /**
                * Sets up the navigation UI when the navigator is ready for use.
                */
               @Override
               public void onNavigatorReady(Navigator navigator) {
                   displayMessage("Navigator ready.");
                   mNavigator = navigator;
                   mNavFragment = (NavigationFragment) getFragmentManager()
                           .findFragmentById(R.id.navigation_fragment);
   
                   // Optional. Disable the guidance notifications and shut down the app
                   // and background service when the user closes the app.
                   // mNavigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)
   
                   // Optional. Set the last digit of the car's license plate to get
                   // route restrictions for supported countries.
                   // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ");
   
                   // Set the camera to follow the device location with 'TILTED' driving view.
                   mNavFragment.getCamera().followMyLocation(Camera.Perspective.TILTED);
   
                   // Set the travel mode (DRIVING, WALKING, CYCLING, TWO_WHEELER, or TAXI).
                   mRoutingOptions = new RoutingOptions();
                   mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING);
   
                   // Navigate to a place, specified by Place ID.
                   navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions);
               }
   
               /**
                * Handles errors from the Navigation SDK.
                * @param errorCode The error code returned by the navigator.
                */
               @Override
               public void onError(@NavigationApi.ErrorCode int errorCode) {
                   switch (errorCode) {
                       case NavigationApi.ErrorCode.NOT_AUTHORIZED:
                           displayMessage("Error loading Navigation SDK: Your API key is "
                                   + "invalid or not authorized to use the Navigation SDK.");
                           break;
                       case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                           displayMessage("Error loading Navigation SDK: User did not accept "
                                   + "the Navigation Terms of Use.");
                           break;
                       case NavigationApi.ErrorCode.NETWORK_ERROR:
                           displayMessage("Error loading Navigation SDK: Network error.");
                           break;
                       case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                           displayMessage("Error loading Navigation SDK: Location permission "
                                   + "is missing.");
                           break;
                       default:
                           displayMessage("Error loading Navigation SDK: " + errorCode);
                   }
               }
           });
   

Ustaw miejsce docelowe

Klasa Navigator zapewnia kontrolę nad konfigurowaniem, uruchamianiem i zatrzymywaniem ścieżki nawigacji.

Korzystając z danych Navigator uzyskanych w poprzedniej sekcji, ustaw miejsce docelowe Waypoint dla tej ścieżki. Po wyznaczeniu wskazówek dojazdu SupportNavigationFragment wyświetla linię łamaną reprezentującą trasę na mapie oraz znacznik w miejscu docelowym.

    private void navigateToPlace(String placeId, RoutingOptions travelMode) {
        Waypoint destination;
        try {
            destination = Waypoint.builder().setPlaceIdString(placeId).build();
        } catch (Waypoint.UnsupportedPlaceIdException e) {
            displayMessage("Error starting navigation: Place ID is not supported.");
            return;
        }

        // Create a future to await the result of the asynchronous navigator task.
        ListenableResultFuture<Navigator.RouteStatus> pendingRoute =
                mNavigator.setDestination(destination, travelMode);

        // Define the action to perform when the SDK has determined the route.
        pendingRoute.setOnResultListener(
                new ListenableResultFuture.OnResultListener<Navigator.RouteStatus>() {
                    @Override
                    public void onResult(Navigator.RouteStatus code) {
                        switch (code) {
                            case OK:
                                // Hide the toolbar to maximize the navigation UI.
                                if (getActionBar() != null) {
                                    getActionBar().hide();
                                }

                                // Enable voice audio guidance (through the device speaker).
                                mNavigator.setAudioGuidance(
                                        Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE);

                                // Simulate vehicle progress along the route for demo/debug builds.
                                if (BuildConfig.DEBUG) {
                                    mNavigator.getSimulator().simulateLocationsAlongExistingRoute(
                                            new SimulationOptions().speedMultiplier(5));
                                }

                                // Start turn-by-turn guidance along the current route.
                                mNavigator.startGuidance();
                                break;
                            // Handle error conditions returned by the navigator.
                            case NO_ROUTE_FOUND:
                                displayMessage("Error starting navigation: No route found.");
                                break;
                            case NETWORK_ERROR:
                                displayMessage("Error starting navigation: Network error.");
                                break;
                            case ROUTE_CANCELED:
                                displayMessage("Error starting navigation: Route canceled.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }

Tworzenie i uruchamianie aplikacji

1. Podłącz urządzenie z Androidem do komputera. Wykonaj instrukcje Android Studio dotyczące uruchamiania aplikacji na urządzeniu sprzętowym. Możesz też skonfigurować urządzenie wirtualne za pomocą Menedżera urządzeń wirtualnych (AVD) Android. Wybierając emulator, pamiętaj, aby wybrać obraz zawierający interfejsy API Google.
2. W Android Studio kliknij opcję menu Uruchom lub ikonę przycisku odtwarzania. Wybierz urządzenie zgodnie z instrukcjami.

Wskazówki pomagające zwiększyć wygodę użytkowników

• Użytkownik musi zaakceptować Warunki korzystania z nawigacji Google, zanim nawigacja stanie się dostępna. Ta akceptacja jest wymagana tylko raz. Domyślnie pakiet SDK prosi o akceptację przy pierwszym wywołaniu nawigatora. Jeśli chcesz, możesz wywołać okno Warunki korzystania z nawigacji na wczesnym etapie interfejsu aplikacji, np. podczas rejestracji lub logowania, używając TermsAndConditionsCheckOption.
• Aby znacznie poprawić jakość nawigacji i dokładność szacowanego czasu dotarcia, do inicjowania punktu pośredniego użyj identyfikatorów miejsc zamiast współrzędnych szerokości i długości geograficznej.
• W tym przykładzie docelowy punkt na trasie jest określony na podstawie określonego identyfikatora miejsca opery w Sydney. Możesz skorzystać z wyszukiwarki identyfikatorów miejsc, aby uzyskać identyfikatory innych konkretnych lokalizacji.