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 (znanej 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>

Jest to bardzo prosta strona HTML, która używa elementu gmp-map do wyświetlania mapy na stronie. 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 odwołanie 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.