Dodawanie mapy Google ze znacznikiem za pomocą JavaScriptu

Wprowadzenie

Z tego samouczka dowiesz się, jak dodać do strony internetowej mapę Google ze znacznikiem, używając HTML, CSS i JavaScriptu. Pokazuje też, jak ustawić opcje mapy i jak użyć gniazda elementu sterującego, aby dodać etykietę do mapy.

Poniżej znajduje się mapa, którą utworzysz, korzystając z tego samouczka. Znacznik znajduje się przy Uluru (znanej też jako Ayers Rock) w Parku Narodowym Uluru-Kata Tjuta.

Pierwsze kroki

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

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

Potrzebujesz przeglądarki. Wybierz popularną przeglądarkę, np. Google Chrome (zalecana), Firefox, Safari lub Edge, odpowiednią dla Twojej platformy, z listy obsługiwanych przeglądarek.

Krok 1. Uzyskaj klucz interfejsu API

W tej sekcji wyjaśniamy, jak uwierzytelnić aplikację w 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 usługi.

4. Na stronie Dane logowania pobierz klucz interfejsu API (i ustaw ograniczenia klucza interfejsu API). Uwaga: jeśli masz już klucz interfejsu API bez ograniczeń lub klucz z ograniczeniami 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 Użycie i płatności.

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 podstawowego HTML strony internetowej:

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

• Zadeklaruj aplikację jako HTML5 za pomocą deklaracji !DOCTYPE html.
• Wczytano interfejs Maps JavaScript API za pomocą narzędzia do wczytywania.
• Utworzono element gmp-map, który będzie zawierał mapę.

Zadeklaruj aplikację jako HTML5

Zalecamy zadeklarowanie wartości true dla parametru DOCTYPE w aplikacji internetowej. W podanych tu przykładach zadeklarowaliśmy nasze aplikacje jako HTML5, używając elementu HTML5 DOCTYPE, jak pokazano poniżej:

<!DOCTYPE html>

Większość obecnych przeglądarek renderuje treści zadeklarowane za pomocą tego elementu DOCTYPE w „trybie standardowym”, co oznacza, że aplikacja powinna być bardziej zgodna z różnymi przeglądarkami. Deklaracja DOCTYPE jest też zaprojektowana tak, aby nie powodować błędów. Przeglądarki, które jej nie rozpoznają, zignorują ją i wyświetlą zawartość w „trybie osobliwości”.

Pamiętaj, że niektóre kody CSS, które działają w trybie osobliwości, nie są prawidłowe w trybie standardowym. Wszystkie rozmiary podane w procentach muszą być dziedziczone z nadrzędnych elementów blokowych. Jeśli któryś z tych elementów nadrzędnych nie ma określonego rozmiaru, przyjmuje się, że ma on rozmiar 0 x 0 pikseli. Z tego powodu dodajemy tę deklarację style:

<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 sekcji Krok 3. Uzyskaj klucz interfejsu API.

Na tym etapie samouczka pojawi się puste okno, w którym będzie widoczny tylko niesformatowany tekst etykiety. 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 odwołanie do tego elementu w obiektowym modelu dokumentu (DOM) przeglądarki. Możesz też użyć elementu div (więcej informacji), ale zalecamy użycie 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. We fragmencie kodu powyżej właściwość center informuje interfejs API, gdzie wyśrodkować mapę, 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ć widok Ziemi w wyższej rozdzielczości.

Poziomy powiększenia

Udostępnienie mapy całej Ziemi jako pojedynczego 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 „fragmenty” i „poziomy powiększenia”. Przy niskich poziomach powiększenia niewielki zestaw kafelków mapy obejmuje duży obszar. Przy wyższych poziomach powiększenia kafelki mają wyższą rozdzielczość i obejmują mniejszy obszar. Poniższa lista zawiera przybliżony poziom szczegółowości, którego możesz się spodziewać na każdym poziomie 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 arkusz CSS, który określa 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. Aby mapa była widoczna, ustaw szerokość i wysokość na wartość większą niż 0 pikseli. W tym przypadku wysokość elementu gmp-map jest ustawiona na 400 pikseli, a szerokość na 100%, aby wyświetlał się na całej szerokości strony internetowej. Zalecamy, aby zawsze wyraźnie określać style wysokości i szerokości.

Uwaga: w przypadku map rastrowych maksymalny wymiar to 6144 × 6144 pikseli.

Rozmieszczanie elementów sterujących

Możesz użyć gniazd elementów sterujących, aby dodać do mapy elementy sterujące formularza HTML. Miejsce to wstępnie zdefiniowana pozycja na mapie. Użyj atrybutu slot, aby ustawić wymaganą 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 jak napisać własny kod JavaScript, który używa tego interfejsu do dodania 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();
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

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();
index.js

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

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

Pobieranie obiektu mapy i ustawianie opcji

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 czasie inicjowania zostaną wysłane inne żądania (np. geolokalizacji lub informacji o miejscu). Aby mieć pewność, że kod zostanie uruchomiony dopiero po pełnym załadowaniu mapy, użyj modułu obsługi zdarzeń addListenerOnce idle w funkcji inicjowania, 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. Moduł obsługi jest wywoływany tylko raz w cyklu życia aplikacji.

Uwaga dotycząca optymalizacji wydajności wewnętrznej:

Aby przyspieszyć wczytywanie strony, interfejs Maps JavaScript API może wewnętrznie opóźniać wczytywanie treści interaktywnych, dopóki element lub kontener nie zbliży się do widocznego obszaru. Te wewnętrzne optymalizacje mogą ulec zmianie w dowolnym momencie bez powiadomienia. Są one przeznaczone do zwiększania wydajności i nie powinny być używane jako mechanizm zarządzania płatnościami. Aby mieć pewność, że opłaty nie będą naliczane, dopóki element nie będzie widoczny, odłóż jego utworzenie w kodzie 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();
index.ts

Uwaga: przeczytaj przewodnik dotyczący korzystania z TypeScript i Map Google.

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();
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>
        <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>
index.html

Więcej informacji o znacznikach:

• Ułatwianie dostępu do znacznika
• Znaczniki z ikonami graficznymi
• Animacje znaczników

Wskazówki i rozwiązywanie problemów

• Dowiedz się więcej o uzyskiwaniu współrzędnych szerokości i długości geograficznej lub konwertowaniu adresu na 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 stylów i rysowania na mapie.
• Użyj konsoli narzędzi dla programistów w przeglądarce, aby przetestować i uruchomić kod, odczytać raporty o błędach i rozwiązać 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 lokalizacji w Mapach Google, wykonaj podane niżej czynności.

  1. Otwórz Mapy Google w przeglądarce.
  2. Kliknij prawym przyciskiem myszy dokładną lokalizację na mapie, której współrzędne chcesz uzyskać.
  3. Wybierz z menu współrzędne szerokości i długości geograficznej.

• Możesz przekonwertować adres na współrzędne geograficzne, korzystając z usługi geokodowania. Przewodniki dla programistów zawierają szczegółowe informacje o rozpoczęciu korzystania z usługi geokodowania.