Aktualizacja aplikacji Maps JavaScript API z wersji 2 do 3

Od 26 maja 2021 r. interfejs Maps JavaScript API w wersji 2 nie jest już dostępny. W efekcie mapy w wersji 2 witryny przestaną działać i będą zwracać błędy JavaScriptu. Aby nadal korzystać z map w swojej witrynie, przejdź na interfejs Maps JavaScript API w wersji 3. Ten przewodnik pomoże Ci przejść przez cały proces.

Przegląd

Każda aplikacja przechodzi nieco inny proces migracji, ale są pewne kroki wspólne dla wszystkich projektów:

  1. Uzyskaj nowy klucz. Interfejs Maps JavaScript API korzysta teraz z konsoli Google Cloud do zarządzania kluczami. Jeśli nadal używasz klucza w wersji 2, przed rozpoczęciem migracji uzyskaj nowy klucz interfejsu API.
  2. Zaktualizuj interfejs API Bootstrap. Większość aplikacji wczyta interfejs Maps JavaScript API w wersji 3 za pomocą tego kodu:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. Zaktualizuj kod. Ilość wymaganych zmian w dużym stopniu zależy od Twojej aplikacji. Typowe zmiany:
    • Zawsze uwzględniaj przestrzeń nazw google.maps. W wersji 3 cały kod JavaScript API Map Google jest przechowywany w przestrzeni nazw google.maps.*, a nie w globalnej przestrzeni nazw. W ramach tego procesu zmieniły się również nazwy większości obiektów. Na przykład zamiast GMap2 wczytasz teraz google.maps.Map.
    • Usuń wszelkie odwołania do przestarzałych metod. Usunięto wiele metod uniwersalnego przeznaczenia, takich jak GDownloadURL i GLog. Zastąp tę funkcję bibliotekami narzędziowymi innych firm lub usuń te odwołania z kodu.
    • (Opcjonalnie) Dodaj biblioteki do kodu. Wiele funkcji zostało przeniesionych do zewnętrznych bibliotek, aby każda aplikacja mogła wczytywać tylko te części interfejsu API, które będą używane.
    • (Opcjonalnie) Skonfiguruj w projekcie środowisko zewnętrzne w wersji 3. Obiekty zewnętrzne w wersji 3 mogą służyć do weryfikowania kodu za pomocą kompilatora Closure Compiler lub do aktywowania autouzupełniania w IDE. Dowiedz się więcej o kompilacji zaawansowanej i elementach Extern.
  4. Testowanie i powielanie. Na tym etapie masz jeszcze trochę pracy do wykonania, ale mamy dobrą wiadomość: wszystko jest na dobrej drodze, by zacząć korzystać z nowej aplikacji z mapami w wersji 3.

Zmiany w interfejsie Maps JavaScript API w wersji 3

Przed zaplanowaniem migracji warto poznać różnice między interfejsem Maps JavaScript API w wersji 2 i Maps JavaScript API w wersji 3. Najnowsza wersja interfejsu Maps JavaScript API została napisana od podstaw z myślą o nowoczesnych technikach programowania JavaScript, większym wykorzystaniu bibliotek i uproszczonym interfejsie API. Do interfejsu API dodano wiele nowych funkcji. Zmodyfikowaliśmy lub usunęliśmy kilka znanych funkcji. W tej sekcji omawiamy główne różnice między tymi wersjami.

Oto niektóre zmiany w interfejsie API wersji 3:

  • Usprawniona główna biblioteka. Wiele funkcji dodatkowych zostało przeniesionych do bibliotek, co pozwoliło skrócić czas wczytywania i analizy interfejsu API Core, który umożliwia szybkie wczytywanie mapy na dowolnym urządzeniu.
  • Zwiększono wydajność kilku funkcji, takich jak renderowanie wielokątów i umieszczanie znaczników.
  • Nowe podejście do limitów wykorzystania po stronie klienta mające na celu lepszą obsługę współdzielonych adresów używanych przez mobilne serwery proxy i firmowe zapory sieciowe.
  • Dodaliśmy obsługę kilku nowoczesnych przeglądarek i przeglądarek mobilnych. Wyłączono obsługę Internet Explorera 6.
  • Usunięto wiele klas pomocniczych do zwykłych obciążeń ( GLog lub GDownloadUrl). Istnieje wiele świetnych bibliotek JavaScript o podobnych funkcjach, takich jak Closure czy jQuery.
  • Implementacja Street View HTML5, która będzie ładowana na każdym urządzeniu mobilnym.
  • Niestandardowe panoramy Street View z Twoimi zdjęciami, które umożliwiają Ci udostępnianie panoram stoków narciarskich, domów na sprzedaż lub innych ciekawych miejsc.
  • Dostosowania stylowych map, które umożliwiają zmianę wyświetlania elementów na mapie podstawowej w celu dopasowania do Twojego niepowtarzalnego stylu wizualnego.
  • Obsługa kilku nowych usług, takich jak ElevationService i matryca odległości.
  • Ulepszone usługi wyznaczania trasy obejmują trasy alternatywne, optymalizację trasy (przybliżone rozwiązania problemu podróżnego sprzedawcy), wskazówki dojazdu rowerem (z warstwą rowerową), wskazówki dojazdu transportem publicznym i wskazówki, które można przeciągać.
  • Zaktualizowany format geokodowania, który zapewnia dokładniejsze informacje o atrybucie type niż wartość accuracy z interfejsu Geocoding API w wersji 2.
  • obsługa wielu okien informacyjnych na jednej mapie,

Uaktualnianie aplikacji

Twój nowy klucz

Interfejs Maps JavaScript API w wersji 3 wykorzystuje nowy system kluczy z wersji 2. Być może używasz już w swojej aplikacji klucza w wersji 3. W takim przypadku nie musisz wprowadzać żadnych zmian. Aby to sprawdzić, sprawdź parametr key w adresie URL, z którego wczytujesz interfejs Maps JavaScript API. Jeśli wartość klucza zaczyna się od „ABQIAA”, używasz klucza w wersji 2. Jeśli masz klucz w wersji 2, w ramach migracji musisz uaktualnić go do wersji v3, co spowoduje:

Klucz jest przekazywany podczas wczytywania interfejsu Maps JavaScript API w wersji 3. Więcej informacji o generowaniu kluczy interfejsu API

Pamiętaj, że jeśli jesteś klientem Google Maps API for Work, możliwe, że zamiast key możesz używać identyfikatora klienta z parametrem client. Identyfikatory klientów są nadal obsługiwane w interfejsie Maps JavaScript API w wersji 3 i nie wymagają procesu uaktualniania klucza.

Wczytywanie interfejsu API

Pierwsza modyfikacja kodu, jaką musisz wprowadzić, obejmuje sposób wczytywania interfejsu API. W wersji 2 interfejs Maps JavaScript API wczytuje się za pomocą żądania wysyłanego do: http://maps.google.com/maps. Jeśli wczytujesz interfejs Maps JavaScript API w wersji 3, musisz wprowadzić te zmiany:

  1. Wczytaj interfejs API z //maps.googleapis.com/maps/api/js
  2. Usuń parametr file.
  3. Zaktualizuj parametr key nowym kluczem w wersji 3. Klienci korzystający z interfejsów Google Maps API for Work powinni używać parametru client.
  4. (Tylko w przypadku abonamentu Premium) Upewnij się, że parametr client jest podany w sposób opisany w Przewodniku dla programistów, który udostępnia abonament Premium w Google Maps Platform.
  5. Usuń parametr v, aby zażądać najnowszej wersji, lub zmień jego wartość zgodnie ze schematem obsługi wersji 3.
  6. (Opcjonalnie) Zastąp parametr hl wartością language i zachowaj jego wartość.
  7. (Opcjonalnie) Dodaj parametr libraries, aby wczytywać biblioteki opcjonalne.

W najprostszym przypadku pobieranie w wersji 3 określa tylko parametr klucza interfejsu API:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

Przykład poniżej zawiera żądanie najnowszej wersji interfejsu Maps JavaScript API v2 w języku niemieckim:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

Przykład poniżej to równoważne żądanie w wersji 3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

Przedstawiamy przestrzeń nazw google.maps

Prawdopodobnie najbardziej zauważalną zmianą w interfejsie Maps JavaScript API w wersji 3 jest wprowadzenie przestrzeni nazw google.maps. Interfejs API w wersji 2 domyślnie umieszcza wszystkie obiekty w globalnej przestrzeni nazw, co może powodować konflikty nazw. W wersji 3 wszystkie obiekty znajdują się w przestrzeni nazw google.maps.

Podczas migracji aplikacji do wersji 3 musisz zmienić kod, aby skorzystać z nowej przestrzeni nazw. Niestety wyszukanie litery „G” i zastępowanie jej ciągiem „google.maps”. Nie zadziała, ale podczas sprawdzania kodu warto zastosować się do reguły. Poniżej znajdziesz kilka przykładów równoważnych klas w wersjach 2 i 3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Usuwanie przestarzałego kodu

Interfejs Maps JavaScript API w wersji 3 ma równolegle większości funkcji dostępnych w wersji 2. Niektóre klasy nie są już obsługiwane. W trakcie migracji musisz zastąpić te klasy bibliotekami narzędziowymi innych firm albo usunąć te odwołania z kodu. Istnieje wiele świetnych bibliotek JavaScript o podobnych funkcjach, np. Closure lub jQuery.

Te klasy nie mają równoległego odpowiednika w interfejsie Maps JavaScript API w wersji 3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Porównanie kodu

Porównajmy 2 proste aplikacje napisane przy użyciu interfejsów API w wersjach 2 i 3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

Jak widać, między tymi aplikacjami występuje kilka różnic. Najważniejsze zmiany:

  • Zmienił się adres, z którego załadowano interfejs API.
  • Metody GBrowserIsCompatible() i GUnload() nie są już wymagane w wersji 3, więc zostały usunięte z interfejsu API.
  • Obiekt GMap2 zostaje zastąpiony przez google.maps.Map jako centralny obiekt w interfejsie API.
  • Właściwości są teraz wczytywane przez klasy opcji. W powyższym przykładzie ustawiliśmy 3 właściwości wymagane do wczytania mapy – center, zoom i mapTypeId – za pomocą wbudowanego obiektu MapOptions.
  • W wersji 3 domyślny interfejs użytkownika jest domyślnie włączony. Możesz wyłączyć tę opcję, ustawiając wartość właściwości disableDefaultUI w obiekcie MapOptions na wartość Prawda.

Podsumowanie

Masz już jednak przedsmak najważniejszych punktów związanych z migracją z wersji 2 do 3 interfejsu Maps JavaScript API. Możesz potrzebować więcej informacji, ale będą one zależały od Twojej aplikacji. W kolejnych sekcjach zamieściliśmy instrukcje migracji dotyczące konkretnych przypadków, w których możesz natrafić. Masz też do dyspozycji kilka materiałów, które mogą Ci się przydać podczas uaktualniania.

Jeśli masz problemy lub pytania związane z tym artykułem, kliknij link PRZEŚLIJ OPINIĘ u góry tej strony.

Szczegółowe źródła

W tej sekcji znajdziesz szczegółowe porównanie najpopularniejszych funkcji interfejsu Maps JavaScript API w wersjach 2 i 3. Każdą sekcję należy czytać oddzielnie. Nie zalecamy zapoznawania się z tym materiałem w całości. Zamiast tego możesz korzystać z tego materiału, aby dostosować proces migracji do poszczególnych przypadków.

  • Zdarzenia – rejestrowanie i obsługa zdarzeń.
  • Elementy sterujące – sterowanie elementami sterującymi wyświetlanymi na mapie.
  • Nakładki – dodawanie i edytowanie obiektów na mapie.
  • Typy map – kafelki tworzące mapę bazową.
  • Warstwy – dodawanie i edytowanie treści w ramach grupy, np. warstw KML lub natężenia ruchu.
  • Usługi – obsługa geokodowania, wskazówek dojazdu lub usług Street View.

Wydarzenia

Model zdarzeń dla interfejsu Maps JavaScript API w wersji 3 jest podobny do tego w wersji 2, ale wiele już się zmieniło.

Opcje

Interfejs Maps JavaScript API wyświetla elementy sterujące interfejsu, które pozwalają użytkownikom na interakcję z mapą. Za pomocą interfejsu API możesz dostosować sposób wyświetlania tych opcji.

Nakładki reklamowe

Nakładki to obiekty, które „dodasz” do mapy, aby wyznaczyć punkty, linie, obszary lub zbiory obiektów.

Typy map

Typy map dostępne w wersjach 2 i 3 nieco się różnią, ale wszystkie podstawowe typy map są dostępne w obu wersjach interfejsu API. Domyślnie wersja 2 używa standardowych „malowanych” fragmentów mapy drogowej. Wersja 3 wymaga jednak, aby podczas tworzenia obiektu google.maps.Map podać określony typ mapy.

Warstwy

Warstwy to obiekty na mapie, które składają się z co najmniej 1 nakładki. Można ich używać jako pojedynczej jednostki i zwykle odzwierciedla ona zbiory obiektów.

Usługi