Przegląd

Wybierz platformę: Android iOS JavaScript

Interfejs Maps JavaScript API pozwala dostosowywać mapy z użyciem 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 (drogowy, satelitarny, hybrydowy i teren), które możesz modyfikować za pomocą warstw i 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 obiektowo. Musisz też znać Mapy 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 poznanie 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 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();
index.ts

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();
index.js

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

style.css

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>
index.html
Zobacz przykład

Wypróbuj fragment

Nawet przy tym prostym przykładzie trzeba zwrócić uwagę na kilka rzeczy:

  1. Deklarujemy aplikację 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 div.
  4. Interfejs Maps JavaScript API wczytujemy za pomocą programu wczytywania wczytywania.

Poniżej omawiamy te etapy.

Wczytywanie interfejsu Maps JavaScript API

Zalecanym sposobem wczytywania interfejsu Maps JavaScript API jest program wczytujący. Alternatywą jest też program wczytujący interfejs JS API. Zalecamy przejrzenie obu metod i wybór tej, która najlepiej pasuje do struktury kodu w Twoim projekcie.

Więcej informacji znajdziesz w artykule Wczytywanie interfejsu Maps JavaScript API.

Program wczytujący

Wczytaj interfejs Maps JavaScript API, dodając do kodu aplikacji wbudowany program wczytywania, 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 wczytać 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();
index.ts

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();
index.js

Pakiet js-api-loader NPM

Aby wczytać interfejs Maps JavaScript API, użyj NPM za pomocą 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ł wczytujący udostępnia interfejs Promise i wywołania zwrotnego. Poniżej pokazano wykorzystanie 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,
  });
});
index.ts

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,
  });
});

index.js

Deklarowanie aplikacji jako HTML5

Zalecamy zadeklarowanie w aplikacji internetowej prawdziwego identyfikatora DOCTYPE. W poniższych przykładach zadeklarowaliśmy nasze aplikacje jako HTML5 przy użyciu prostego 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. Projekt DOCTYPE został również zaprojektowany z myślą o płynnej degradacji jakości: przeglądarki, które go nie rozumieją, zignorują go i będą wyświetlać zawartość w „trybie osobliwości”.

Pamiętaj, że niektóre elementy CSS działające w trybie osobliwości nie są prawidłowe w trybie standardowym. Wszystkie rozmiary określone procentowo muszą dziedziczyć z nadrzędnych elementów blokowych. 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ę 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 trzeba zadeklarować 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ć 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 wbudowane

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

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&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

Dostępny jest pakiet @googlemaps/js-api-loader, który umożliwia płynne ładowanie dynamiczne. 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ł wczytujący udostępnia interfejs Promise i wywołania zwrotnego. Poniżej pokazano wykorzystanie 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,
  });
});
index.ts

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,
  });
});

index.js

Atrybuty tagu skryptu

W powyższych przykładach w tagu script ustawiono kilka zalecanych atrybutów. Poniżej objaśniamy poszczególne atrybuty.

  • src: adres URL, z którego wczytuje się interfejs Maps JavaScript API, w tym wszystkie symbole i definicje potrzebne 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 adresu URL.
  • async: prosi przeglądarkę o asynchroniczne pobranie i wykonanie skryptu. Podczas wykonywania skrypt wywoła funkcję określoną za pomocą parametru callback.

Biblioteki

Podczas ładowania interfejsu Maps JavaScript API za pomocą adresu URL możesz opcjonalnie wczytać dodatkowe biblioteki, używając operatora await do wywoływania 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, dopóki o nie nie poprosisz. Więcej informacji znajdziesz w artykule Biblioteki w interfejsie Maps JavaScript API.

Mapowanie elementów DOM

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

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

W przykładzie powyżej użyliśmy CSS do ustawienia wysokości elementu div na mapie na „100%”. Spowoduje to rozwinięcie elementu oraz dopasowanie go do rozmiaru ekranu urządzenia mobilnego. Może być konieczne dostosowanie wartości szerokości i wysokości w zależności od rozmiaru ekranu i dopełnienia przeglądarki. Pamiętaj, że elementy div zwykle ustawiają szerokość elementu, który je zawiera, a puste elementy div mają zwykle zerową wysokość. Z tego powodu w elemencie <div> musisz zawsze wyraźnie ustawić wysokość.

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 określa właściwość zoom, gdzie powiększenie 0 odpowiada całkowicie pomniejszonej mapie Ziemi, a większe poziomy powiększenia – przy wyższej rozdzielczości.

zoom: 8

Oferowanie całej Ziemi w postaci pojedynczego zdjęcia wymagałoby olbrzymiej mapy lub małej 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 większy obszar, a przy większym powiększeniu – w wyższej rozdzielczości i na mniejszym obszarze. 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 przy powiększeniu 0, 7 i 18.

Więcej informacji o tym, jak interfejs Maps JavaScript API wczytuje fragmenty na podstawie bieżącego poziomu powiększenia, znajdziesz w przewodniku po współrzędnych mapy i fragmentów.

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 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 nowej instancji mapy określasz na stronie element HTML <div> jako kontener mapy. Węzły HTML są elementami podrzędnymi obiektu JavaScript document i uzyskują odwołanie 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 (który jest zwykle elementem DIV) przy użyciu dowolnych (opcjonalnych) przekazanych parametrów.

Rozwiązywanie problemów

Klucz interfejsu API i błędy rozliczeniowe

W niektórych przypadkach może pojawić się zaciemniona mapa lub „negatywne” zdjęcie 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 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. Oto instrukcje, które pomogą Ci rozwiązać ten problem:

Jeśli kod nie działa:

Aby pomóc Ci w utworzeniu kodu map, w tym filmie Brendan Kenny i Mano Marks wskazują kilka częstych 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ź podstawowe informacje – niektóre z najczęstszych problemów występują przy początkowym tworzeniu mapy. Na przykład:
    • Upewnij się, ż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, przez co są niewidoczne.
    Zapoznaj się z naszymi przykładami referencyjnej implementacji.
  • 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.
  • Zadaj pytania na stronie Stack Overflow. Wskazówki dotyczące publikowania ciekawych pytań są dostępne na stronie Pomoc.