Dodawanie mapy Google ze znacznikiem za pomocą JavaScriptu

Wprowadzenie

W tym samouczku pokazujemy, jak dodać do strony internetowej mapę Google ze znacznikiem za pomocą HTML, CSS i JavaScriptu. Pokazuje też, jak ustawić opcje mapy i jak używać rozmieszczania elementów sterujących, aby dodać etykietę do mapy.

Poniżej znajduje się mapa, którą utworzysz w tym samouczku. Znacznik znajduje się w Uluru (znanym też jako Ayers Rock) w Parku Narodowym Uluru-Kata Tjuta.

Pierwsze kroki

Aby utworzyć mapę Google ze znacznikiem na stronie internetowej, wykonaj 3 czynności:

  1. Pobieranie klucza interfejsu API
  2. Tworzenie strony HTML
  3. Dodawanie mapy ze znacznikiem

Potrzebujesz przeglądarki. Wybierz znaną przeglądarkę, np. Google Chrome (zalecana), Firefox, Safari lub Edge, w zależności od platformy z listy obsługiwanych przeglądarek.

Krok 1. Uzyskaj klucz interfejsu API

W tej sekcji dowiesz się, jak uwierzytelnić aplikację w interfejsie Maps JavaScript API za pomocą własnego klucza interfejsu API.

Aby uzyskać klucz interfejsu API:

  1. Otwórz konsolę Google Cloud.

  2. Utwórz lub wybierz projekt.

  3. Kliknij Dalej, aby włączyć interfejs API i powiązane z nim usługi.

  4. Na stronie Dane logowania uzyskaj klucz interfejsu API (i ustaw ograniczenia klucza interfejsu API). Uwaga: jeśli masz już klucz interfejsu API bez ograniczeń lub klucz z ograniczeniami dotyczącymi przeglądarki, możesz go użyć.

  5. Aby zapobiec kradzieży limitu i zabezpieczyć klucz interfejsu API, zapoznaj się z artykułem Korzystanie z kluczy interfejsu API.

  6. Włącz płatności. Więcej informacji znajdziesz w artykule Wykorzystanie i rozliczenia.

  7. Gdy uzyskasz klucz interfejsu API, dodaj go do poniższego fragmentu kodu, klikając „YOUR_API_KEY”. Skopiuj i wklej tag skryptu programu rozruchowego, aby użyć go na własnej stronie internetowej.

    <script>   (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({     key: "YOUR_API_KEY",     v: "weekly",     // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).     // Add other bootstrap parameters as needed, using camel case.   }); </script>

Krok 2. Utwórz stronę HTML

Oto kod podstawowej strony internetowej HTML:

<!DOCTYPE html> <!--  @license  Copyright 2025 Google LLC. All Rights Reserved.  SPDX-License-Identifier: Apache-2.0 -->  <html>   <head>     <title>Add a Map</title>      <link rel="stylesheet" type="text/css" href="./style.css" />     <script type="module" src="./index.js"></script>     <!-- prettier-ignore -->     <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})         ({key: "YOUR_API_KEY", v: "weekly"});</script>   </head>   <body>      <!-- The map, centered at Uluru, Australia. -->     <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">     </gmp-map>    </body> </html>

To bardzo prosta strona HTML, która używa elementu gmp-map do wyświetlania mapy. Mapa będzie pusta, ponieważ nie dodaliśmy jeszcze żadnego kodu JavaScript.

Zrozumienie kodu

Na tym etapie przykładu mamy:

  • zadeklarować aplikację jako HTML5 za pomocą deklaracji !DOCTYPE html.
  • Interfejs Maps JavaScript API został wczytany za pomocą programu wczytującego bootstrap.
  • Utworzono element gmp-map do przechowywania mapy.

Deklarowanie aplikacji jako HTML5

Zalecamy zadeklarowanie wartości DOCTYPE w aplikacji internetowej. W przykładach poniżej zadeklarowaliśmy nasze aplikacje jako HTML5 za pomocą elementu HTML5 DOCTYPE:

<!DOCTYPE html>

Większość obecnych przeglądarek renderuje treści zadeklarowane za pomocą tego tagu DOCTYPE w „trybie standardów”, co oznacza, że Twoja aplikacja powinna być bardziej zgodna z różnymi przeglądarkami. DOCTYPE jest też zaprojektowany tak, aby działać w sposób niezakłócony. Przeglądarki, które go nie obsługują, będą go ignorować i wyświetlać treści w „trybie zgodności”.

Pamiętaj, że niektóre style CSS działające w trybie zgodności nie są prawidłowe w trybie standardów. Wszystkie rozmiary oparte na procentach muszą dziedziczyć rozmiar z elementów blokowych nadrzędnych. Jeśli którykolwiek z tych elementów nadrzędnych nie określa rozmiaru, przyjmuje się, że ma on rozmiar 0 x 0 pikseli. Z tego powodu dodajemy to style oświadczenie:

<style>   gmp-map {     height: 100%;   }   html, body {     height: 100%;     margin: 0;     padding: 0;   } </style>

Wczytywanie interfejsu Maps JavaScript API

Program rozruchowy przygotowuje interfejs Maps JavaScript API do wczytania (żadne biblioteki nie są wczytywane, dopóki nie zostanie wywołana funkcja importLibrary()).

<script>   (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({     key: "YOUR_API_KEY",     v: "weekly",     // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).     // Add other bootstrap parameters as needed, using camel case.   }); </script>

Instrukcje uzyskiwania własnego klucza interfejsu API znajdziesz w kroku 3: Uzyskaj klucz interfejsu API.

Na tym etapie samouczka pojawi się puste okno, w którym będzie widoczny tylko tekst etykiety bez formatowania. Dzieje się tak, ponieważ nie dodaliśmy jeszcze żadnego kodu JavaScript.

Tworzenie elementu gmp-map

Aby mapa wyświetlała się na stronie internetowej, musimy zarezerwować dla niej miejsce. Zwykle robimy to, tworząc element gmp-map i uzyskując do niego odniesienie w modelu DOM przeglądarki. Możesz też użyć elementu div (więcej informacji), ale zalecamy używanie elementu gmp-map.

Poniższy kod definiuje element gmp-map i ustawia parametry center, zoom i map-id.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID"> </gmp-map>

Opcje center i zoom są zawsze wymagane. W powyższym kodzie właściwość center określa, gdzie ma być wyśrodkowana mapa, a właściwość zoom określa poziom powiększenia mapy. Powiększenie: 0 to najmniejsze powiększenie, które wyświetla całą Ziemię. Ustaw wyższą wartość powiększenia, aby powiększyć Ziemię w wyższej rozdzielczości.

Poziomy powiększenia

Oferowanie mapy całej Ziemi jako jednego obrazu wymagałoby ogromnej mapy lub małej mapy o bardzo niskiej rozdzielczości. W rezultacie obrazy map w Mapach Google i interfejsie Maps JavaScript API są podzielone na „kafelki” i „poziomy powiększenia”. Przy niskim poziomie powiększenia niewielki zestaw kafelków mapy obejmuje duży obszar, a przy wyższym poziomie powiększenia kafelki mają wyższą rozdzielczość i obejmują mniejszy obszar. Poniższa lista pokazuje przybliżony poziom szczegółowości na poszczególnych poziomach powiększenia:

  • 1: Świat
  • 5. Ląd lub kontynent
  • 10. Miasto
  • 15. Ulice
  • 20. Budynki

Poniższe 3 obrazy przedstawiają tę samą lokalizację w Tokio na poziomach powiększenia 0, 7 i 18.

Poniższy kod opisuje CSS, który ustawia rozmiar elementu gmp-map.

/* Set the size of the gmp-map element that contains the map */ gmp-map {     height: 400px; /* The height is 400 pixels */     width: 100%; /* The width is the width of the web page */ }

W powyższym kodzie element style określa rozmiar elementu gmp-map. Ustaw szerokość i wysokość na wartość większą niż 0 pikseli, aby mapa była widoczna. W tym przypadku element gmp-map ma wysokość 400 pikseli i szerokość 100%, dzięki czemu wyświetla się na całej szerokości strony. Zalecamy zawsze jawne ustawianie stylów wysokości i szerokości.

Kontrolowanie umieszczania reklam

Za pomocą umieszczania elementów sterujących możesz dodawać do mapy elementy sterujące formularza HTML. Miejsce to predefiniowana pozycja na mapie. Użyj atrybutu slot, aby ustawić potrzebną pozycję elementu, i zagnieżdżaj elementy w elemencie gmp-map. Poniższy fragment kodu pokazuje, jak dodać etykietę HTML w lewym górnym rogu mapy.

<!-- The map, centered at Uluru, Australia. --> <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">   <div id="controls" slot="control-inline-start-block-start">     <h3>My Google Maps Demo</h3>   </div> </gmp-map>

Krok 3. Dodaj kod JavaScript

W tej sekcji dowiesz się, jak wczytać interfejs Maps JavaScript API na stronę internetową i napisać własny kod JavaScript, który używa tego interfejsu do dodawania mapy ze znacznikiem.

TypeScript

async function initMap(): Promise<void> {   //  Request the needed libraries.   const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([     google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,     google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,   ]);   // Get the gmp-map element.   const mapElement = document.querySelector(     "gmp-map"   ) as google.maps.MapElement;    // Get the inner map.   const innerMap = mapElement.innerMap;    // Set map options.   innerMap.setOptions({     mapTypeControl: false,   });    // Add a marker positioned at the map center (Uluru).   const marker = new AdvancedMarkerElement({     map: innerMap,     position: mapElement.center,     title: "Uluru/Ayers Rock",   }); } initMap();
index.ts

JavaScript

async function initMap() {     //  Request the needed libraries.     const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([         google.maps.importLibrary("maps"),         google.maps.importLibrary("marker"),     ]);     // Get the gmp-map element.     const mapElement = document.querySelector("gmp-map");     // Get the inner map.     const innerMap = mapElement.innerMap;     // Set map options.     innerMap.setOptions({         mapTypeControl: false,     });     // Add a marker positioned at the map center (Uluru).     const marker = new AdvancedMarkerElement({         map: innerMap,         position: mapElement.center,         title: "Uluru/Ayers Rock",     }); } initMap();
index.js

Gdy wywoływana jest funkcja initMap(), powyższy kod wykonuje te czynności:

  • Wczytuje biblioteki maps i marker.
  • Pobiera element mapy z interfejsu DOM.
  • Ustawia dodatkowe opcje mapy na mapie wewnętrznej.
  • Dodaje znacznik do mapy.

Pobieranie obiektu mapy i ustawianie opcji

Symbol innerMap reprezentuje instancję klasy Map. Aby ustawić opcje mapy, pobierz instancję innerMap z elementu mapy i wywołaj setOptions. Poniższy fragment kodu pokazuje, jak pobrać instancję innerMap z DOM, a następnie wywołać setOptions:

// Get the gmp-map element. const mapElement = document.querySelector(   "gmp-map" ) as google.maps.MapElement;  // Get the inner map. const innerMap = mapElement.innerMap;  // Set map options. innerMap.setOptions({   mapTypeControl: false, });

Poczekaj, aż mapa się wczyta.

Gdy używasz elementu gmp-map, mapa wczytuje się asynchronicznie. Może to spowodować wyścig, jeśli w momencie inicjowania zostaną wysłane inne żądania (np. żądanie geolokalizacji lub szczegółów miejsca). Aby mieć pewność, że kod zostanie uruchomiony dopiero po pełnym załadowaniu mapy, użyj w funkcji inicjującej addListenerOnceprocedury obsługi zdarzenia idle, jak pokazano poniżej:

// Do things once the map has loaded. google.maps.event.addListenerOnce(innerMap, 'idle', () => {     // Run this code only after the map has loaded.     console.log("The map is now ready!"); });

Dzięki temu kod zostanie uruchomiony dopiero po wczytaniu mapy, a procedura obsługi zostanie wywołana tylko raz w trakcie cyklu życia aplikacji.

Pełny przykładowy kod

Pełny przykładowy kod znajdziesz tutaj:

TypeScript

async function initMap(): Promise<void> {   //  Request the needed libraries.   const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([     google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,     google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,   ]);   // Get the gmp-map element.   const mapElement = document.querySelector(     "gmp-map"   ) as google.maps.MapElement;    // Get the inner map.   const innerMap = mapElement.innerMap;    // Set map options.   innerMap.setOptions({     mapTypeControl: false,   });    // Add a marker positioned at the map center (Uluru).   const marker = new AdvancedMarkerElement({     map: innerMap,     position: mapElement.center,     title: "Uluru/Ayers Rock",   }); } initMap();
index.ts

JavaScript

async function initMap() {     //  Request the needed libraries.     const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([         google.maps.importLibrary("maps"),         google.maps.importLibrary("marker"),     ]);     // Get the gmp-map element.     const mapElement = document.querySelector("gmp-map");     // Get the inner map.     const innerMap = mapElement.innerMap;     // Set map options.     innerMap.setOptions({         mapTypeControl: false,     });     // Add a marker positioned at the map center (Uluru).     const marker = new AdvancedMarkerElement({         map: innerMap,         position: mapElement.center,         title: "Uluru/Ayers Rock",     }); } initMap();
index.js

CSS

/*  * Always set the map height explicitly to define the size of the div element  * that contains the map.  */ gmp-map {   height: 100%; }  /*    * Optional: Makes the sample page fill the window.    */ html, body {   height: 100%;   margin: 0;   padding: 0; }
style.css

HTML

<html>   <head>     <title>Add a Map</title>      <link rel="stylesheet" type="text/css" href="./style.css" />     <script type="module" src="./index.js"></script>     <!-- prettier-ignore -->     <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})         ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>   </head>   <body>     <!-- The map, centered at Uluru, Australia. -->     <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">       <div id="controls" slot="control-inline-start-block-start">         <h3>My Google Maps Demo</h3>       </div>     </gmp-map>   </body> </html>
index.html

Wypróbuj

Więcej informacji o markerach:

Wskazówki i rozwiązywanie problemów

  • Dowiedz się więcej o uzyskiwaniu współrzędnych geograficznych lub przekształcaniu adresu we współrzędne geograficzne.
  • Możesz dostosować mapę, zmieniając opcje takie jak styl i właściwości. Więcej informacji o dostosowywaniu map znajdziesz w przewodnikach dotyczących stylizowania i rysowania na mapie.
  • Użyj konsoli narzędzi deweloperskich w przeglądarce, aby testować i uruchamiać kod, odczytywać raporty o błędach i rozwiązywać problemy z kodem.
  • Aby otworzyć konsolę w Chrome, użyj tych skrótów klawiszowych:
    Command+Option+J (na Macu) lub Ctrl+Shift+J (w systemie Windows).

  •  Aby uzyskać współrzędne geograficzne (szerokość i długość) lokalizacji w Mapach Google, wykonaj te czynności:

    1. Otwórz Mapy Google w przeglądarce.
    2. Kliknij prawym przyciskiem myszy dokładną lokalizację na mapie, dla której chcesz uzyskać współrzędne.
    3. W wyświetlonym menu kontekstowym wybierz Co tu jest?. U dołu ekranu wyświetli się karta. W ostatnim wierszu karty znajdź współrzędne szerokości i długości geograficznej.

  • Za pomocą usługi geokodowania możesz przekonwertować adres na współrzędne geograficzne. W przewodnikach dla deweloperów znajdziesz szczegółowe informacje o rozpoczynaniu korzystania z usługi Geocoding.