Wydarzenia

Wybierz platformę: Android iOS JavaScript

Na tej stronie opisujemy zdarzenia interfejsu i zdarzenia błędów, które możesz nasłuchiwać i obsługiwać automatycznie.

Zdarzenia w interfejsie

Skrypt JavaScript w przeglądarce jest sterowany zdarzeniami, co oznacza, że odpowiada na interakcje, generując zdarzenia, i oczekuje, że program nasłuchuje interesujące zdarzenia. Istnieją 2 typy zdarzeń:

• Zdarzenia użytkownika (takie jak zdarzenia myszy) są przekazywane z modelu DOM do interfejsu Maps JavaScript API. Są to zdarzenia niezależne od standardowych zdarzeń DOM.
• Powiadomienia o zmianach stanu MVC odzwierciedlają zmiany w obiektach Maps JavaScript API i są nazywane zgodnie z konwencją property_changed.

Każdy obiekt Maps JavaScript API eksportuje liczbę nazwanych zdarzeń. Programy zainteresowane określonymi zdarzeniami rejestrują detektory zdarzeń JavaScript dla tych zdarzeń i wykonują kod po odebraniu tych zdarzeń przez wywołanie metody addListener() w celu zarejestrowania modułów obsługi zdarzeń na obiekcie.

Z przykładu poniżej dowiesz się, które zdarzenia są wywoływane przez interfejs google.maps.Map podczas korzystania z mapy.

Pełną listę zdarzeń znajdziesz w dokumentacji interfejsu Maps JavaScript API. Zdarzenia są wymienione w osobnej sekcji dla każdego obiektu, który je zawiera.

Zdarzenia w interfejsie

Niektóre obiekty w Maps JavaScript API są zaprojektowane tak, by reagować na zdarzenia użytkownika, takie jak zdarzenia myszy lub klawiatury. Oto niektóre z zdarzeń użytkownika, których może nasłuchiwać obiekt google.maps.marker.AdvancedMarkerElement:

• 'click'
• 'drag'
• 'dragend'
• 'dragstart'
• 'gmp-click'

Pełną listę znajdziesz w klasie AdvancedMarkerElement. Te zdarzenia mogą wyglądać jak standardowe zdarzenia DOM, ale w rzeczywistości są częścią interfejsu Maps JavaScript API. Różne przeglądarki implementują różne modele zdarzeń DOM, dlatego Maps JavaScript API udostępnia te mechanizmy, które umożliwiają nasłuchiwanie zdarzeń DOM i reagowanie na nie bez konieczności obsługi różnych różnic między przeglądarkami. Zdarzenia te zwykle przekazują też argumenty w zdarzeniu, które informują o pewnym stanie interfejsu (na przykład położenie myszy).

Zmiany stanu MVC

Obiekty MVC zazwyczaj zawierają stan. Za każdym razem, gdy zmieni się właściwość obiektu, interfejs Maps JavaScript API wywoła zdarzenie, które spowoduje zmianę tej właściwości. Na przykład interfejs API wywoła na mapie zdarzenie zoom_changed po zmianie poziomu powiększenia. Te zmiany stanu możesz przechwycić, wywołując funkcję addListener() w celu zarejestrowania modułów obsługi zdarzeń również na obiekcie.

Zdarzenia użytkownika i zmiany stanu MVC mogą wyglądać podobnie, ale zazwyczaj należy traktować je inaczej w kodzie. Na przykład zdarzenia MVC nie przekazują argumentów w zdarzeniu. Musisz sprawdzić właściwość, która uległa zmianie po zmianie stanu MVC, wywołując w tym obiekcie odpowiednią metodę getProperty.

Obsługa zdarzeń

Aby zarejestrować się, aby otrzymywać powiadomienia o zdarzeniach, użyj modułu obsługi zdarzeń addListener(). Ta metoda przyjmuje nasłuchiwane zdarzenie i funkcję wywoływaną po wystąpieniu określonego zdarzenia.

Przykład: zdarzenia mapy i znaczników

Ten kod łączy zdarzenia użytkownika ze zdarzeniami zmiany stanu. Do znacznika dołączamy moduł obsługi zdarzeń, który po kliknięciu powiększa mapę. Do mapy dodajemy również moduł obsługi zdarzeń na potrzeby zmian właściwości center. Po 3 sekundach od otrzymania zdarzenia center_changed następuje przesuwanie mapy z powrotem do znacznika:

TypeScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const myLatlng = { lat: -25.363, lng: 131.044 };

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: myLatlng,
      mapId: "DEMO_MAP_ID",
    }
  );

  const marker = new google.maps.marker.AdvancedMarkerElement({
    position: myLatlng,
    map,
    title: "Click to zoom",
  });

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.position as google.maps.LatLng);
    }, 3000);
  });

  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.position as google.maps.LatLng);
  });
}

initMap();
index.ts

Uwaga: przeczytaj przewodnik po korzystaniu z TypeScriptu i Map Google.

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");
  const myLatlng = { lat: -25.363, lng: 131.044 };
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: myLatlng,
    mapId: "DEMO_MAP_ID",
  });
  const marker = new google.maps.marker.AdvancedMarkerElement({
    position: myLatlng,
    map,
    title: "Click to zoom",
  });

  map.addListener("center_changed", () => {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(() => {
      map.panTo(marker.position);
    }, 3000);
  });
  marker.addListener("click", () => {
    map.setZoom(8);
    map.setCenter(marker.position);
  });
}

initMap();
index.js

Uwaga: JavaScript jest kompilowany na podstawie fragmentu kodu TypeScript.

Zobacz przykład

Zobacz próbkę

JSFiddle.net Google Cloud Shell

Wskazówka: jeśli chcesz wykryć zmianę w widocznym obszarze, użyj konkretnego zdarzenia bounds_changed, a nie składowych zdarzeń zoom_changed i center_changed. Interfejs Maps JavaScript API uruchamia te ostatnie zdarzenia niezależnie, dlatego getBounds() może zgłaszać przydatne wyniki dopiero po całkowitej zmianie widocznego obszaru. Jeśli chcesz wykonać wywołanie getBounds() po takim zdarzeniu, nasłuchuj zdarzenia bounds_changed.

Przykład: edytowanie kształtów i przeciąganie zdarzeń

Gdy kształt jest edytowany lub przeciągnięty, po wykonaniu tego działania wywoływane jest zdarzenie. Listę zdarzeń i niektóre fragmenty kodu znajdziesz w artykule Kształty.

Wyświetl przykład (rectangle-event.html)

Dostęp do argumentów w zdarzeniach interfejsu

Zdarzenia interfejsu w interfejsie Maps JavaScript API zwykle przekazują argument zdarzenia, do którego detektor zdarzeń ma dostęp i odnotowuje stan interfejsu użytkownika w momencie wystąpienia zdarzenia. Na przykład zdarzenie interfejsu 'click' zwykle przekazuje MouseEvent, który zawiera właściwość latLng, która wskazuje klikniętą lokalizację na mapie. Pamiętaj, że to zachowanie jest unikalne dla zdarzeń interfejsu. Zmiany stanu MVC nie przekazują argumentów w ich zdarzeniach.

Dostęp do argumentów zdarzenia w detektorze zdarzeń możesz uzyskać tak samo jak do właściwości obiektu. Poniższy przykład dodaje detektor zdarzeń dla mapy i tworzy znacznik, gdy użytkownik kliknie mapę w lokalizacji klikniętej na mapie.

TypeScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -25.363882, lng: 131.044922 },
      mapId: "DEMO_MAP_ID",
    }
  );

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng: google.maps.LatLng, map: google.maps.Map) {
  new google.maps.marker.AdvancedMarkerElement({
    position: latLng,
    map: map,
  });
  map.panTo(latLng);
}

initMap();
index.ts

Uwaga: przeczytaj przewodnik po korzystaniu z TypeScriptu i Map Google.

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary(
    "marker",
  );
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
    mapId: "DEMO_MAP_ID",
  });

  map.addListener("click", (e) => {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  new google.maps.marker.AdvancedMarkerElement({
    position: latLng,
    map: map,
  });
  map.panTo(latLng);
}

initMap();
index.js

Uwaga: JavaScript jest kompilowany na podstawie fragmentu kodu TypeScript.

Zobacz przykład

Zobacz próbkę

JSFiddle.net Google Cloud Shell

Używanie zamykania w detektorach zdarzeń

Przy uruchamianiu odbiornika często dobrze jest mieć dołączone do obiektu zarówno prywatne, jak i trwałe dane. JavaScript nie obsługuje „prywatnych” danych instancji, ale obsługuje zamknięcia, które umożliwiają wewnętrznym funkcjom dostęp do zmiennych zewnętrznych. Zamknięcia są przydatne w detektorach zdarzeń, umożliwiając dostęp do zmiennych, które nie są normalnie dołączone do obiektów, w których występują zdarzenia.

W przykładzie poniżej użyto zamknięcia funkcji w detektorze zdarzeń w celu przypisania wiadomości tajnego do zestawu znaczników. Kliknięcie każdego znacznika spowoduje wyświetlenie części tajnej wiadomości, która nie jest zawarta w samym znaczniku.

TypeScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -25.363882, lng: 131.044922 },
      mapId: "DEMO_MAP_ID",
    }
  );

  const bounds: google.maps.LatLngBoundsLiteral = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141,
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const marker = new google.maps.marker.AdvancedMarkerElement({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random(),
      },
      map: map,
    });

    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(
  marker: google.maps.marker.AdvancedMarkerElement,
  secretMessage: string
) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.map, marker);
  });
}

initMap();
index.ts

Uwaga: przeczytaj przewodnik po korzystaniu z TypeScriptu i Map Google.

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -25.363882, lng: 131.044922 },
    mapId: "DEMO_MAP_ID",
  });
  const bounds = {
    north: -25.363882,
    south: -31.203405,
    east: 131.044922,
    west: 125.244141,
  };

  // Display the area between the location southWest and northEast.
  map.fitBounds(bounds);

  // Add 5 markers to map at random locations.
  // For each of these markers, give them a title with their index, and when
  // they are clicked they should open an infowindow with text from a secret
  // message.
  const secretMessages = ["This", "is", "the", "secret", "message"];
  const lngSpan = bounds.east - bounds.west;
  const latSpan = bounds.north - bounds.south;

  for (let i = 0; i < secretMessages.length; ++i) {
    const marker = new google.maps.marker.AdvancedMarkerElement({
      position: {
        lat: bounds.south + latSpan * Math.random(),
        lng: bounds.west + lngSpan * Math.random(),
      },
      map: map,
    });

    attachSecretMessage(marker, secretMessages[i]);
  }
}

// Attaches an info window to a marker with the provided message. When the
// marker is clicked, the info window will open with the secret message.
function attachSecretMessage(marker, secretMessage) {
  const infowindow = new google.maps.InfoWindow({
    content: secretMessage,
  });

  marker.addListener("click", () => {
    infowindow.open(marker.map, marker);
  });
}

initMap();
index.js

Uwaga: JavaScript jest kompilowany na podstawie fragmentu kodu TypeScript.

Zobacz przykład

Zobacz próbkę

JSFiddle.net Google Cloud Shell

Pobieranie i ustawianie właściwości w modułach obsługi zdarzeń

Żadne ze zdarzeń zmiany stanu MVC w systemie zdarzeń Maps JavaScript API nie przekazują argumentów po wywołaniu zdarzenia. Zdarzenia użytkownika przekazują argumenty, które można sprawdzać. Jeśli chcesz sprawdzić właściwość po zmianie stanu MVC, musisz jawnie wywołać dla tego obiektu odpowiednią metodę getProperty(). Ta kontrola zawsze pobiera bieżący stan obiektu MVC, który może nie być stanem w momencie pierwszego wywołania zdarzenia.

Uwaga: jawne ustawienie w ramach modułu obsługi zdarzeń właściwości, która reaguje na zmianę stanu tej konkretnej usługi, może powodować nieprzewidywalne lub niepożądane zachowanie. Skonfigurowanie takiej właściwości wywoła na przykład nowe zdarzenie, a jeśli zawsze ustawisz ją w tym module obsługi zdarzeń, może to spowodować utworzenie pętli nieskończonej.

W przykładzie poniżej skonfigurowaliśmy moduł obsługi zdarzeń, który będzie reagował na zdarzenia powiększenia, wyświetlając okno informacyjne wyświetlające ten poziom.

TypeScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;

  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: originalMapCenter,
    }
  );

  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);

  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom()!);
  });
}

initMap();
index.ts

Uwaga: przeczytaj przewodnik po korzystaniu z TypeScriptu i Map Google.

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: originalMapCenter,
  });
  const infowindow = new google.maps.InfoWindow({
    content: "Change the zoom level",
    position: originalMapCenter,
  });

  infowindow.open(map);
  map.addListener("zoom_changed", () => {
    infowindow.setContent("Zoom: " + map.getZoom());
  });
}

initMap();
index.js

Uwaga: JavaScript jest kompilowany na podstawie fragmentu kodu TypeScript.

Zobacz przykład

Zobacz próbkę

JSFiddle.net Google Cloud Shell

Wykrywaj zdarzenia DOM

Model zdarzeń Maps JavaScript API tworzy własne zdarzenia niestandardowe i nimi zarządza. DOM w przeglądarce tworzy jednak i wysyła własne zdarzenia zgodnie z używanym modelem zdarzeń przeglądarki. Jeśli chcesz przechwytywać te zdarzenia i odpowiadać na nie, interfejs Maps JavaScript API udostępnia metodę statyczną addDomListener() służącą do nasłuchiwania zdarzeń DOM i tworzenia powiązań z nimi.

Ta wygodna metoda ma podpis, jak pokazano poniżej:

addDomListener(instance:Object, eventName:string, handler:Function)

gdzie instance może być dowolnym elementem DOM obsługiwanym przez przeglądarkę, w tym:

• Hierarchiczne elementy DOM, np. window lub document.body.myform
• Elementy nazwane, np. document.getElementById("foo")

Zwróć uwagę, że interfejs addDomListener() przekazuje wskazane zdarzenie do przeglądarki, która obsługuje je zgodnie z modelem zdarzenia DOM przeglądarki. Jednak prawie wszystkie nowoczesne przeglądarki obsługują przynajmniej DOM poziomu 2. Więcej informacji o zdarzeniach na poziomie DOM znajdziesz w dokumentacji Mozilla DOM Levels (Poziomy DOM Mozilli).

TypeScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;

  const mapDiv = document.getElementById("map") as HTMLElement;
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

initMap();
index.ts

Uwaga: przeczytaj przewodnik po korzystaniu z TypeScriptu i Map Google.

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map } = await google.maps.importLibrary("maps");
  const mapDiv = document.getElementById("map");
  const map = new google.maps.Map(mapDiv, {
    zoom: 8,
    center: new google.maps.LatLng(-34.397, 150.644),
  });

  // We add a DOM event here to show an alert if the DIV containing the
  // map is clicked.
  google.maps.event.addDomListener(mapDiv, "click", () => {
    window.alert("Map was clicked!");
  });
}

initMap();
index.js

Uwaga: JavaScript jest kompilowany na podstawie fragmentu kodu TypeScript.

HTML

<html>
  <head>
    <title>Listening to DOM Events</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

Powyższy kod jest kodem interfejsu Maps JavaScript API, jednak metoda addDomListener() wiąże się z obiektem window przeglądarki i umożliwia interfejsowi API komunikowanie się z obiektami spoza normalnej domeny interfejsu API.

Usuń detektory zdarzeń

Aby usunąć konkretny detektor zdarzeń, musi on być przypisany do zmiennej. Następnie możesz wywołać removeListener() i przekazać nazwę zmiennej, do której przypisano detektor.

var listener1 = marker.addListener('click', aFunction);

google.maps.event.removeListener(listener1);

Aby usunąć wszystkie detektory z konkretnej instancji, wywołaj clearInstanceListeners(), przekazując nazwę instancji.

var listener1 = marker.addListener('click', aFunction);
var listener2 = marker.addListener('mouseover', bFunction);

// Remove listener1 and listener2 from marker instance.
google.maps.event.clearInstanceListeners(marker);

Aby usunąć wszystkie detektory określonego typu zdarzenia w konkretnej instancji, wywołaj clearListeners(), przekazując nazwę instancji i nazwę zdarzenia.

marker.addListener('click', aFunction);
marker.addListener('click', bFunction);
marker.addListener('click', cFunction);

// Remove all click listeners from marker instance.
google.maps.event.clearListeners(marker, 'click');

Więcej informacji znajdziesz w dokumentacji referencyjnej dotyczącej przestrzeni nazw google.maps.event.

Wykrywaj błędy uwierzytelniania

Jeśli chcesz automatycznie wykrywać błąd uwierzytelniania (np. automatycznie wysyłać obraz typu beacon), możesz przygotować funkcję wywołania zwrotnego. Jeśli określona poniżej funkcja globalna jest zdefiniowana, zostanie ona wywołana w przypadku niepowodzenia uwierzytelniania. function gm_authFailure() { /* Code */ };