Uaktualnianie aplikacji korzystającej z interfejsu Maps JavaScript API z wersji 2 na 3

Od 26 maja 2021 r. interfejs Maps JavaScript API w wersji 2 nie jest już dostępny. W efekcie mapy w wersji 2. Twojej witryny przestaną działać i zaczną zwracać błędy JavaScriptu. Aby nadal korzystać z map w swojej witrynie, zmień wersję Maps JavaScript API na 3. Ten przewodnik pomoże Ci w tym procesie.

Omówienie

Każda aplikacja ma nieco inny proces migracji, jednak niektóre kroki są wspólne dla wszystkich projektów:

  1. Uzyskaj nowy klucz. Interfejs Maps JavaScript API do zarządzania kluczami korzysta teraz z konsoli Google Cloud. Jeśli nadal używasz klucza w wersji 2, przed rozpoczęciem migracji pobierz nowy klucz API.
  2. Zaktualizuj bootstrap interfejsu API. Większość aplikacji wczytuje 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. Wymagana ilość zmian zależy w dużej mierze od aplikacji. Typowe zmiany to:
    • Zawsze odwołuj się do przestrzeni nazw google.maps. W wersji 3 cały kod interfejsu Maps JavaScript API jest przechowywany w przestrzeni nazw google.maps.*, a nie w przestrzeni nazw globalnej. W ramach tego procesu zmieniliśmy nazwy większości obiektów. Na przykład zamiast GMap2 będziesz wczytywać google.maps.Map.
    • Usuń wszelkie odwołania do przestarzałych metod. Usunięto kilka metod ogólnych, takich jak GDownloadURL i GLog. Zastąp tę funkcję zewnętrznymi bibliotekami narzędzi lub usuń te odwołania z kodu.
    • (Opcjonalnie) Dodaj biblioteki do kodu. Wiele funkcji zostało wyodrębnionych do zewnętrznych bibliotek narzędziowych, aby każda aplikacja wczytywała tylko te części interfejsu API, których potrzebuje.
    • (Opcjonalnie) Skonfiguruj projekt tak, aby używał zewnętrznych bibliotek wersji 3. Bibliotek zewnętrznych w wersji 3 można używać do sprawdzania kodu za pomocą kompilatora Closure Compiler lub do uruchamiania autouzupełniania w IDE. Dowiedz się więcej o  kompilacji zaawansowanej i zewnętrznych komponentach.
  4. Testuj i powtarzaj. W tym momencie nadal będziesz mieć trochę pracy, ale dobra wiadomość jest taka, że będziesz już blisko nowej wersji 3 map.

Zmiany w wersji 3 interfejsu Maps JavaScript API

Zanim zaplanujesz migrację, zapoznaj się z różnicami między interfejsem Maps JavaScript API w wersji 2 a interfejsem Maps JavaScript API w wersji 3. Najnowsza wersja interfejsu Maps JavaScript API została napisana od podstaw z uwzględnieniem nowoczesnych technik programowania w języku JavaScript, częstszego korzystania z bibliotek i uproszczonego interfejsu API. Do interfejsu API dodano wiele nowych funkcji, a kilka znanych funkcji zostało zmienionych lub nawet usuniętych. W tej sekcji opisaliśmy najważniejsze różnice między tymi 2 wersjami.

Niektóre zmiany w interfejsie API w wersji 3 to:

  • usprawniona podstawowa biblioteka; Wiele funkcji dodatkowych zostało przeniesionych do bibliotek, co pozwoliło skrócić czas wczytywania i analizowania interfejsu Core API, dzięki czemu mapa wczytuje się szybko na dowolnym urządzeniu.
  • Zwiększona wydajność kilku funkcji, takich jak renderowanie wielokątów i umieszczenie znaczników.
  • Nowe podejście do limitów użycia po stronie klienta, aby lepiej dostosować się do współdzielonych adresów używanych przez serwery proxy na urządzeniach mobilnych i firmowe zapory sieciowe.
  • Dodano obsługę kilku nowoczesnych przeglądarek i przeglądarek mobilnych. Obsługa Internet Explorera 6 została usunięta.
  • Usunięto wiele klas pomocniczych o ogólnym zastosowaniu ( GLog lub GDownloadUrl). Obecnie istnieje wiele doskonałych bibliotek JavaScript, które zapewniają podobne funkcje, np. Closure czy jQuery.
  • Implementacja Street View w HTML5, która będzie wczytywać się na dowolnym urządzeniu mobilnym.
  • Niestandardowe panoramy Street View ze zdjęciami własnymi, dzięki którym możesz udostępniać panoramy stoków narciarskich, domów na sprzedaż lub innych interesujących miejsc.
  • Dzięki dostosowywaniu map stylizowanych możesz zmieniać wyświetlanie elementów na mapie podstawowej, aby dopasować ją do swojego stylu wizualnego.
  • Obsługa kilku nowych usług, takich jak ElevationService i Distance Matrix.
  • Ulepszony serwis wskazówek drogowych zapewnia alternatywne trasy, optymalizację trasy (przybliżone rozwiązania problemu sprzedawcy podróżującego), wskazówki dotyczące jazdy na rowerze (z warstwą rowerową), wskazówki dotyczące transportu publicznego oraz wskazówki drogowe z możliwością przeciągania.
  • Zaktualizowany format Geokodowania, który zapewnia dokładniejsze informacje o typie niż wartość accuracy z interfejsu Geokodowania API v2.
  • Obsługa wielu okien informacji na jednej mapie

Przechodzenie na nowszą wersję aplikacji

Twój nowy klucz

Interfejs Maps JavaScript API w wersji 3 korzysta z nowego systemu kluczy z wersji 2. W przypadku aplikacji możesz już używać klucza w wersji 3. W takim przypadku nie musisz wprowadzać żadnych zmian. Aby to sprawdzić, sprawdź adres URL, z którego wczytujesz interfejs Maps JavaScript API, pod kątem parametru key. Jeśli wartość klucza zaczyna się od „ABQIAA”, używasz klucza w wersji 2. Jeśli masz klucz w wersji 2, musisz go uaktualnić do wersji 3 w ramach migracji. W efekcie:

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 korzystasz z interfejsów API Map Google dla firmy, możesz używać identyfikatora klienta z parametrem client zamiast parametru key. Identyfikatory klienta są nadal obsługiwane w interfejsie Maps JavaScript API w wersji 3 i nie trzeba przechodzić procesu uaktualniania klucza.

Wczytaj interfejs API

Pierwszą modyfikację, którą musisz wprowadzić w kodzie, jest sposób wczytywania interfejsu API. W wersji 2 interfejs Maps JavaScript API wczytujesz za pomocą żądania do interfejsu 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, podając swój nowy klucz wersji 3. Klienci korzystający z interfejsów API Map Google for Work powinni używać parametru client.
  4. (dotyczy tylko subskrypcji Google Maps Platform Premium) Sprawdź, czy parametr client jest podany zgodnie z opisem w  przewodniku dla programistów dotyczącym subskrypcji Google Maps Platform Premium.
  5. Aby zażądać najnowszej wersji, usuń parametr v lub zmień jego wartość zgodnie ze schematem wersji 3.
  6. (Opcjonalnie) zastąp parametr hl parametrem language i zachowaj jego wartość.
  7. (Opcjonalnie) Dodaj parametr libraries, aby wczytać opcjonalne biblioteki.

W najprostszym przypadku bootstrap v3 będzie zawierać tylko parametr klucza interfejsu API:

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

W przykładzie poniżej wysyłamy żądanie do najnowszej wersji interfejsu Maps JavaScript API 2 w języku niemieckim:

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

Poniżej znajdziesz przykład żądania o takim samym znaczeniu w wersji 3.

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

Przestrzeń nazw google.maps

Prawdopodobnie najbardziej zauważalną zmianą w 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ć kolizje nazw. W wersji 3 wszystkie obiekty znajdują się w przestrzeni nazw google.maps.

Podczas migracji aplikacji na wersję 3.0 musisz zmienić kod, aby korzystać z nowej przestrzeni nazw. Wyszukiwanie „G” i zastępowanie tego fragmentu ciągiem znaków „google.maps” nie przyniesie oczekiwanych rezultatów, ale jest to dobra zasada, której warto przestrzegać podczas sprawdzania kodu. Poniżej znajdziesz kilka przykładów klas równoważnych w wersji 2 i 3.

v2 Wersja 3
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 nieaktualnego kodu

Interfejs Maps JavaScript API w wersji 3 zawiera odpowiedniki większości funkcji z wersji 2, ale niektóre klasy nie są już obsługiwane. W ramach migracji należy zastąpić te klasy bibliotekami narzędzi innych firm lub usunąć te odwołania z kodu. Istnieje wiele świetnych bibliotek JavaScript, które zapewniają podobne funkcje, np. Closure czy jQuery.

Te klasy nie mają odpowiedników 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ównaj kod

Oto porównanie 2 aplikacji napisanych za pomocą interfejsów API w wersji 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ć, te 2 aplikacje różni się od siebie w kilku aspektach. Najważniejsze zmiany:

  • Zmienił się adres, z którego wczytywane jest interfejs API.
  • Metody GBrowserIsCompatible() i GUnload() nie są już wymagane w wersji 3 i zostały usunięte z interfejsu API.
  • Obiekt GMap2 zostaje zastąpiony przez obiekt google.maps.Map, który staje się centralnym obiektem w interfejsie API.
  • Właściwości są teraz ładowane za pomocą klas opcji. W tym przykładzie użyliśmy 3 właściwości (center, zoom i mapTypeId), które są wymagane do załadowania mapy, za pomocą obiektu MapOptions.
  • W wersji 3 domyślny interfejs jest domyślnie włączony. Możesz to wyłączyć, ustawiając właściwość disableDefaultUI na wartość true w obiekcie MapOptions.

Podsumowanie

W tym momencie powinieneś/powinnaś już znać najważniejsze punkty migracji z wersji 2 na wersję 3 interfejsu Maps JavaScript API. Możesz potrzebować więcej informacji, ale wszystko zależy od Twojego zgłoszenia. W następnych sekcjach znajdziesz instrukcje migracji w przypadku konkretnych sytuacji, z którymi możesz się spotkać. Dodatkowo udostępniamy kilka materiałów, które mogą Ci się przydać podczas procesu uaktualniania.

  • Najwięcej informacji o interfejsie API i jego działaniu znajdziesz w dokumentacji dla deweloperów interfejsu Maps JavaScript API w wersji 3.
  • Referencje interfejsu Maps JavaScript API w wersji 3 pomogą Ci dowiedzieć się więcej o nowych klasach i metodach w tym interfejsie API.
  • Społeczność Stack Overflow to świetne miejsce na zadawanie pytań dotyczących kodu. Na stronie pytania i odpowiedzi dotyczące interfejsu Maps JavaScript API używają tagów „google-maps” lub „google-maps-api-3”.
  • Klienci korzystający z abonamentu premium na Mapy Google powinni zapoznać się z dokumentacją Google Maps Platform w wersji premium.
  • Blog programistów Google Geo to świetne miejsce, w którym można się dowiedzieć o najnowszych zmianach w interfejsie API.

Jeśli masz pytania lub wątpliwości dotyczące tego dokumentu, kliknij link WYŚLIJ OPINIĘ u góry tej strony.

Szczegółowe informacje

W tej sekcji znajdziesz szczegółowe porównanie najpopularniejszych funkcji interfejsu Maps JavaScript API w wersji 2 i 3. Każdy rozdział dokumentacji jest przeznaczony do samodzielnego czytania. Zalecamy, aby nie czytać tego dokumentu w całości. Zamiast tego należy korzystać z tego materiału w celu przeprowadzenia migracji w konkretnym przypadku.

  • Zdarzenia – rejestrowanie i obsługa zdarzeń.
  • Elementy sterujące – umożliwiają manipulowanie elementami sterującymi nawigacją wyświetlanymi na mapie.
  • Nakładki – dodawanie i edytowanie obiektów na mapie.
  • Typy map – płytki, z których składa się mapa podstawowa.
  • Warstwy – dodawanie i edytowanie treści jako grupy, na przykład warstw KML lub ruchu.
  • Usługi – praca z geokodowaniem Google, wskazówkami lub usługami Street View.

Wydarzenia

Model zdarzeń interfejsu Maps JavaScript API w wersji 3 jest podobny do modelu używanego w wersji 2, ale pod maską wiele się zmieniło.

Elementy sterujące

Interfejs Maps JavaScript API wyświetla elementy sterujące interfejsem użytkownika, które umożliwiają użytkownikom interakcję z mapą. Za pomocą interfejsu API możesz dostosować sposób wyświetlania tych elementów.

Nakładki

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

Typy map

Typy map dostępne w wersji 2 i 3 różnią się nieznacznie, ale wszystkie podstawowe typy map są dostępne w obu wersjach interfejsu API. Wersja 2 domyślnie używa standardowych „malowanych” kafelków mapy drogowej. Wersja 3 wymaga jednak podania określonego typu mapy podczas tworzenia obiektu google.maps.Map.

Warstwy

Warstwy to obiekty na mapie, które składają się z co najmniej 1 nakładki. Można je modyfikować jako jedną całość i zazwyczaj odzwierciedlają one zbiory obiektów.

Usługi