Przegląd

Wybierz platformę: Android iOS JavaScript

Interfejs Maps JavaScript API umożliwia dostosowywanie map za pomocą własnych treści i zdjęć do wyświetlania na stronach internetowych i na urządzeniach mobilnych. Interfejs Maps JavaScript API obejmuje 4 podstawowe typy map (roadmap, satelitarne, hybrydowe i terenowe), które możesz 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, które znają język JavaScript i koncepcje programowania zorientowanego na obiekty. Zapoznaj się też z Mapami z perspektywy użytkownika. W internecie znajdziesz wiele samouczków na temat JavaScriptu.

Ta dokumentacja koncepcyjna ma umożliwić Ci szybkie rozpoczęcie odkrywania i tworzenia aplikacji za pomocą interfejsu Maps JavaScript API. Publikujemy też dokumentację interfejsu Maps JavaScript API.

Witaj świecie

Najłatwiejszym sposobem na rozpoczęcie poznawania interfejsu 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, 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>
    <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 przy tym prostym przykładzie warto zwrócić uwagę na kilka kwestii:

  1. Aplikacja deklaruje się jako HTML5 za pomocą deklaracji <!DOCTYPE html>.
  2. Tworzymy element div o nazwie „mapa”, który służy do przechowywania mapy.
  3. Definiujemy funkcję JavaScript, która tworzy mapę w elemencie div.
  4. Wczytujemy interfejs Maps JavaScript API 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 ładowanie interfejsu 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.

Wczytywanie

Wczytaj interfejs Maps JavaScript API, dodając do kodu aplikacji wbudowany program wczytywania, jak pokazano 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, jak w tym przykładzie:

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

Aby wczytać interfejs Maps JavaScript API za pomocą NPM, użyj funkcji @googlemaps/js-api-loader. Zainstaluj go przez 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ł wczytywania wyświetla interfejs obiecywania i wywołania zwrotnego. Poniżej pokazujemy użycie domyślnej metody obiecującej obietnicy: 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 prawdziwego parametru DOCTYPE. W poniższych przykładach zadeklarowaliśmy nasze aplikacje jako HTML5 za pomocą prostego elementu DOCTYPE HTML5, jak pokazano poniżej:

<!DOCTYPE html>

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

Pamiętaj, że niektóre elementy CSS, które działają w trybie osobliwości, nie są prawidłowe w trybie standardowym. W szczególności wszystkie rozmiary procentowe 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 rozmiar ma 0 x 0 pikseli. Z tego względu dołączamy tę deklaracja <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 te wartości procentowe muszą zostać zadeklarowane także w przypadku właściwości <body> i <html>.

Wczytuję interfejs Maps JavaScript API

Interfejs Maps JavaScript API jest wczytywany za pomocą tagu script, który można dodać bezpośrednio w 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 projekcie.

Ładowanie wbudowane

Aby wczytać interfejs Maps JavaScript API w pliku HTML, dodaj tag script jak poniżej.

<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 podczas pracy z interfejsem API w osobnym pliku .js i jest odpowiednikiem 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 za pomocą:

npm install @googlemaps/js-api-loader

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

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

Moduł wczytywania wyświetla interfejs obiecywania i wywołania zwrotnego. Poniżej pokazujemy użycie domyślnej metody obiecującej obietnicy: 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ę, że w powyższych przykładach w tagu script ustawiono kilka atrybutów, które są zalecane. Poniżej objaśniamy poszczególne atrybuty.

  • src: adres URL, z którego wczytuje się 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, w którym podaje się nazwę funkcji globalnej, która ma zostać wywołana po całkowitym wczytaniu interfejsu Maps JavaScript API. Dowiedz się więcej o parametrach adresu URL.
  • async: prosi przeglądarkę o asynchroniczne pobieranie i wykonywanie skryptu. Podczas wykonywania skryptu wywołuje 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ą wczytywane bez wyraźnego żądania. Więcej informacji znajdziesz w bibliotece w interfejsie Maps JavaScript API.

Zmapuj elementy DOM

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

Aby mapa została wyświetlona na stronie internetowej, musimy zarezerwować miejsce. Zwykle robimy to, tworząc nazwany element div i uzyskując do niego odwołanie w obiektowym modelu dokumentu (DOM) przeglądarki.

W przykładzie powyżej użyliśmy CSS, aby ustawić wysokość elementu div mapy na „100%”. Spowoduje to dostosowanie się do rozmiaru reklam na urządzeniach mobilnych. Może być konieczne dostosowanie wartości szerokości i wysokości zgodnie z rozmiarem ekranu i dopełnieniem przeglądarki. Pamiętaj, że elementy div zwykle pobierają szerokość z elementu, który zawiera, a puste elementy div mają zwykle 0 wysokości. Z tego powodu musisz zawsze ustawiać wysokość bezpośrednio w elemencie <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 pomniejszonej mapie kuli ziemskiej, a większe poziomy powiększenia – w wyższej rozdzielczości.

zoom: 8

Przedstawienie mapy całej Ziemi w postaci jednego zdjęcia wymagałoby albo ogromnej mapy, albo małej mapy o bardzo niskiej rozdzielczości. W związku z tym obrazy map w Mapach Google i interfejs Maps JavaScript API są podzielone na „kafelki” i „poziomy powiększenia”. Przy małym powiększeniu niewielki zestaw kafelków mapy obejmuje większy obszar, a przy większym powiększeniu – mają większą rozdzielczość i obejmą mniejszy obszar. Poniższa lista pokazuje przybliżony poziom szczegółowości na każdym poziomie powiększenia:

  • 1: świat
  • 5: ląd/kontynent
  • 10: Miasto
  • 15: Ulice
  • 20. Budynki

Poniższe 3 obrazy pokazują tę samą lokalizację Tokio przy powiększeniu 0, 7 i 18.

Informacje o tym, jak interfejs Maps JavaScript API wczytuje kafelki z uwzględnieniem bieżącego poziomu powiększenia, znajdziesz w przewodniku po współrzędnych fragmentach mapy i fragmentów.

Obiekt mapy

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

Klasa JavaScript reprezentująca mapę to klasa Map. Obiekty tej klasy definiują jedną mapę na stronie. (Możesz utworzyć więcej niż 1 instancję tej klasy – każdy obiekt będzie definiować 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łują się do tego elementu 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 jest podana poniżej:

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

Rozwiązywanie problemów

Klucz interfejsu API a błędy rozliczeniowe

W pewnych okolicznościach mogą być wyświetlane ciemne mapy lub „negatywne” zdjęcia Street View ze znakiem wodnym z tekstem „tylko do celów programistycznych”. Zwykle oznacza to problemy z kluczem interfejsu API lub płatnościami. Aby można było 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 map, w tym filmie Brendan Kenny i Mano Marks zwracają uwagę na kilka częstych błędów i sposoby ich naprawy.

  • Poszukaj literówek. Pamiętaj, że w języku JavaScript wielkość liter ma znaczenie.
  • Sprawdź podstawy – niektóre z najczęstszych problemów występują przy początkowym tworzeniu mapy. Na przykład:
    • Potwierdź, że w opcjach mapy określono właściwości zoom i center.
    • Pamiętaj, by zadeklarować element div, w którym mapa będzie wyświetlana na ekranie.
    • Upewnij się, że element div mapy ma wysokość. Domyślnie elementy div mają wysokość 0 i dlatego są niewidoczne.
    Zapoznaj się z przykładami implementacji.
  • Użyj debugera JavaScriptu, aby łatwiej zidentyfikować problem, na przykład taki, który znajdziesz 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ń są dostępne na stronie pomocy.