Interfejs Maps JavaScript API pozwala dodawać własne treści i zdjęcia do wyświetlania na stronach internetowych i urządzeniach mobilnych. Interfejs Maps JavaScript API obejmuje 4 podstawowe typy map (mapa drogowa, satelitarna, hybrydowa i terenowa), które można modyfikować za pomocą warstw i stylów, elementów sterujących i zdarzeń oraz różnych usług i bibliotek.
Odbiorcy
Ta dokumentacja jest przeznaczona dla osób znających język programowania JavaScript i koncepcje programowania zorientowanego na obiekt. Musisz też zapoznać się z Mapami z perspektywy użytkownika. W internecie dostępnych jest wiele samouczków na temat JavaScriptu.
Ta dokumentacja koncepcyjna została opracowana, aby umożliwić Ci szybkie rozpoczęcie poznawania i tworzenia aplikacji za pomocą interfejsu Maps JavaScript API. Publikujemy też dokumentację API JavaScript Map Google.
Witaj świecie
Najłatwiejszym sposobem poznania interfejsu Maps JavaScript API jest zapoznanie się z prostym przykładem. Poniższy przykład przedstawia mapę wyśrodkowaną na Sydney w Nowej Południowej Walii w Australii.TypeScript
let map: google.maps.Map; async function initMap(): Promise<void> { const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary; map = new Map(document.getElementById("map") as HTMLElement, { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } initMap();
JavaScript
let map; async function initMap() { const { Map } = await google.maps.importLibrary("maps"); map = new Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } 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> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div id="map"></div> <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script> </body> </html>
Zobacz próbkę
Nawet w tym prostym przykładzie należy pamiętać o kilku kwestiach:
- Deklarujemy aplikację jako HTML5, używając deklaracji
<!DOCTYPE html>
. - Tworzymy element
div
o nazwie „map”, który będzie przechowywać mapę. - Definiujemy funkcję JavaScriptu, która tworzy mapę w
div
. - Interfejs Maps JavaScript API wczytujemy za pomocą programu wczytywania.
Poniżej omawiamy te etapy.
Wczytaj interfejs Maps JavaScript API
Zalecanym sposobem wczytywania interfejsu Maps JavaScript API jest Moduł wczytywania. Alternatywą jest też program wczytujący interfejs JS API. Zalecamy zapoznanie się z obydwoma podejściami i wybranie tej, która najlepiej pasuje do struktury kodu w Twoim projekcie.
Więcej informacji znajdziesz w artykule Wczytywanie interfejsu Maps JavaScript API.
Moduł wczytywania
Wczytaj interfejs Maps JavaScript API, dodając wbudowany moduł wczytywania do kodu aplikacji, jak w tym fragmencie:
<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>
Aby wczytywać biblioteki w czasie działania, użyj operatora await
do wywołania importLibrary()
z poziomu funkcji asynchronicznej, jak pokazano poniżej:
TypeScript
let map: google.maps.Map; async function initMap(): Promise<void> { const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary; map = new Map(document.getElementById("map") as HTMLElement, { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } initMap();
JavaScript
let map; async function initMap() { const { Map } = await google.maps.importLibrary("maps"); map = new Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); } initMap();
Pakiet js-api-loader NPM
Użyj @googlemaps/js-api-loader, aby użyć NPM do wczytywania interfejsu Maps JavaScript API. Zainstaluj ją przez NPM za pomocą tego polecenia:
npm install @googlemaps/js-api-loader
Pakiet można zaimportować do aplikacji za pomocą:
import { Loader } from "@googlemaps/js-api-loader"
Moduł ładowania ujawnia interfejs Promise i wywołania zwrotnego. Poniżej znajdziesz przykład użycia domyślnej metody Promise (load()
).
TypeScript
const loader = new Loader({ apiKey: "YOUR_API_KEY", version: "weekly", ...additionalOptions, }); loader.load().then(async () => { const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary; map = new 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(async () => { const { Map } = await google.maps.importLibrary("maps"); map = new Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); });
Zadeklarowanie aplikacji jako HTML5
Zalecamy zadeklarowanie w aplikacji internetowej prawdziwej wartości DOCTYPE
. W tych przykładach zadeklarowaliśmy nasze aplikacje jako HTML5 za pomocą prostego DOCTYPE
HTML5, jak w przykładzie poniżej:
<!DOCTYPE html>
Większość obecnych przeglądarek renderuje treści zadeklarowane za pomocą tego parametru DOCTYPE
w „trybie standardowym”, co oznacza, że aplikacja powinna być bardziej zgodna z różnymi przeglądarkami. Interfejs DOCTYPE
został zaprojektowany tak, aby płynnie się zmniejszać. Przeglądarki, które go nie rozumieją, zignorują go i wyświetlą treść w „trybie osobliwości”.
Pamiętaj, że niektóre CSS, które działają w trybie osobliwości, nie działają w trybie standardowym. Mówiąc konkretnie, wszystkie rozmiary określone w procentach muszą dziedziczyć z nadrzędnych elementów blokowych. Jeśli któryś z tych elementów nadrzędnych nie określi rozmiaru, przyjmuje się, że mają one wymiary 0 x 0 pikseli. Z tego względu dołączamy tę deklarację <style>
:
<style> #map { height: 100%; } html, body { height: 100%; margin: 0; padding: 0; } </style>
Ta deklaracja CSS wskazuje, że kontener mapy <div>
(o identyfikatorze map
) powinien zajmować 100% wysokości treści HTML. Pamiętaj, że musimy również zadeklarować te wartości procentowe w przypadku
<body>
i <html>
.
Wczytuję Maps JavaScript API
Interfejs Maps JavaScript API jest wczytywany za pomocą taguscript
, który można dodać w tekście pliku HTML lub dynamicznie za pomocą osobnego pliku JavaScript. Zalecamy zapoznanie się z obydwoma podejściami i wybranie tej, która najlepiej pasuje do struktury kodu w Twoim projekcie.
Wczytywanie wbudowane
Aby wczytać interfejs Maps JavaScript API bezpośrednio w pliku HTML, dodaj tag script
zgodnie z poniższym przykładem.
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>
Wczytywanie dynamiczne
Przykład poniżej pokazuje, jak dynamicznie ładować interfejs Maps JavaScript API bezpośrednio za pomocą osobnego pliku JavaScript. Takie podejście umożliwia obsługę całego kodu związanego z korzystaniem z interfejsu API z poziomu osobnego pliku .js
i jest odpowiednikiem dodania wbudowanego tagu skryptu.
// 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);
Wczytywanie dynamiczne
Dostępny jest pakiet @googlemaps/js-api-loader, który zapewnia płynniejsze ładowanie dynamiczne. Można go zainstalować za pomocą NPM przy użyciu:
npm install @googlemaps/js-api-loader
Pakiet można zaimportować do aplikacji za pomocą:
import { Loader } from "@googlemaps/js-api-loader"
Moduł ładowania ujawnia interfejs Promise i wywołania zwrotnego. Poniżej znajdziesz przykład użycia domyślnej metody Promise (load()
).
TypeScript
const loader = new Loader({ apiKey: "YOUR_API_KEY", version: "weekly", ...additionalOptions, }); loader.load().then(async () => { const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary; map = new 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(async () => { const { Map } = await google.maps.importLibrary("maps"); map = new Map(document.getElementById("map"), { center: { lat: -34.397, lng: 150.644 }, zoom: 8, }); });
Atrybuty tagu skryptu
Zwróć uwagę na powyższe przykłady, że w tagu script
ustawiono kilka atrybutów, co jest zalecane. Poniżej opisujemy każdy z atrybutów.
src
: adres URL, z którego wczytywany jest interfejs Maps JavaScript API, w tym wszystkie symbole i definicje potrzebne do korzystania z Maps JavaScript API. Adres URL w tym przykładzie ma 2 parametry:key
, gdzie podajesz klucz interfejsu API, orazcallback
, gdzie określasz nazwę funkcji globalnej, która zostanie wywołana po całkowitym wczytaniu interfejsu Maps JavaScript API. Dowiedz się więcej o parametrach adresów URL.async
: prosi przeglądarkę o asynchroniczne pobranie i wykonanie skryptu. Podczas wykonywania skrypt wywołuje funkcję określoną za pomocą parametrucallback
.
Biblioteki
Podczas wczytywania interfejsu Maps JavaScript API za pomocą adresu URL możesz opcjonalnie wczytać dodatkowe biblioteki, używając operatora await
do wywołania importLibrary()
z poziomu funkcji asynchronicznej. Biblioteki to moduły kodu, które zapewniają dodatkowe funkcje głównego interfejsu Maps JavaScript API, ale nie są wczytywane, jeśli ich wyraźnie nie zażądasz. Więcej informacji znajdziesz w artykule
Biblioteki w Maps JavaScript API.
Mapuj elementy DOM
<div id="map"></div>
Aby mapa wyświetlała się na stronie internetowej, musimy zarezerwować dla niej miejsce.
Zwykle robimy to, tworząc element div
i uzyskując odniesienie do tego elementu w obiektowym modelu dokumentu (DOM) przeglądarki.
W powyższym przykładzie użyliśmy CSS, aby ustawić wysokość elementu div mapy na „100%”. Reklama rozwija się do rozmiaru na urządzeniach mobilnych. Konieczne może być dostosowanie wartości szerokości i wysokości do rozmiaru ekranu i dopełnienia przeglądarki. Pamiętaj, że elementy div zazwyczaj przyjmują szerokość szerokości od elementu nadrzędnego, a puste elementy div mają zwykle 0 wysokości. Z tego powodu wysokość elementu <div>
zawsze należy ustawiać bezpośrednio.
Opcje mapy
Dla każdej mapy wymagane są 2 opcje: center
i zoom
.
map = new Map(document.getElementById('map'), { center: {lat: -34.397, lng: 150.644}, zoom: 8 });
Poziomy powiększenia
Początkowa rozdzielczość wyświetlania mapy jest ustawiana przez właściwość zoom
, w której powiększenie 0
odpowiada mapie całej Ziemi, a większe poziomy powiększania – w większej rozdzielczości.
zoom: 8
Oferowanie mapy całej Ziemi jako jednego obrazu wymagałoby dużej mapy lub małej mapy o bardzo niskiej rozdzielczości. W związku z tym obrazy map w Mapach Google i Maps JavaScript API są podzielone na „kafelki” i „poziomy powiększenia”. Przy małym powiększeniu mały zestaw kafelków mapy obejmuje szeroki obszar, a przy większym powiększeniu są one w wyższej rozdzielczości 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/kontynent
- 10: Miasto
- 15: Ulice
- 20. Budynki
Poniższe trzy obrazy przedstawiają tę samą lokalizację Tokio w poziomach powiększenia 0, 7 i 18.
Informacje o tym, jak interfejs Maps JavaScript API wczytuje kafelki na podstawie bieżącego poziomu powiększenia, znajdziesz w przewodniku po współrzędnych mapach i kafelkach.
Obiekt mapy
map = new Map(document.getElementById("map"), {...});
Klasa JavaScript reprezentująca mapę to klasa Map
.
Obiekty tej klasy definiują pojedynczą mapę na stronie. Możesz utworzyć więcej niż 1 instancję tej klasy – każdy obiekt będzie definiować osobną mapę na stronie. Tworzymy nową instancję tej klasy za pomocą operatora JavaScript new
.
Gdy tworzysz nową instancję mapy, określasz znajdujący się na stronie element HTML <div>
jako kontener mapy. Węzły HTML są elementami podrzędnymi obiektu JavaScript document
. Odniesienie do tego elementu uzyskujemy za pomocą metody document.getElementById()
.
Ten kod definiuje zmienną (o nazwie map
) i przypisuje ją do nowego obiektu Map
. Funkcja Map()
jest nazywana konstruktorem, a jej definicja znajduje się poniżej:
Zespół | Opis |
---|---|
Map(mapDiv:Node, opts?:MapOptions
) |
Tworzy nową mapę w obrębie danego kontenera HTML – który jest zwykle elementem DIV – przy użyciu dowolnych (opcjonalnych) przekazywanych parametrów. |
Rozwiązywanie problemów
Klucz interfejsu API i błędy rozliczeniowe
W pewnych okolicznościach może być wyświetlana zaciemniona mapa lub „negatywne” zdjęcie Street View z tekstem „Tylko do celów programistycznych”. Zwykle oznacza to problemy z kluczem interfejsu API lub płatnościami. Aby móc korzystać z usług Google Maps Platform, musisz włączyć na koncie płatności, a wszystkie żądania muszą zawierać prawidłowy klucz interfejsu API. Aby rozwiązać ten problem:
Jeśli kod nie działa:
Aby pomóc Ci w uruchomieniu kodu na mapie, Brendan Kenny i Mano Marks omawiają w tym filmie kilka częstych błędów i sposoby ich poprawiania.
- Sprawdź, czy nie ma literówek. Pamiętaj, że w języku JavaScript wielkość liter ma znaczenie.
- Sprawdź podstawy – niektóre z najczęstszych problemów występują podczas początkowego tworzenia mapy. Na przykład:
- Potwierdź, że w opcjach mapy określono właściwości
zoom
icenter
. - Upewnij się, że został zadeklarowany element div, w którym mapa będzie widoczna na ekranie.
- Upewnij się, że element div mapy ma wysokość. Elementy div domyślnie mają wysokość 0, więc są niewidoczne.
- Potwierdź, że w opcjach mapy określono właściwości
- W identyfikacji problemów, np. w Narzędziach deweloperskich w Chrome, możesz użyć debugera JavaScriptu. Zacznij od wyszukania błędów w konsoli JavaScript.
- Zadaj pytania w Stack Overflow. Wskazówki na temat publikowania ciekawych pytań znajdziesz na stronie Pomoc.