Przewodnik po migracji

Ostrzeżenie: ten dokument może zawierać nieaktualne informacje. Pracujemy nad rozwiązaniem tego problemu, ale tymczasem zachęcamy do zapoznania się ze stroną Pierwsze kroki, gdzie znajdziesz przykładowe aplikacje. Pokazują one zachowania i wzorce użytkowania interfejsów API, które pomogą Ci w migracji z wersji 1.

Największą zmianą wprowadzoną przez Google w pakiecie SDK do nawigacji w wersji 2 jest to, że zastąpiliśmy kilka klas nawigacji ich odpowiednikami z pakietu Maps SDK na Androida.

Od wersji 2.2 pakiet Navigation SDK jest (prawie) zwykłym zamiennikiem interfejsu API Map usług Google Play. Zamiast przepakowywać wszystkie interfejsy API do com.google.android.libraries.maps, zostały one spakowane w komponencie com.google.android.gms.maps tak, jak w przypadku Usług Google Play. Znacznie ułatwia to przełączanie się między wersją Usług Google Play a pakietem SDK nawigacji.

Uwaga: te instrukcje dotyczą tylko wersji 2.2 i nowszych.

Zalety

• Lepsze wykorzystanie pamięci. Wykorzystujesz teraz mniej pamięci i przepustowości niż w przypadku korzystania jednocześnie z pakietu Navigation SDK oraz pakietu Maps SDK na Androida.
• Przełączanie się z trybu widoku mapy na tryb nawigacji jest teraz płynniejsze i łatwiejsze w obsłudze.
• Teraz masz większą kontrolę nad kamerą.
• Możesz teraz rysować linie łamane i nakładki oraz dodawać do mapy style niestandardowe.

Jednak takie funkcje jak Street View i wersja uproszczona nie są obsługiwane.

Ważne: pakiet SDK nawigacji zastąpi pakiet SDK Map Google na Androida. Trzeba będzie usunąć wszelkie odniesienia do klienta.

Wymagania wstępne

• Wersja 2 pakietu SDK nawigacji korzysta z Androida Jetpacka – pakietu bibliotek, narzędzi i wskazówek, które ułatwiają pisanie wysokiej jakości aplikacji. Oznacza to, że aby używać AndroidX, musisz przeprowadzić migrację aplikacji, korzystając z bibliotek pomocy. Więcej informacji znajdziesz w artykule o migracji na AndroidaX.

Krok 1. Migracja z pakietu Maps SDK na Androida

Większość funkcji pakietu Maps SDK na Androida znajduje się teraz w wersji 2 pakietu Navigation SDK. Usunęliśmy kilka funkcji, ponieważ nie były potrzebne w kontekście nawigacji.

Ważne różnice

Pakiet SDK Map Google na Androida był dostępny w Usługach Google Play.

Funkcje pakietu Maps SDK na Androida, które są zawarte w wersji 2 pakietu Navigation SDK, są oparte na nowej wersji pakietu Maps SDK na Androida i nie znajdują się w Usługach Google Play. Te nowe funkcje działają w nowszym silniku niż te dostępne w Usługach Google Play, ale mają kilka ulepszeń. Oznacza to również, że mapa jest uruchomiona w procesie Twojej aplikacji, a nie w procesie usługi Google Play.

Nazwa niektórych zajęć została zmieniona

W tabeli poniżej znajdziesz listę zajęć, których nazwy zostały zmienione. W ten sposób odróżniliśmy te aplikacje od ich odpowiednika w pakiecie SDK Map Google na Androida.

Nazwa klasy pakietu Maps SDK na Androida	Nazwa klasy pakietu SDK nawigacji
MapView.java	NavigationView.java
MapFragment.java	SupportNavigationFragment.java

Te klasy zawierają połączenie metod dostępnych w starej klasie NavigationView z bieżącą klasą MapView. Możesz je sobie wyobrazić jako klasy MapView i MapFragment, ale z obsługą nawigacji.

Usunięte funkcje

Niektóre funkcje Map zostały usunięte, ponieważ nie miały sensu w kontekście nawigacji lub wystąpiły niezgodności techniczne. Usunięte funkcje:

• Street View
• wersji uproszczonej, która jest niewystarczająca do nawigacji.
• Nie możesz ustawić LocationProvider, gdy kamera jest w trybie śledzenia. Dzieje się tak, ponieważ nawigacja korzysta z elementu RoadSnappedLocationProvider, a przełączenie się na tego dostawcę może spowodować problemy z nawigacją.
• Zastosowanie min./maks. powiększenia i progów LatLng nie będzie działać, gdy kamera jest w trybie śledzenia.
• Jeśli te brakujące funkcje powodują problemy, skontaktuj się z przedstawicielem klienta.

Etapy migracji

1. Usuń z kompilacji pakiet SDK Map Google na Androida (np. Gradle). Użycie obu pakietów SDK spowoduje błędy kompilacji.
2. Zastąp instancje MapView instancjami NavigationView.
3. Zastąp instancje MapFragment instancjami NavigationSupportFragment.

Jeśli Twoja aplikacja nie korzystała wcześniej z pakietu Navigation SDK, migracja została zakończona.

Krok 2. Migracja z wersji 1.x pakietu Navigation SDK

Wykonaj poniższe czynności, aby przenieść integrację z pakietem Navigation SDK w wersji 1.x do wersji 2.

1. Pobierz mapę za pomocą nowych metod

Zmienił się sposób pobierania mapy. W wersjach wcześniejszych niż 2 można było uzyskać mapę przy użyciu wywołania synchronicznego. Teraz posłużysz się wywołaniem synchronicznym. W tabeli poniżej znajdziesz stare metody oraz nowe metody pobierania mapy.

Stara metoda	Nowa metoda
NavigationView.getMap()	NavigationView.getMapAsync()
SupportNavigationFragment.getMap()	SupportNavigationFragment.getMapAsync()

Uwaga: klasa NavigationFragment została usunięta, ponieważ klasa Fragment została wycofana i zastąpiona klasą SupportFragment.

2. Migracja bibliotek

Wersja 1.x pakietu Navigation SDK zawiera własną implementację kilku klas tego pakietu na Androida. Te klasy należały do pakietu com.google.android.libraries.navigation.

W wersji 2 te klasy zostały zastąpione przez implementacje pakietu SDK Map Google na Androida, które znajdują się w pakiecie com.google.android.gms.maps.model. Możesz przenieść swoją aplikację, aby zintegrować nowe klasy, wyszukując i zastępując.

Tabela poniżej zawiera zarówno stare, jak i nowe klasy.

Stara klasa	Nowe zajęcia
com.google.android.libraries.navigation.LatLng	com.google.android.gms.maps.model.LatLng
com.google.android.libraries.navigation.LatLngBounds	com.google.android.gms.maps.model.LatLngBounds
com.google.android.libraries.navigation.Marker	com.google.android.gms.maps.model.Marker
com.google.android.libraries.navigation.MarkerOptions	com.google.android.gms.maps.model.MarkerOptions
com.google.android.libraries.navigation.VisibleRegion	com.google.android.gms.maps.model.VisibleRegion

3. Wprowadzanie zmian w istniejących interfejsach API

W tabeli poniżej znajdziesz najważniejsze zmiany wprowadzone przez Google w wersji 2 pakietu SDK do nawigacji.

Metoda	Zmień
NavigationApi.cleanup()	Usunięto. Ta metoda nie była używana do normalnego działania i może spowodować nieprzewidywalne zachowanie. Musisz usunąć wywołania tej metody.
RoadSnappedLocationProvider.requestLocationUpdates()	Usunięto. Użyj w zamian zasady addLocationListener().
RoadSnappedLocationProvider.stopRequestingLocationUpdates()	Usunięto. Użyj w zamian zasady removeLocationListener().

4. Przejdź na nową klasę znacznika

Wersja 2 pakietu Navigation SDK korzysta teraz z tej samej implementacji klasy Marker co pakiet SDK Map Google na Androida. Wprowadzimy następujące zmiany.

Metody związane ze znacznikami

Metoda	Zmień
addMarker(MarkerOptions markerOptions)	Używa teraz klasy com.google.android.gms.maps.model.MarkerOptions.
removeMarker(Marker marker)	Ta metoda już nie istnieje. Klasa znacznika ma teraz metodę marker.remove().
removeAllMarkers()	Ta metoda już nie istnieje, ale dostępna jest metoda clear(), która usuwa z mapy wszystkie znaczniki, linie łamane, wielokąty i warstwy.

Różnice w znacznikach

• Metoda describeContents() nie występuje w wersji 2 pakietu Navigation SDK. Umożliwiło Ci to zapisanie danych widoku przez wywołanie onSaveInstanceState(). Teraz musisz samodzielnie śledzić szczegóły widoku, aby móc go ponownie utworzyć, gdy nastąpi zmiana konfiguracji.
• Metoda navMarker#icon(BitMap) została zmieniona na mapMarker#icon(BitmapDescriptor). Ta zmiana wymaga przejścia z BitMap na BitmapDescriptor.

Metody zaznaczania

Będziesz teraz używać klasy Marker z pakietu com.google.android.gms.maps.model. W tabeli poniżej znajdziesz różnice w korzystaniu z nowej klasy Marker.

Metoda	Zmień
getAnchorU()	Już nie istnieje.
getAnchorV()	Już nie istnieje.
getIcon()	Już nie istnieje. Musisz samodzielnie utrzymać odniesienie do tej ikony, aby móc z niej korzystać po zmianie konfiguracji, gdy trzeba będzie odtworzyć stan mapy.
getPosition()	Nadal istnieje.
getTitle()	Nadal istnieje.

Uwaga: jeśli potrzebujesz usuniętych metod z klasy znacznika, poinformuj nas o tym, a my pomożemy Ci rozwiązać ten problem.

5. Sterowanie kamerą

Elementy sterujące aparatem dostępne w wersji 1.x pakietu Navigation SDK były względnie ograniczone. Wersja 2 pakietu SDK do nawigacji korzysta teraz z tego samego modelu aparatu, który jest używany w pakiecie Maps SDK na Androida, z tą różnicą, że dostępny jest tryb śledzenia podobny do tego w pakiecie Navigation SDK w wersji 1.x.

Główne różnice

• Klasa com.google.android.libraries.navigation.Camera została usunięta w wersji 2.
  • Element Camera.showRouteOverview() został przeniesiony do folderów NavigationView i SupportNavigationFragment.
  • Metoda Camera.followMyLocation() została przeniesiona do: GoogleMap.
• Połączenia do Camera.setLocation() możesz zastąpić wartością GoogleMap.moveCamera() lub GoogleMap.animateCamera().
• Do tych sekcji: GoogleMap dodano atrybuty setOnFollowMyLocationCallback() i isCameraFollowingMyLocation(), aby dostarczyć więcej informacji o trybie obserwowania.

Krok 3. Scal przepływy działań

Jeśli korzystasz z wersji 1 pakietu Navigation SDK i wykonasz podane wyżej instrukcje, przeniesiesz przypadki użycia mapy do klasy NavigationView i przeniesiesz przypadki użycia nawigacji do GoogleMap. Powstają jednak 2 wystąpienia GoogleMap i 2 wystąpienia NavigationView. Oznacza to, że nadal będziesz wykorzystywać więcej pamięci, niż jest to konieczne, a przełączanie się między 2 instancjami może spowodować zauważalne przerwy w płynnym renderowaniu interfejsu. Aby rozwiązać ten problem, należy scalić przepływy aktywności/fragmentów, aby mogły współużytkować jedną instancję. Zapewnia to wygodę użytkowników i ułatwia obsługę aplikacji.