Przegląd

Wybierz platformę: Android iOS JavaScript

Interfejs Maps JavaScript API pozwala dostosowywać mapy do własnych treści i obrazów do wyświetlania na stronach internetowych i na urządzeniach mobilnych. Interfejs Maps JavaScript API udostępnia 4 podstawowe typy map (mapa dróg, satelitarna, hybrydowa i terenowa), które można modyfikować za pomocą warstw, stylów, elementów sterujących i zdarzeń, a także różnych usług i bibliotek.

Odbiorcy

Ta dokumentacja jest przeznaczona dla osób, które znają się na programowaniu w języku JavaScript i koncepcjach programowania zorientowanego na obiekt. Musisz też znać Mapy z perspektywy użytkownika. W internecie znajdziesz wiele samouczków na temat JavaScriptu.

Ta dokumentacja koncepcyjna została zaprojektowana tak, aby umożliwić Ci szybkie rozpoczęcie poznawania i tworzenia aplikacji za pomocą interfejsu Maps JavaScript API. Publikujemy też dokumentację interfejsu Maps JavaScript API.

Witaj świecie

Najprostszym sposobem na zapoznanie się z interfejsem Maps JavaScript API jest zapoznanie się z prostym przykładem. Poniższy przykład pokazuje mapę wyśrodkowaną na Sydney w Nowej Południowej Walii (Australia).

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

    <!-- 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 przykład

Wypróbuj fragment

Nawet w tym prostym przykładzie trzeba pamiętać o kilku kwestiach:

  1. Deklarujemy aplikację jako HTML5 za pomocą deklaracji <!DOCTYPE html>.
  2. Tworzymy element div o nazwie „mapa” do przechowywania mapy.
  3. Definiujemy funkcję JavaScript, która tworzy mapę w elemencie div.
  4. Interfejs Maps JavaScript API wczytuje się za pomocą programu wczytywania.

Poniżej omawiamy te etapy.

Wczytywanie interfejsu Maps JavaScript API

Zalecany sposób wczytywania interfejsu Maps JavaScript API to program ładujący. Alternatywnym rozwiązaniem 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 do kodu aplikacji wbudowany program rozruchowy, 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 funkcji asynchronicznej w ten sposób:

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 NPM js-api-loader

Aby używać NPM do wczytywania interfejsu Maps JavaScript API, użyj funkcji @googlemaps/js-api-loader. Zainstaluj go za pomocą NPM za pomocą tego polecenia:

npm install @googlemaps/js-api-loader

Ten pakiet można zaimportować do aplikacji za pomocą:

import { Loader } from "@googlemaps/js-api-loader"

Moduł wczytujący udostępnia interfejs Promise i wywołania zwrotnego. Poniżej pokazujemy użycie 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,
  });
});

Deklarowanie aplikacji jako HTML5

Zalecamy zadeklarowanie w aplikacji internetowej wartości DOCTYPE. W poniższych przykładach zadeklarowaliśmy nasze aplikacje jako HTML5 przy użyciu prostego elementu HTML5 DOCTYPE, jak pokazano poniżej:

<!DOCTYPE html>

Większość obecnych przeglądarek renderuje treści zadeklarowane w komponencie DOCTYPE w „trybie standardowym”, co oznacza, że aplikacja powinna być bardziej zgodna z różnymi przeglądarkami. Interfejs DOCTYPE został też zaprojektowany w taki sposób, aby płynnie się zmniejszać. Przeglądarki, które go nie rozumieją, ignorują go i wyświetlają zawartość w „trybie osobliwości”.

Pamiętaj, że niektóre elementy CSS, które działają w trybie osobliwości, nie działają w trybie standardowym. W szczególności wszystkie rozmiary określone procentowo muszą dziedziczyć elementy bloków nadrzędnych. Jeśli któryś z tych elementów nadrzędnych nie określi rozmiaru, zakłada się, że jego rozmiar to 0 x 0 pikseli. Dlatego uwzględniamy 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 trzeba zadeklarować te wartości procentowe także w przypadku właściwości <body> i <html>.

Wczytuję interfejs Maps JavaScript API

Interfejs Maps JavaScript API wczytuje się za pomocą tagu script, który można dodać do pliku HTML lub dynamicznie za pomocą osobnego pliku JavaScript. Zalecamy zapoznanie się z obydwiema podejściami i wybranie tej, która najlepiej pasuje do struktury kodu w projekcie.

Wczytywanie bezpośrednie

Aby wczytać interfejs Maps JavaScript API w pliku HTML, dodaj tag script w podany niżej sposób.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Wczytywanie dynamiczne

Zobacz przykład poniżej, aby dynamicznie wczytywać wbudowany interfejs Maps JavaScript API za pomocą osobnego pliku JavaScript. Ta metoda umożliwia obsługę całego kodu na potrzeby pracy z interfejsem API w osobnym 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

Aby zapewnić płynniejsze dynamiczne wczytywanie, dostępny jest pakiet @googlemaps/js-api-loader. Można ją zainstalować za pomocą NPM z użyciem tych elementów:

npm install @googlemaps/js-api-loader

Ten pakiet można zaimportować do aplikacji za pomocą:

import { Loader } from "@googlemaps/js-api-loader"

Moduł wczytujący udostępnia interfejs Promise i wywołania zwrotnego. Poniżej pokazujemy użycie 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

W powyższych przykładach można zauważyć, że w tagu script ustawiono kilka atrybutów, które są zalecane. Poniżej objaśniamy poszczególne atrybuty.

  • src: adres URL, z którego jest ładowany interfejs Maps JavaScript API, wraz ze wszystkimi symbolami i definicjami potrzebnymi do korzystania z interfejsu Maps JavaScript API. Adres URL w tym przykładzie ma 2 parametry: key, gdzie podaje się klucz interfejsu API, i callback, gdzie określa 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 skryptu wywoła on funkcję określoną za pomocą parametru callback.

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 funkcji asynchronicznej. Biblioteki to moduły kodu, które zapewniają dodatkowe funkcje głównego interfejsu Maps JavaScript API, ale nie są ładowane, dopóki o nie nie poprosisz. Więcej informacji znajdziesz w artykule o bibliotekach w interfejsie Maps JavaScript API.

Mapuj elementy DOM

<div id="map"></div>

Aby mapa była wyświetlana na stronie internetowej, musimy zarezerwować dla niej miejsce. Zwykle robimy to, tworząc nazwany element div i uzyskając odniesienie do tego elementu w obiektowym modelu dokumentu (DOM) przeglądarki.

W przykładzie powyżej użyliśmy CSS, aby ustawić wysokość elementu div mapy na „100%”. Rozwinie się, aby zmieścić się w rozmiarze na urządzeniach mobilnych. W zależności od rozmiaru ekranu i dopełnienia przeglądarki konieczne może być dostosowanie wartości szerokości i wysokości. Pamiętaj, że elementy div zwykle pobierają szerokość z elementu, który je zawiera, a puste elementy div mają zwykle zerową wysokość. Z tego powodu musisz zawsze wyraźnie ustawiać wysokość elementu <div>.

Opcje mapy

W przypadku 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 określa właściwość zoom, gdzie powiększenie 0 odpowiada całkowicie pomniejszeniu mapy Ziemi, a większe poziomy powiększenia – przy większej rozdzielczości.

zoom: 8

Oferowanie całej Ziemi w postaci pojedynczego zdjęcia wymagałoby dużej mapy lub niewielkiej mapy o bardzo niskiej rozdzielczości. W efekcie obrazy map w Mapach Google i interfejsie Maps JavaScript API są dzielone na „kafelki” i „poziomy powiększenia”. Przy małym powiększeniu niewielki zestaw fragmentów mapy obejmuje duży obszar, a przy większym powiększeniu mają one większą 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/kontynent
  • 10: Miasto
  • 15: Ulice
  • 20. Budynki

Poniższe 3 obrazy przedstawiają tę samą lokalizację Tokio na poziomach 0, 7 i 18.

Więcej informacji o tym, jak interfejs Maps JavaScript API wczytuje kafelki z bieżącym poziomem powiększenia, znajdziesz w przewodniku po współrzędnych mapach i kafelkach.

Obiekt mapy

map = new Map(document.getElementById("map"), {...});

Klasa JavaScript, która reprezentuje mapę, to klasa Map. Obiekty tej klasy definiują pojedynczą mapę na stronie. (Możesz utworzyć więcej instancji tej klasy – każdy obiekt zdefiniuje na stronie osobną mapę). Tworzymy nową instancję tej klasy przy użyciu operatora JavaScript new.

Podczas tworzenia nowego wystąpienia mapy jako kontener mapy określasz element HTML <div> na stronie. Węzły HTML są elementami podrzędnymi obiektu JavaScript document i odwołujemy się do tego elementu za pomocą metody document.getElementById().

Ten kod określa zmienną (o nazwie map) i przypisuje ją do nowego obiektu Map. Funkcja Map() jest nazywana konstruktorem, a jej definicja jest widoczna poniżej:

Zespół Opis
Map(mapDiv:Node, opts?:MapOptions ) Tworzy nową mapę wewnątrz danego kontenera HTML (zwykle jest to element DIV), przy użyciu dowolnych (opcjonalnych) przekazanych parametrów.

Rozwiązywanie problemów

Klucz interfejsu API i błędy rozliczeniowe

W pewnych okolicznościach przyciemniona mapa lub „negatywne” zdjęcie Street View może się wyświetlać ze znakiem wodnym z tekstem „tylko do celów programistycznych”. Takie zachowanie zwykle oznacza problemy z kluczem interfejsu API lub płatnościami. Aby korzystać z usług Google Maps Platform, na Twoim koncie muszą być włączone płatności, a wszystkie żądania muszą zawierać prawidłowy klucz interfejsu API. Aby rozwiązać ten problem, wykonaj te czynności:

Jeśli kod nie działa:

Aby pomóc Ci w utworzeniu kodu w Mapach, Brendan Kenny i Mano Marks pokazują w tym filmie kilka typowych błędów i sposoby ich naprawy.

  • Sprawdź, czy nie ma literówek. Pamiętaj, że w języku JavaScript rozróżniana jest wielkość liter.
  • Sprawdź podstawy – niektóre z najczęstszych problemów występują przy początkowym tworzeniu mapy. Na przykład:
    • Potwierdź, że w opcjach mapy zostały określone właściwości zoom i center.
    • Pamiętaj, aby zadeklarować element div, w którym mapa wyświetli się na ekranie.
    • Sprawdź, czy element div mapy ma wysokość. Domyślnie elementy div mają wysokość 0 i dlatego są niewidoczne.
    Informacje o implementacji znajdziesz w przykładach.
  • Użyj debugera JavaScriptu, aby zidentyfikować problemy (takie jak ten dostępny w Narzędziach deweloperskich w Chrome). Zacznij od wyszukania błędów w konsoli JavaScript.
  • Opublikuj pytania w Stack Overflow. Wytyczne na temat publikowania ciekawych pytań znajdziesz na stronie Pomoc.