Einführung
In diesem Tutorial erfahren Sie, wie Sie mithilfe von HTML, CSS und JavaScript eine Google-Karte mit einer Markierung auf einer Webseite einfügen. Außerdem wird gezeigt, wie Sie Kartenoptionen festlegen und wie Sie mit der Funktion „Control Slotting“ ein Label auf der Karte hinzufügen.
Unten sehen Sie die Karte, die Sie mit dieser Anleitung erstellen. Die Markierung befindet sich am Uluru (auch als Ayers Rock bezeichnet) im Uluṟu-Kata-Tjuṯa-Nationalpark.
Überblick und Webbrowser
Um eine Google-Karte mit einer Markierung auf Ihrer Webseite einzufügen, sind drei Schritte erforderlich:
Sie benötigen einen Webbrowser. Wählen Sie aus der Liste der unterstützten Browser einen gängigen Browser wie Google Chrome (empfohlen), Firefox, Safari oder Edge für Ihre Plattform aus.
Schritt 1: API-Schlüssel anfordern
In diesem Abschnitt wird erläutert, wie Sie Ihre Anwendung mit Ihrem eigenen API-Schlüssel bei der Maps JavaScript API authentifizieren können.
So fordern Sie einen API-Schlüssel an:
Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes Projekt aus.
Klicken Sie auf Weiter, um die API und die zugehörigen Dienste zu aktivieren.
Fordern Sie auf der Seite Anmeldedaten einen API-Schlüssel an und legen Sie die Einschränkungen für den API-Schlüssel fest. Wenn Sie bereits einen API-Schlüssel ohne Einschränkungen oder einen Schlüssel mit Browsereinschränkungen haben, können Sie auch diesen verwenden.
Informationen zum Verhindern von Kontingentdiebstahl und zum Sichern Ihres API-Schlüssels finden Sie unter Mit API-Schlüsseln authentifizieren.
Aktivieren Sie die Abrechnung. Weitere Informationen finden Sie unter Nutzung und Abrechnung.
Nachdem Sie einen API-Schlüssel erhalten haben, klicken Sie auf „YOUR_API_KEY“, um ihn in das folgende Snippet einzufügen. Kopieren Sie das Bootloader-Script-Tag, das Sie auf Ihrer eigenen Webseite verwenden möchten, und fügen Sie es ein.
<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>
Schritt 2: HTML-Seite erstellen
Hier ist der Code für eine einfache HTML-Webseite:
<!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>Dies ist eine sehr einfache HTML-Seite, auf der mit einem gmp-map-Element eine Karte angezeigt wird. Die Karte ist leer, da wir noch keinen JavaScript-Code hinzugefügt haben.
Code verstehen
In dieser Phase des Beispiels haben wir Folgendes:
- Die Anwendung wurde mit der
!DOCTYPE html-Deklaration als HTML5 deklariert. - Die Maps JavaScript API wurde mit dem Bootstrap-Ladeprogramm geladen.
- Es wurde ein
gmp-map-Element erstellt, das die Karte enthält.
Anwendung als HTML5 deklarieren
Wir empfehlen, dass Sie ein echtes DOCTYPE-Element innerhalb Ihrer Webanwendung deklarieren.
In den Beispielen hier haben wir die Anwendungen über den HTML5-DOCTYPE als HTML5 deklariert (siehe unten):
<!DOCTYPE html>
Die meisten aktuellen Browser rendern Inhalte, die mit diesem DOCTYPE deklariert sind, im „Standardmodus“. Ihre Anwendung sollte daher browserübergreifend kompatibler sein. Der DOCTYPE ist für das Prinzip der „Graceful Degradation“ konzipiert. Browser, die ihn nicht verstehen, ignorieren ihn und verwenden den Quirks-Modus, um den Inhalt anzuzeigen.
Bestimmte CSS, die im Quirks-Modus funktionieren, sind im Standardmodus nicht gültig. Insbesondere müssen alle prozentualen Größen von übergeordneten Blockelementen übernommen werden. Wenn für einen der Ancestors keine Größe angegeben ist, wird davon ausgegangen, dass er eine Größe von 0 × 0 Pixeln hat. Daher wird die folgende style-Deklaration eingefügt:
<style>
gmp-map {
height: 100%;
}
html, body {
height: 100%;
margin: 0;
padding: 0;
}
</style>Maps JavaScript API laden
Das Bootstrap-Ladeprogramm bereitet die Maps JavaScript API für das Laden vor. Es werden keine Bibliotheken geladen, bis importLibrary() aufgerufen wird.
<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>
Eine Anleitung zum Abrufen eines eigenen API-Schlüssels finden Sie unter Schritt 3: API-Schlüssel anfordern.
In dieser Phase des Tutorials wird ein leeres Fenster mit dem unformatierten Labeltext angezeigt. Das liegt daran, dass wir noch keinen JavaScript-Code hinzugefügt haben.
gmp-map-Element erstellen
Damit die Karte auf einer Webseite angezeigt werden kann, muss ein Platz für sie reserviert werden. Dazu wird normalerweise ein gmp-map-Element erstellt, auf das im DOM (Document Object Model) des Browsers verwiesen wird. Sie können dazu auch ein div-Element verwenden (weitere Informationen), es wird jedoch empfohlen, das gmp-map-Element zu verwenden.
Im folgenden Code wird das gmp-map-Element definiert und die Parameter center, zoom und map-id werden festgelegt.
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID"> </gmp-map>
Die Optionen center und zoom sind immer erforderlich. Im Code oben wird mit der Eigenschaft center der API mitgeteilt, wo sich der Mittelpunkt der Karte befinden soll, und mit der Eigenschaft zoom wird die Zoomstufe der Karte festgelegt. Die geringste Stufe ist „Zoom: 0“. Hier wird die gesamte Erde dargestellt. Um heranzuzoomen und die Erde in höherer Auflösung zu sehen, müssen Sie eine höhere Zoomstufe festlegen.
Zoomstufen
Um die gesamte Erde in einem einzigen Bild darzustellen, wäre entweder eine riesige Karte oder eine kleine Karte mit sehr geringer Auflösung erforderlich. Daher werden Kartenbilder in Google Maps und der Maps JavaScript API in Kartenkacheln und Zoomstufen unterteilt. Bei niedrigen Zoomstufen decken wenige Kartenkacheln einen großen Bereich ab. Bei höheren Stufen haben die Kacheln eine höhere Auflösung und decken einen kleineren Bereich ab. Die folgende Liste enthält die ungefähre Detailebene, die Sie bei der jeweiligen Zoomstufe erwarten können:
- 1: Welt
- 5: Landmasse oder Kontinent
- 10: Stadt
- 15: Straßen
- 20: Gebäude
Die folgenden drei Bilder zeigen Tokio in den Zoomstufen 0, 7 und 18.
Der folgende Code beschreibt die CSS-Attribute, über die die Größe des Elements gmp-map festgelegt wird.
/* 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 */ }
Im Code oben wird über das style-Element die Größe von gmp-map festgelegt. Die Breite und Höhe müssen auf mehr als 0 px festgelegt werden, damit die Karte sichtbar ist. In diesem Fall ist für das gmp-map-Element eine Höhe von 400 px und eine Breite von 100% festgelegt, damit die Karte über die gesamte Breite der Webseite angezeigt wird. Es wird empfohlen, die Höhe und Breite immer explizit festzulegen.
Kontrollgruppen
Mit der Steuerung von Slots können Sie Ihrer Karte HTML-Formularsteuerelemente hinzufügen. Ein Slot ist eine vordefinierte Position auf der Karte. Verwenden Sie das Attribut slot, um die erforderliche Position für ein Element festzulegen, und verschachteln Sie Elemente im gmp-map-Element. Im folgenden Snippet sehen Sie, wie Sie der oberen linken Ecke der Karte ein HTML-Label hinzufügen.
<!-- 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>Schritt 3: JavaScript-Code hinzufügen
In diesem Abschnitt erfahren Sie, wie Sie die Maps JavaScript API in eine Webseite laden und eigenen JavaScript-Code schreiben, um mithilfe der API eine Karte mit einer Markierung einzufügen.
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();
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();
Der obige Code führt Folgendes aus, wenn initMap() aufgerufen wird:
- Lädt die Bibliotheken
mapsundmarker. - Ruft das Kartenelement aus dem DOM ab.
- Legt zusätzliche Kartenoptionen für die innere Karte fest.
- Fügt der Karte eine Markierung hinzu.
Kartenobjekt abrufen und Optionen festlegen
innerMap steht für eine Instanz der Map-Klasse.
Um Kartenoptionen festzulegen, rufen Sie die innerMap-Instanz aus dem Kartenelement ab und rufen Sie setOptions auf.
Das folgende Snippet zeigt, wie die innerMap-Instanz aus dem DOM abgerufen und dann setOptions aufgerufen wird:
// 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, });
Warten, bis die Karte geladen ist
Wenn Sie das gmp-map-Element verwenden, wird die Karte asynchron geladen. Dies kann zu einem Race Condition führen, wenn während der Initialisierung andere Anfragen gestellt werden (z. B. eine Anfrage zum Abrufen des geografischen Standorts oder von Ortsdetails). Damit Ihr Code erst ausgeführt wird, wenn die Karte vollständig geladen ist, verwenden Sie in Ihrer Initialisierungsfunktion einen addListenerOnce-Ereignishandler für den Leerlauf, wie hier gezeigt:
// 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!"); });
So wird sichergestellt, dass Ihr Code erst ausgeführt wird, nachdem die Karte geladen wurde. Der Handler wird nur einmal während des Lebenszyklus der App ausgelöst.
Vollständiges Codebeispiel
Hier finden Sie den vollständigen Beispielcode:
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();
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();
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>
<!-- 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>Testbeispiel
Weitere Informationen zu Markierungen:
Tipps und Fehlerbehebung
- Weitere Informationen zum Abrufen von Breiten- und Längengraden oder Umwandeln von Adressen in geografische Koordinaten
- Optionen wie Stil und Eigenschaften lassen sich anpassen, um die Karte individuell zu gestalten. Weitere Informationen zum Anpassen von Karten finden Sie unter Cloudbasiertes Gestalten von Karteninhalten und Auf Karten zeichnen.
- Verwenden Sie die Entwicklertools in Ihrem Webbrowser, um Ihren Code zu testen und auszuführen, Fehlerberichte zu lesen und Probleme mit dem Code zu beheben.
- Mit den folgenden Tastenkombinationen können Sie die Konsole in Chrome aufrufen:
Befehlstaste + Optionstaste + J (Mac) oder Strg + Umschalttaste + J (Windows). So rufen Sie die Breiten- und Längengrade für einen Ort in Google Maps ab:
- Öffnen Sie Google Maps in einem Browser.
- Klicken Sie mit der rechten Maustaste auf die genaue Position auf der Karte, für die Sie Koordinaten benötigen.
- Wählen Sie im Kontextmenü, das eingeblendet wird, Was ist hier? aus. Unten auf dem Bildschirm wird eine Infokarte eingeblendet. Die Breiten- und Längengrade finden Sie in der letzten Zeile der Infokarte.
Mit dem Geocoding-Dienst können Sie eine Adresse in Breiten- und Längengrade umwandeln. Ausführliche Informationen zu den ersten Schritten mit dem Geocoding-Dienst finden Sie in den Entwicklerleitfäden.