Komponenty internetowe w interfejsie Maps JavaScript API (wersja przedpremierowa)

Web Komponenty to popularny standard W3C, który obejmuje kodowanie HTML, CSS i JS w niestandardowych i wielokrotnego użytku elementów HTML. Te komponenty wielokrotnego użytku mogą mieć szeroki zakres: od prostych elementów, takich jak wyświetlanie oceny miejsca w gwiazdkach, po bardziej złożone logiki biznesowe. W tym przewodniku opisano komponenty sieciowe dostępne w interfejsie Maps JavaScript API.

Więcej informacji o standardzie znajdziesz w artykule Komponenty sieciowe.

Odbiorcy

Ta dokumentacja została opracowana, aby umożliwić Ci szybkie rozpoczęcie odkrywania i tworzenia aplikacji za pomocą komponentów sieciowych. Musisz znać pojęcia programowania w HTML i CSS.

Wyświetl mapę

Najłatwiejszym sposobem na zapoznanie się z komponentami internetowymi jest skorzystanie z przykładu. Poniższy przykład zawiera mapę rejonu San Jose.

TypeScript

// This example adds a map using web components.
function initMap(): void {
    console.log('Maps JavaScript API loaded.');
}

declare global {
    interface Window {
        initMap: () => void;
    }
}
window.initMap = initMap;

JavaScript

// This example adds a map using web components.
function initMap() {
  console.log("Maps JavaScript API loaded.");
}

window.initMap = 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;
}

gmp-map {
  height: 400px;
}

HTML

<html>
  <head>
    <title>Add a Map Web Component</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>
    <gmp-map
      center="37.4220656,-122.0840897"
      zoom="10"
      map-id="DEMO_MAP_ID"
    ></gmp-map>

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=beta"
      defer
    ></script>
  </body>
</html>

Wypróbuj fragment

W tym przykładzie warto pamiętać o kilku kwestiach:

  1. Interfejs Map JavaScript API jest wywoływany asynchronicznie. Funkcja wywołania zwrotnego określa, kiedy interfejs API został załadowany.
  2. Sposób prezentacji mapy jest określany za pomocą elementu niestandardowego <gmp-map>.
  3. Właściwości mapy definiuje się, określając atrybuty w elemencie niestandardowym <gmp-map>.
  4. Styl można stosować w elementach niestandardowych lub zadeklarować w osobnym pliku CSS.

Określ styl mapy bazowej

Identyfikator mapy to identyfikator powiązany z konkretnym stylem mapy lub obiektem. Aby korzystać z opcjonalnych funkcji konfiguracji w chmurze, zastąp styl DEMO_MAP_ID map w chmurze własnym identyfikatorem mapy. Aby dowiedzieć się, jak utworzyć identyfikator mapy i skonfigurować styl niestandardowy, przeczytaj artykuł o stylach map w chmurze.

Dodawanie znaczników do mapy

Tak jak można zagnieżdżać wbudowane tagi HTML w celu tworzenia złożonych hierarchii treści, można też zagnieżdżać element <gmp-advanced-marker> w elemencie, aby wyświetlić 1 lub więcej znaczników mapy.

TypeScript

// This example adds a map with markers, using web components.
function initMap(): void {
    console.log('Maps JavaScript API loaded.');
}

declare global {
    interface Window {
        initMap: () => void;
    }
}
window.initMap = initMap;

JavaScript

// This example adds a map with markers, using web components.
function initMap() {
  console.log("Maps JavaScript API loaded.");
}

window.initMap = 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;
}

gmp-map {
  height: 400px;
}

HTML

<html>
  <head>
    <title>Add a Map with Markers using Web Components</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>
    <gmp-map center="43.4142989,-124.2301242" zoom="4" map-id="DEMO_MAP_ID">
      <gmp-advanced-marker
        position="37.4220656,-122.0840897"
        title="Mountain View, CA"
      ></gmp-advanced-marker>
      <gmp-advanced-marker
        position="47.648994,-122.3503845"
        title="Seattle, WA"
      ></gmp-advanced-marker>
    </gmp-map>

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&libraries=marker&v=beta"
      defer
    ></script>
  </body>
</html>

Wypróbuj fragment

Dodaliśmy tutaj 2 elementy <gmp-advanced-marker> w elemencie niestandardowym <gmp-map>. Tekst elementu title zawiera dodatkowy tekst znajdujący się po najechaniu kursorem i etykietę ułatwień dostępu dla określonego elementu.

Zdarzenia JavaScript

Główną zaletą komponentów sieciowych jest łatwość obsługi. Korzystając z kilku wierszy kodu, można wyświetlić mapę z ograniczoną wiedzą na temat JavaScriptu lub zaawansowanego programowania. Po zaimplementowaniu kodu zachowuje się zgodny ze znanymi wzorcami innych elementów HTML. Na przykład natywny system obsługi zdarzeń w przeglądarce może służyć do reagowania na działania związane z mapą i działaniami zaawansowanego znacznika (takie jak kliknięcie znacznika).

W kodzie HTML ustaw atrybut gmp-clickable w elemencie gmp-advanced-marker tak, aby znacznik był klikalny. Do obsługi zdarzeń kliknięcia używaj zasady advancedMarker.addEventListener.

TypeScript

// This example adds a map using web components.
function initMap(): void {
  console.log('Maps JavaScript API loaded.');
  const advancedMarkers = document.querySelectorAll("#marker-click-event-example gmp-advanced-marker");
  for (const advancedMarker of advancedMarkers) {

    customElements.whenDefined(advancedMarker.localName).then(async () => {
      advancedMarker.addEventListener('gmp-click', async () => {

        const infoWindow = new google.maps.InfoWindow({
          //@ts-ignore
          content: advancedMarker.title,
        });
        infoWindow.open({
          //@ts-ignore
          anchor: advancedMarker
        });
      });
    });
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// This example adds a map using web components.
function initMap() {
  console.log("Maps JavaScript API loaded.");

  const advancedMarkers = document.querySelectorAll(
    "#marker-click-event-example gmp-advanced-marker",
  );

  for (const advancedMarker of advancedMarkers) {
    customElements.whenDefined(advancedMarker.localName).then(async () => {
      advancedMarker.addEventListener("gmp-click", async () => {
        const infoWindow = new google.maps.InfoWindow({
          //@ts-ignore
          content: advancedMarker.title,
        });

        infoWindow.open({
          //@ts-ignore
          anchor: advancedMarker,
        });
      });
    });
  }
}

window.initMap = 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;
}

gmp-map {
  height: 400px;
}

HTML

<html>
  <head>
    <title>Add a Map Web Component with Events</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>
    <gmp-map
      id="marker-click-event-example"
      center="43.4142989,-124.2301242"
      zoom="4"
      map-id="DEMO_MAP_ID"
    >
      <gmp-advanced-marker
        position="37.4220656,-122.0840897"
        title="Mountain View, CA"
        gmp-clickable
      ></gmp-advanced-marker>
      <gmp-advanced-marker
        position="47.648994,-122.3503845"
        title="Seattle, WA"
        gmp-clickable
      ></gmp-advanced-marker>
    </gmp-map>

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&libraries=marker&v=beta"
      defer
    ></script>
  </body>
</html>

Wypróbuj fragment

W tym przykładzie initMap reprezentuje wymaganą funkcję wywołania zwrotnego po całkowitym wczytaniu interfejsu Maps JavaScript API. Kod ustawia detektory dla każdego znacznika i wyświetla okno informacyjne po kliknięciu każdego znacznika.

Co dalej?