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ć umieszczania elementów sterujących, aby dodać etykietę do mapy.

Poniżej znajduje się mapa, którą utworzysz w ramach tego samouczka. 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 tego 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 w przykładzie mamy:

  • zadeklarować aplikację jako HTML5 za pomocą deklaracji !DOCTYPE html;
  • Interfejs Maps JavaScript API został wczytany za pomocą narzędzia do wczytywania.
  • 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. Element DOCTYPE został też zaprojektowany tak, aby działać w sposób niezakłócony. Przeglądarki, które go nie rozpoznają, będą go ignorować i wyświetlać treści w „trybie osobliwoś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 nadrzędnych elementów blokowych, a 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

Narzędzie do wczytywania 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ć do tego 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ą funkcji 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 init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // 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).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // 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).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

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ć sytuację wyścigu, 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.

Kompletny przykładowy kod

Pełny przykładowy kod znajdziesz tutaj:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // 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).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // 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).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

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;
}

HTML

<html>
    <head>
        <title>Add a Map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </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>

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. Wybierz współrzędne geograficzne z menu.

  • 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.