Aktualizacja interfejsu API JavaScript Map Google z wersji 2 do 3

Interfejs Maps JavaScript API w wersji 2 nie jest już dostępny od 26 maja 2021 r. W rezultacie mapy witryny w wersji 2 przestaną działać i zwrócą błędy JavaScript. Aby nadal korzystać z map w swojej witrynie, przejdź na interfejs Maps JavaScript API w wersji 3. Ten przewodnik pomoże Ci przejść przez ten proces.

Opis

Każda aplikacja będzie miała nieco inny proces migracji, ale istnieją pewne aspekty typowe dla wszystkich projektów:

  1. Wygeneruj nowy klucz. Interfejs Maps JavaScript API używa teraz Google Cloud Console do zarządzania kluczami. Jeśli nadal używasz klucza v2, zanim rozpoczniesz migrację, zdobądź nowy klucz interfejsu API.
  2. Zaktualizuj pakiet rozruchowy API. Większość aplikacji wczyta ten interfejs API do JavaScriptu w wersji 3 za pomocą tego kodu:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. Zaktualizuj kod. Wymagana liczba zmian będzie zależała od Twojej aplikacji. Typowe zmiany:
    • Zawsze używaj odwołania 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 globalnej przestrzeni nazw. W ramach tego procesu zmieniono nazwę większości obiektów. Na przykład zamiast GMap2 wczytasz wartość google.maps.Map.
    • Usuń wszelkie odwołania do nieaktualnych metod. Usunięto różne metody ogólnego zastosowania, takie jak GDownloadURL i GLog. Zastąp tę funkcję bibliotekami narzędzi innych firm lub usuń te odwołania z kodu.
    • (Opcjonalnie) Dodaj biblioteki do kodu. Wiele funkcji zostało przeniesionych do bibliotek narzędzi, dzięki czemu każda aplikacja będzie musiała wczytać tylko te części interfejsu API, które będą używane.
    • (Opcjonalnie) Skonfiguruj projekt, aby korzystał z rozszerzeń zewnętrznych w wersji 3. Rozszerzenia v3 mogą służyć do weryfikacji kodu za pomocą kompilatora zamknięcia lub do autouzupełniania w IDE. Dowiedz się więcej o kompilacji zaawansowanej i zaawansowanych.
  4. Testuj i powtarzaj. Jeszcze musisz coś zrobić, ale mamy dobrą wiadomość: jesteś na dobrej drodze do przejścia na nową wersję map w wersji 3.

Zmiany w wersji 3 interfejsu Maps JavaScript API

Przed zaplanowaniem migracji poświęć trochę czasu na zrozumienie różnic między interfejsem API JavaScript JavaScript w wersji 2 i interfejsem Maps JavaScript API w wersji 3. Najnowsza wersja interfejsu Maps JavaScript API została stworzona od podstaw z myślą o nowoczesnych technikach programowania, zwiększonym wykorzystaniu bibliotek i uproszczonym interfejsie API. Do interfejsu API dodaliśmy wiele nowych funkcji i zmieniliśmy kilka znanych funkcji. W tej sekcji omawiamy niektóre kluczowe różnice między tymi wersjami.

Oto niektóre zmiany w interfejsie API wersji 3:

  • Prosta biblioteka podstawowa. Wiele dodatkowych funkcji zostało przeniesionych do bibliotek, co skraca czas wczytywania i analizowania podstawowego interfejsu API, co umożliwia szybkie wczytywanie mapy na dowolnym urządzeniu.
  • Zwiększona wydajność kilku funkcji, takich jak renderowanie wielokątów i umieszczanie znaczników.
  • Nowe podejście do limitów wykorzystania po stronie klienta, które lepiej uwzględnia adresy udostępniane przez mobilne serwery proxy i firmowe zapory sieciowe.
  • Dodaliśmy obsługę kilku nowoczesnych przeglądarek i przeglądarek mobilnych. Obsługa przeglądarki Internet Explorer 6 została usunięta.
  • Wiele klas pomocniczych o charakterze ogólnym (GLog lub GDownloadUrl) zostało usuniętych. Obecnie istnieje wiele świetnych bibliotek JavaScript, które zapewniają podobne funkcje, takie jak zamknięcie czy jQuery.
  • implementacja Street View HTML5, która wczytuje się na dowolnym urządzeniu mobilnym;
  • W przypadku niestandardowych widoków Street View możesz dodawać do nich własne zdjęcia, aby udostępniać panoramę stoków narciarskich, domy na sprzedaż lub inne ciekawe miejsca.
  • Dostosowywanie Map stylizowanych, które pozwala zmienić sposób wyświetlania elementów na mapie podstawowej, tak aby pasował do unikalnego stylu wizualnego.
  • Obsługa kilku nowych usług, takich jak ElevationService i Odległość matryca.
  • Ulepszone usługi wyznaczania trasy obejmują trasy alternatywne, optymalizację tras (przybliżone rozwiązania problemu z podróżą sprzedawcy), wskazówki dojazdu rowerem (z warstwą rowerową), wskazówki dojazdu transportem publicznym oraz trasy do przeciągania.
  • Zaktualizowany format geokodowania, który zawiera dokładniejsze informacje o typie niż wartość accuracy w interfejsie Geocoding API v2.
  • Obsługiwanie wielu systemów informacyjnych w ramach jednej mapy

Uaktualnianie aplikacji

Twój nowy klucz

Interfejs Maps JavaScript API w wersji 3 korzysta z nowego systemu kluczy z wersji 2. Być może korzystasz już z klucza w wersji 3. W takim przypadku nie musisz wprowadzać żadnych zmian. Aby to sprawdzić, sprawdź adres URL, z którego wczytano interfejs Maps JavaScript API pod kątem parametru key. Jeśli wartość klucza zaczyna się od 'ABQIAA&#39, używasz klucza w wersji 2. Jeśli masz klucz v2, musisz przejść na klucz v3 w ramach migracji. Dzięki temu:

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

Jeśli używasz interfejsu API Map Google dla Firm, być może używasz identyfikatora klienta z parametrem client zamiast parametru key. Jednak identyfikatory klientów są nadal obsługiwane w interfejsie Maps JavaScript API w wersji 3 i nie trzeba ich uaktualniać.

Wczytywanie interfejsu API

Pierwsza zmiana, jaką musisz wprowadzić w kodzie, obejmuje sposób wczytywania interfejsu API. W wersji 2 wczytujesz interfejs Maps JavaScript API za pomocą żądania skierowanego do http://maps.google.com/maps. Jeśli ładujesz interfejs Maps JavaScript API w wersji 3, musisz wprowadzić te zmiany:

  1. Wczytywanie interfejsu API z //maps.googleapis.com/maps/api/js
  2. Usuń parametr file.
  3. Zaktualizuj parametr key o nowy klucz w wersji 3. Klienci korzystający z Google Maps API for Work powinni używać parametru client.
  4. (Dotyczy tylko abonamentu Premium Google Maps Platform) Parametr client powinien być podany w przewodniku dla programistów pakietu Premium 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, by wczytać opcjonalne biblioteki.

W najprostszym przypadku plik rozruchowy v3 będzie określać tylko parametr klucza interfejsu API:

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

Poniższy przykład przedstawia najnowszą wersję 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 dla wersji 3.

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

Przedstawiamy przestrzeń nazw google.maps

Najbardziej zauważalna zmiana w interfejsie Maps JavaScript API w wersji 3 to wprowadzenie przestrzeni nazw google.maps. Interfejs API w wersji 2 domyślnie umieszcza wszystkie obiekty w globalnej przestrzeni nazw, co może spowodować kolidowanie nazw. W wersji 3 wszystkie obiekty znajdują się w przestrzeni nazw google.maps.

Podczas migracji aplikacji do wersji 3 musisz zmienić kod, aby korzystać z nowej przestrzeni nazw. Niestety wyszukiwanie i zastępowanie ciągu „"google.maps." wygra” – ale jest to dobra zasada, według której warto sprawdzić kod. Poniżej znajdziesz kilka przykładów równoważnych klas 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

W większości funkcji wersji 2 interfejs Maps JavaScript API w wersji 3 działa równolegle. Jednak niektóre klasy nie są już obsługiwane. W ramach migracji musisz zastąpić te klasy bibliotekami narzędzi innych firm lub usunąć te odwołania z kodu. Istnieje wiele świetnych bibliotek JavaScript, które oferują podobne funkcje, takie jak zamknięcie czy jQuery.

Te klasy nie mają równoległego interfejsu API JavaScript JavaScript 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ównywanie kodu

Porównaj 2 proste aplikacje, które zostały napisane za pomocą interfejsów API v2 i v3.

<!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>
    

Oto kilka różnic między tymi aplikacjami. Najważniejsze zmiany:

  • Adres, z którego został wczytany interfejs API, uległ zmianie.
  • Metody GBrowserIsCompatible() i GUnload() nie są już wymagane w wersji 3 i zostały usunięte z interfejsu API.
  • Obiekt GMap2 został zastąpiony przez google.maps.Map głównym obiektem w interfejsie API.
  • Właściwości są teraz wczytywane za pomocą klas opcji. W przykładzie powyżej ustawiamy 3 właściwości wymagane do załadowania mapy: center, zoom i mapTypeId za pomocą wbudowanego obiektu MapOptions.
  • W wersji 3 domyślny interfejs jest domyślnie włączony. Aby wyłączyć tę funkcję, ustaw właściwość disableDefaultUI w obiekcie MapOptions na wartość „true”.

Podsumowanie

W tym momencie dowiedzieliśmy się więcej o kluczowych kwestiach związanych z migracją z interfejsu API JavaScript Map Google do wersji 2. Możesz potrzebować więcej informacji, ale zależy to od konkretnego zgłoszenia. W kolejnych sekcjach znajdziesz instrukcje migracji, które mogą się pojawić w poszczególnych przypadkach. Warto też skorzystać z kilku zasobów, które mogą Ci się przydać podczas uaktualniania.

  • Interfejs Maps JavaScript API w wersji 3 (Dokumentacja dla deweloperów) to miejsce, w którym znajdziesz więcej informacji o interfejsie API i jego działaniu.
  • Więcej informacji o nowych klasach i metodach w interfejsie API wersji 3 znajdziesz w dokumentacji Maps JavaScript API w wersji 3.
  • Społeczność Stack Overflow to idealne miejsce do zadawania pytań dotyczących kodu. Na stronie pytania i odpowiedzi dotyczące interfejsu API JavaScript JavaScript znajdziesz w tagach 'google-maps' i #39;google-maps-api-3'.
  • Klienci korzystający z abonamentu premium na Google Maps Platform powinni zapoznać się z dokumentacją abonamentu Premium Google Maps Platform.
  • Blog Google Geo Developers to świetny sposób, aby poznać najnowsze zmiany związane z interfejsem API.

Jeśli masz pytania lub problemy dotyczące tego artykułu, skorzystaj z linku PRZEŚ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żda sekcja pliku referencyjnego jest przeznaczona do odczytu indywidualnego. Zalecamy, aby nie czytać tego pliku referencyjnego w całości. Możesz wykorzystać ten materiał, aby przeprowadzić migrację indywidualnie.

  • Zdarzenia – rejestrowanie zdarzeń i ich obsługa.
  • Elementy sterujące – manipulowanie elementami nawigacyjnymi, które pojawiają się na mapie.
  • Nakładki – dodawanie i edytowanie obiektów na mapie.
  • Typy map – kafelki składające się na mapę podstawową.
  • Warstwy – dodawanie i edytowanie treści jako grupy, takich jak KML lub warstwy Ruch.
  • Usługi – obsługa geokodowania, tras dojazdu lub usług Street View w Google.

Zdarzenia

Model zdarzenia w interfejsie Maps JavaScript API w wersji 3 jest podobny do modelu v2, ale uległ on znacznym zmianom.

Opcje

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

Nakładki

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

Typy map

Typy map dostępne w wersjach 2 i 3 są różne, ale wszystkie podstawowe typy map są dostępne w obu wersjach interfejsu API. Domyślnie wersja 2 korzysta z standardowych kafelków &map drogowych. Wersja 3 wymaga jednak określonego typu mapy podczas tworzenia obiektu google.maps.Map.

Warstwy

Warstwy to obiekty na mapie składające się z co najmniej jednej nakładki. Możesz zmanipulować je jako pojedynczą jednostkę i ogólnie odzwierciedlają kolekcje obiektów.

Usługi