Nowy styl mapy będzie wkrótce dostępny w Google Maps Platform. Ta aktualizacja stylu mapy obejmuje nową domyślną paletę kolorów oraz ulepszenia ułatwiające obsługę i łatwość obsługi map. Wszystkie style mapy zostaną automatycznie zaktualizowane w marcu 2025 r. Więcej informacji o dostępności i sposobie włączania tej funkcji znajdziesz w artykule Nowy styl mapy w Google Maps Platform.

Ta strona została przetłumaczona przez Cloud Translation API.

Przegląd

Wybierz platformę: Android iOS JavaScript

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();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>

    <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

Zobacz próbkę

JSFiddle.net Google Cloud Shell

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();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

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

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

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, oraz callback, 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ą 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 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:

Czy używasz klucza interfejsu API?

Tego nie wiem. Jak sprawdzić, czy używam klucza interfejsu API?

Klucz interfejsu API jest przekazywany jako parametr key w adresie URL służącym do wczytywania interfejsu Maps JavaScript API. Oto kilka sposobów sprawdzenia, czy używasz klucza interfejsu API:

Użyj rozszerzenia do Chrome Google Maps Platform API Checker. Pozwoli Ci to sprawdzić, czy Twoja witryna prawidłowo implementuje licencjonowane interfejsy API Map Google.
Jeśli do wczytywania interfejsu Maps JavaScript API używasz biblioteki lub wtyczki, sprawdź ustawienia tej biblioteki i poszukaj opcji klucza interfejsu API.
Sprawdź błędy w przeglądarce. Jeśli widzisz te komunikaty, nie używasz poprawnie klucza interfejsu API:

Ostrzeżenie interfejsu Google Maps JavaScript API: NoApiKeys
Błąd interfejsu JavaScript API Map Google: MissingKeyMapError

Dla programistów stron internetowych:

Jeśli masz dostęp do kodu źródłowego swojej aplikacji, znajdź tag <script>, który służy do wczytywania interfejsu Maps JavaScript API. Podczas wczytywania interfejsu Maps JavaScript API wstaw YOUR_API_KEY w kodzie poniżej swoim kluczem interfejsu API.
```
  <script async defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
  </script>
```
Sprawdź w przeglądarce ruch w sieci generowany przez Twoją witrynę. W Chrome możesz to sprawdzić na karcie DevTools w Narzędziach deweloperskich. Zobaczysz tu żądania sieci wysłane przez Twoją witrynę. Żądania wysyłane za pomocą interfejsu Maps JavaScript API znajdują się pod ścieżką maps/api/js. Tutaj możesz sprawdzić, czy żądania używają parametru key. Podczas wyświetlania karty Sieć warto filtrować ruch w sieci według parametru maps/api/js.

Nie, nie używam klucza interfejsu API.

Aby uzyskać klucz interfejsu API, kliknij przycisk poniżej. Jeśli nie widzisz przewodnika konfiguracji, postępuj zgodnie z pełnymi instrukcjami w artykule Pierwsze kroki z Google Maps Platform.
Rozpocznij

Tak, używam klucza interfejsu API.

Świetnie! Sprawdźmy, czy z projektem jest połączone konto rozliczeniowe.

Czy z Twoim projektem jest połączone konto rozliczeniowe?

Tego nie wiem. Jak sprawdzić, czy z moim projektem połączone jest konto rozliczeniowe?

Otwórz stronę Płatności w konsoli Google Cloud i wybierz projekt, w którym utworzono Twój klucz interfejsu API. Aby potwierdzić, że klucz jest powiązany z projektem:

Przejdź do sekcji Dane logowania, która jest dostępna na pasku po lewej stronie w sekcji Google Maps Platform > Dane logowania.
Sprawdź, czy na liście znajduje się klucz interfejsu API, którego obecnie używasz w witrynie. Jeśli tak nie jest, przełącz się na inny projekt i sprawdź w nim dane logowania.
Jeśli nie możesz znaleźć projektu ze swoim kluczem interfejsu API, być może nie masz dostępu do tego projektu. Poproś o pomoc innych użytkowników ze swojej organizacji. Jeśli nie można znaleźć oryginalnego projektu, wykonaj te czynności:
1. Utwórz nowy projekt. Aby to zrobić, wybierz Nowy projekt na liście projektów lub kliknij Utwórz projekt na stronie Menedżera zasobów.
2. Tworzenie nowego klucza interfejsu API Możesz to zrobić na stronie Dane logowania. Następnie kliknij kolejno Utwórz dane logowania i Klucz interfejsu API.

Po znalezieniu projektu w Cloud Console sprawdź, czy powiązane jest z nim konto rozliczeniowe w sekcji Płatności w menu po lewej stronie.

Nie, konto rozliczeniowe nie jest połączone z moim projektem.

Otwórz stronę Włącz płatności w Cloud Console i dodaj konto rozliczeniowe do projektu. Więcej informacji znajdziesz w artykule o pierwszych krokach z Google Maps Platform.

Tak, z moim projektem jest połączone konto rozliczeniowe.

Świetnie! Upewnijmy się, że podana forma płatności jest prawidłowa.

Czy podana forma płatności jest już nieważna (np. karta kredytowa straciła ważność)?

Formy płatności możesz dodawać, usuwać i aktualizować w Cloud Console.

Czy w przypadku interfejsu API przekroczono samodzielnie nałożony dzienny limit?

Jeśli masz ustawiony limit dzienny dla któregoś z interfejsów API, co zwykle zapobiega nieoczekiwanemu wzrostowi liczby wyświetleń, możesz rozwiązać ten problem, zwiększając limit dzienny.

Limity dzienne możesz sprawdzić w panelu interfejsów API i usług w konsoli Cloud. Gdy to zrobisz:

Jeśli pojawi się taka prośba, wybierz projekt.
Wybierz interfejs API z listy, a następnie kliknij kartę Limity.

Czy klucz interfejsu API ma ograniczenie adresów IP?

Kluczy interfejsu API z ograniczeniem adresów IP można używać tylko w przypadku usług internetowych przeznaczonych do użytku po stronie serwera (np. Geocoding API i innych interfejsów API usług sieciowych). Większość z tych usług internetowych ma swoje odpowiedniki w Maps JavaScript API (zobacz np. usługę geokodowania). Aby korzystać z usług po stronie klienta Maps JavaScript API, musisz utworzyć oddzielny klucz interfejsu API, który można zabezpieczyć ograniczeniem stron odsyłających HTTP (zobacz Pobieranie, dodawanie i ograniczanie klucza interfejsu API).

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 i center.
- 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.
Zapoznaj się z naszymi przykładami implementacji referencyjnej.
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.