Mit der Maps JavaScript API können Sie Karten mit eigenen Inhalten und Bildern für die Anzeige auf Webseiten und Mobilgeräten anpassen. Die Maps JavaScript API umfasst vier Basiskartentypen (Straßen-, Satelliten-, hybride und Geländekarte), die Sie mithilfe von Ebenen und Stilen, Steuerelementen und Ereignissen sowie verschiedenen Diensten und Bibliotheken anpassen können.
Zielgruppe
Diese Dokumentation richtet sich an Personen, die sich mit JavaScript und objektorientierten Programmierungskonzepten auskennen. Außerdem sollten Sie mit Google Maps aus Sicht des Nutzers vertraut sein. Im Web sind viele JavaScript-Anleitungen verfügbar.
Diese konzeptbezogene Dokumentation soll Ihnen einen schnellen Einstieg in die Verwendung und Entwicklung von Anwendungen mit der Maps JavaScript API ermöglichen. Weitere Informationen sind in der Referenz zur Maps JavaScript API verfügbar.
Hello World
Mit einem einfachen Beispiel gelingt der Einstieg in die Maps JavaScript API am leichtesten. Im folgenden Beispiel wird eine Karte angezeigt, deren Mittelpunkt Sydney, New South Wales, Australien ist.TypeScript
let map: google.maps.Map; function initMap(): void { map = new google.maps.Map(document.getElementById("map") as HTMLElement, { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
let map; function initMap() { map = new google.maps.Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } window.initMap = initMap;
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; }
HTML
<html> <head> <title>Simple Map</title> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div id="map"></div> <!-- The `defer` attribute causes the callback to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises with https://www.npmjs.com/package/@googlemaps/js-api-loader. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly" defer ></script> </body> </html>
Testbeispiel
Selbst bei diesem einfachen Beispiel sind einige Dinge zu beachten:
- Mithilfe der
<!DOCTYPE html>
-Deklaration wird die Anwendung als HTML5 deklariert. - Es muss ein
div
-Element namens „map“ erstellt werden, das die Karte enthält. - Es wird eine JavaScript-Funktion definiert, die eine Karte im
div
-Element erstellt. - Die Maps JavaScript API wird mit einem
script
-Tag geladen.
Diese Schritte sind nachfolgend beschrieben.
Anwendung als HTML5 deklarieren
Wir empfehlen, einen echten DOCTYPE
in Ihrer Webanwendung zu deklarieren. In den Beispielen hier haben wir die Anwendungen über den einfachen 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> #map { height: 100%; } html, body { height: 100%; margin: 0; padding: 0; } </style>
Diese CSS-Deklaration gibt an, dass der <div>
-Kartencontainer (mit der ID map
) 100 % der Höhe des HTML-Textkörpers einnehmen soll. Auch für <body>
und <html>
müssen diese Prozentsätze ausdrücklich deklariert werden.
Maps JavaScript API laden
Die Maps JavaScript API wird mit einemscript
-Tag geladen, das direkt (inline) in Ihre HTML-Datei oder dynamisch mit einer separaten JavaScript-Datei eingefügt werden kann. Am besten setzen Sie sich mit beiden Ansätzen auseinander und wählen denjenigen aus, der für die Codestruktur Ihres Projekts am besten geeignet ist.
Inline laden
Um die Maps JavaScript API direkt (inline) in einer HTML-Datei zu laden, fügen Sie wie unten gezeigt ein script
-Tag ein.
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>
Dynamisch laden
Im folgenden Beispiel wird die Maps JavaScript API dynamisch über eine separate JavaScript-Datei geladen. Bei diesem Ansatz können Sie Ihren gesamten Code für die Arbeit mit der API über eine separate .js
-Datei verwalten. Dies entspricht der Inline-Einbindung des Skript-Tags.
// Create the script tag, set the appropriate attributes var script = document.createElement('script'); script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap'; script.async = true; // Attach your callback function to the `window` object window.initMap = function() { // JS API is loaded and available }; // Append the 'script' element to 'head' document.head.appendChild(script);
Dynamisch laden
Das Paket @googlemaps/js-api-loader ist verfügbar, um das dynamische Laden nahtloser zu gestalten. So wird es über NPM installiert:
npm install @googlemaps/js-api-loader
So wird das Paket in die Anwendung importiert:
import { Loader } from "@googlemaps/js-api-loader"
Das Ladeprogramm zeigt eine Promise- und Callback-Oberfläche an. Im Folgenden wird die Verwendung der standardmäßigen Promise-Methode load()
veranschaulicht.
TypeScript
const loader = new Loader({ apiKey: "YOUR_API_KEY", version: "weekly", ...additionalOptions, }); loader.load().then(() => { map = new google.maps.Map(document.getElementById("map") as HTMLElement, { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); });
JavaScript
const loader = new Loader({ apiKey: "YOUR_API_KEY", version: "weekly", ...additionalOptions, }); loader.load().then(() => { map = new google.maps.Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); });
Skript-Tag-Attribute
In den Beispielen oben sind mehrere empfohlene Attribute für das Tag script
festgelegt. Nachfolgend werden die einzelnen Attribute erläutert.
src
: Die URL, von der die Maps JavaScript API geladen wird, einschließlich aller Symbole und Definitionen, die Sie für die Verwendung der Maps JavaScript API benötigen. In diesem Beispiel hat die URL zwei Parameter:key
zum Angeben des API-Schlüssels undcallback
für den Namen einer globalen Funktion, die aufgerufen werden soll, sobald die Maps JavaScript API vollständig geladen wurde. Weitere Informationen zu URL-Parameternasync
: Weist den Browser an, das Skript asynchron herunterzuladen und auszuführen. Wenn das Skript ausgeführt wurde, wird die Funktion aufgerufen, die mit dem Parametercallback
angegeben wurde.
Bibliotheken
Wenn die Maps JavaScript API über die URL geladen wird, können Sie mithilfe des URL-Parameters libraries
optional weitere Bibliotheken laden. Bibliotheken sind Codemodule, die zusätzliche Funktionen für die primäre JavaScript API bieten. Sie werden nur geladen, wenn sie ausdrücklich angefordert werden. Weitere Informationen
API synchron laden
Im script
-Tag, mit dem die Maps JavaScript API geladen wird, können das Attribut defer
und der Parameter callback
weggelassen werden. Dadurch wird das Laden der API blockiert, bis sie vollständig heruntergeladen ist.
Dadurch wird die Seite wahrscheinlich langsamer geladen. Sie können aber nachfolgende Skript-Tags in der Gewissheit schreiben, dass die API bereits geladen ist.
DOM-Kartenelemente
<div id="map"></div>
Damit die Karte auf einer Webseite angezeigt werden kann, muss ein Platz für sie reserviert werden.
Dazu wird normalerweise ein benanntes div
-Element erstellt, auf das im DOM (Document Object Model) des Browsers verwiesen wird.
Im Beispiel oben haben wir CSS verwendet, um die Höhe des „div“-Elements der Karte auf „100 %“ festzulegen. Dadurch wird die Größe an den Bildschirm des jeweiligen Mobilgeräts angepasst. Möglicherweise müssen Sie die Werte für Breite und Höhe an die Bildschirmgröße und den Abstand des Browsers anpassen. „div“-Elemente übernehmen die Breite in der Regel von ihrem Container. Leere „div“-Elemente haben normalerweise eine Höhe von 0. Daher müssen Sie für <div>
immer explizit eine Höhe festlegen.
Kartenoptionen
Für jede Karte sind zwei Optionen erforderlich: center
und zoom
.
map = new google.maps.Map(document.getElementById('map'), { center: {lat: -34.397, lng: 150.644}, zoom: 8 });
Zoomstufen
Die anfängliche Auflösung, mit der die Karte angezeigt werden soll, wird über die zoom
-Eigenschaft definiert. Dabei entspricht die Zoomstufe 0
einer vollständig herausgezoomten Karte der Erde. Durch höhere Zoomstufen wird eine höhere Auflösung erzielt.
zoom: 8
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 Google Maps 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/Kontinent
- 10: Stadt
- 15: Straßen
- 20: Gebäude
Die folgenden drei Bilder zeigen Tokio in den Zoomstufen 0, 7 und 18.
Informationen dazu, wie die Maps JavaScript API Kacheln auf Grundlage der aktuellen Zoomstufe lädt, finden Sie im Leitfaden zu Karten- und Kachelkoordinaten.
Map-Objekte
map = new google.maps.Map(document.getElementById("map"), {...});
Die JavaScript-Klasse, mit der Karten dargestellt werden, ist die Map
-Klasse.
Objekte dieser Klasse definieren eine einzelne Karte auf einer Seite. Sie können mehrere Instanzen dieser Klasse erstellen. Jedes Objekt definiert eine separate Karte auf der Seite. Mit dem JavaScript-Operator new
wird eine neue Instanz dieser Klasse erstellt.
Wenn Sie eine neue Karteninstanz erstellen, geben Sie ein <div>
-HTML-Element auf der Seite als Container für die Karte an. HTML-Knoten sind untergeordnete Objekte des JavaScript-document
-Objekts. Ein Verweis auf dieses Element wird über die Methode document.getElementById()
abgerufen.
Dieser Code definiert eine Variable (namens map
) und weist sie einem neuen Map
-Objekt zu. Die Funktion Map()
wird als Konstruktor bezeichnet. Hier ist ihre Definition:
Konstruktor | Beschreibung |
---|---|
Map(mapDiv:Node, opts?:MapOptions
) |
Erstellt eine neue Karte innerhalb des angegebenen HTML-Containers (in der Regel ein „div“-Element). Dazu werden alle (optionalen) Parameter verwendet, die übergeben werden. |
Problembehebung
API-Schlüssel- und Abrechnungsfehler
Unter bestimmten Umständen werden dunkle Karten oder „negative“ Street View-Bilder ausgegeben, die mit dem Wasserzeichen „for development purposes only“ (nur für Entwicklungszwecke) versehen sind. Das weist in der Regel auf Probleme mit einem API-Schlüssel oder der Abrechnung hin. Damit Sie Google Maps Platform-Produkte nutzen können, muss die Abrechnung für Ihr Konto aktiviert sein. Außerdem müssen alle Anfragen einen gültigen API-Schlüssel enthalten. Der folgende Ablauf hilft bei der Fehlerbehebung:
Wenn der Code immer noch nicht funktioniert
Brendan Kenny und Mano Marks beschreiben in diesem Video einige häufige Fehler und zeigen Ihnen, wie Sie sie beheben können.
- Suchen Sie nach Tippfehlern. Denken Sie daran, dass in JavaScript zwischen Groß- und Kleinschreibung unterschieden wird.
- Sehen Sie sich die Grundlagen an. Einige der häufigsten Probleme treten bei der ersten Kartenerstellung auf. Beispiele:
- Prüfen Sie, ob Sie in den Kartenoptionen die Eigenschaften
zoom
undcenter
angegeben haben. - Vergewissern Sie sich, dass Sie ein „div“-Element deklariert haben, in dem die Karte auf dem Bildschirm angezeigt wird.
- Kontrollieren Sie, dass für das „div“-Element für die Karte eine Höhe definiert ist. „div“-Elemente werden standardmäßig mit einer Höhe von 0 erstellt und sind daher nicht sichtbar.
- Prüfen Sie, ob Sie in den Kartenoptionen die Eigenschaften
- Verwenden Sie eine JavaScript-Fehlersuche, z. B. die, die in den Chrome-Entwicklertools verfügbar ist. Suchen Sie zuerst in der JavaScript-Konsole nach Fehlern.
- Posten Sie Fragen auf Stack Overflow. Richtlinien für gute Fragen sind auf der Supportseite verfügbar.