Wydarzenia

Wybierz platformę: Android iOS JavaScript

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

Zdarzenia interfejsu

JavaScript w przeglądarce jest sterowany zdarzeniami, co oznacza, że reaguje na interakcje, generując zdarzenia, i oczekuje, że program będzie nasłuchiwać interesujących zdarzeń. Istnieją 2 rodzaje zdarzeń:

  • Zdarzenia użytkownika (np. zdarzenia myszy „click”) są propagowane z DOM do interfejsu Maps JavaScript API. Te zdarzenia są oddzielne i różnią się od standardowych zdarzeń DOM.
  • Powiadomienia o zmianach stanu MVC odzwierciedlają zmiany w obiektach interfejsu Maps JavaScript API i są nazywane zgodnie z konwencją property_changed.

Każdy obiekt interfejsu Maps JavaScript API eksportuje kilka nazwanych zdarzeń. Programy zainteresowane określonymi zdarzeniami rejestrują dla nich detektory zdarzeń JavaScriptu i wykonują kod, gdy te zdarzenia są odbierane przez wywołanie addListener() w celu zarejestrowania modułów obsługi zdarzeń w obiekcie.

Poniższy przykład pokazuje, które zdarzenia są wywoływane przez google.maps.Map podczas interakcji z mapą.

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

Zdarzenia interfejsu

Niektóre obiekty w interfejsie Maps JavaScript API są zaprojektowane tak, aby reagować na zdarzenia użytkownika, takie jak zdarzenia myszy lub klawiatury. Oto przykłady 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 dokumentacji klasy 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 interfejs Maps JavaScript API udostępnia te mechanizmy, aby nasłuchiwać zdarzeń DOM i na nie reagować bez konieczności obsługiwania różnych specyficznych cech przeglądarek. Zdarzenia te zwykle przekazują też argumenty w ramach zdarzenia, które odnotowuje stan interfejsu (np. położenie myszy).

Zmiany stanu MVC

Obiekty MVC zwykle zawierają stan. Za każdym razem, gdy zmieni się właściwość obiektu, interfejs Maps JavaScript API wywoła zdarzenie informujące o tej zmianie. Na przykład interfejs API wywoła zdarzenie zoom_changed na mapie, gdy zmieni się poziom powiększenia mapy. Możesz przechwytywać te zmiany stanu, wywołując funkcję addListener(), aby zarejestrować w obiekcie procedury obsługi zdarzeń.

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

Obsługa zdarzeń

Aby zarejestrować powiadomienia o zdarzeniach, użyj modułu obsługi zdarzeń addListener(). Ta metoda przyjmuje zdarzenie, którego ma nasłuchiwać, oraz funkcję, która ma być wywoływana, gdy wystąpi określone zdarzenie.

Przykład: zdarzenia związane z mapą i znacznikiem

Poniższy kod łączy zdarzenia użytkownika ze zdarzeniami zmiany stanu. Ten przykład dołącza do znacznika moduł obsługi zdarzeń, który powiększa mapę po kliknięciu. Dołącza też do mapy procedurę obsługi zdarzeń, która reaguje na zmiany właściwości center i po 3 sekundach od otrzymania zdarzenia center_changed przesuwa mapę z powrotem do znacznika.

TypeScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps')) as google.maps.MapsLibrary;
    (await google.maps.importLibrary('marker')) as google.maps.MarkerLibrary;

    // Retrieve the map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map from the map element.
    const innerMap = mapElement.innerMap;

    const center = mapElement.center;

    const marker = new google.maps.marker.AdvancedMarkerElement({
        position: center,
        map: innerMap,
        title: 'Click to zoom',
        gmpClickable: true,
    });

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

    // Zoom in when the marker is clicked.
    marker.addListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(marker.position as google.maps.LatLng);
    });
}

initMap();
index.ts

JavaScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps'));
    (await google.maps.importLibrary('marker'));
    // Retrieve the map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map from the map element.
    const innerMap = mapElement.innerMap;
    const center = mapElement.center;
    const marker = new google.maps.marker.AdvancedMarkerElement({
        position: center,
        map: innerMap,
        title: 'Click to zoom',
        gmpClickable: true,
    });
    innerMap.addListener('center_changed', () => {
        // 3 seconds after the center of the map has changed,
        // pan back to the marker.
        window.setTimeout(() => {
            innerMap.panTo(marker.position);
        }, 3000);
    });
    // Zoom in when the marker is clicked.
    marker.addListener('gmp-click', () => {
        innerMap.setZoom(8);
        innerMap.setCenter(marker.position);
    });
}
initMap();
index.js
Zobacz przykład

Wypróbuj przykład

Wskazówka: jeśli chcesz wykryć zmianę w obszarze wyświetlania, użyj konkretnego zdarzenia bounds_changed, a nie zdarzeń składowych zoom_changed i center_changed. Ponieważ interfejs Maps JavaScript API wywołuje te zdarzenia niezależnie, getBounds() może nie podawać przydatnych wyników dopóki obszar widoku nie zostanie ostatecznie zmieniony. Jeśli po takim zdarzeniu chcesz getBounds(), zacznij nasłuchiwać zdarzenia bounds_changed.

Przykład: zdarzenia edycji kształtu i przeciągania

Gdy kształt jest edytowany lub przeciągany, po zakończeniu działania wywoływane jest zdarzenie. Listę zdarzeń i fragmenty kodu znajdziesz w sekcji Kształty.

Zobacz 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 może uzyskać dostęp detektor zdarzeń, aby określić stan interfejsu w momencie wystąpienia zdarzenia. Na przykład zdarzenie interfejsu 'click' zwykle przekazuje MouseEvent zawierający właściwość latLng, która oznacza klikniętą lokalizację na mapie. Pamiętaj, że to zachowanie dotyczy tylko zdarzeń interfejsu. Zmiany stanu MVC nie przekazują argumentów w zdarzeniach.

Do argumentów zdarzenia w detektorze zdarzeń możesz uzyskać dostęp w taki sam sposób, jak do właściwości obiektu. W tym przykładzie dodajemy detektor zdarzeń dla mapy i tworzymy znacznik, gdy użytkownik kliknie mapę w klikniętej lokalizacji.

TypeScript

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

  const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
  const innerMap = mapElement.innerMap;

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

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

JavaScript

async function initMap() {
    // Request needed libraries.
    await google.maps.importLibrary("maps");
    await google.maps.importLibrary("marker");
    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    innerMap.addListener("click", (e) => {
        placeMarkerAndPanTo(e.latLng, innerMap);
    });
}
function placeMarkerAndPanTo(latLng, map) {
    new google.maps.marker.AdvancedMarkerElement({
        position: latLng,
        map: map,
    });
    map.panTo(latLng);
}
initMap();
index.js
Zobacz przykład

Wypróbuj przykład

Używanie domknięć w detektorach zdarzeń

Podczas wykonywania detektora zdarzeń często korzystne jest dołączenie do obiektu zarówno danych prywatnych, jak i trwałych. JavaScript nie obsługuje „prywatnych” danych instancji, ale obsługuje domknięcia, które umożliwiają funkcjom wewnętrznym dostęp do zmiennych zewnętrznych. Domknięcia są przydatne w przypadku odbiorników zdarzeń, ponieważ umożliwiają dostęp do zmiennych, które zwykle nie są dołączane do obiektów, w których występują zdarzenia.

W przykładzie poniżej użyto zamknięcia funkcji w detektorze zdarzeń, aby przypisać tajną wiadomość do zestawu znaczników. Kliknięcie każdego znacznika spowoduje wyświetlenie części tajnej wiadomości, która nie znajduje się w samym znaczniku.

TypeScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps')) as google.maps.MapsLibrary;
    (await google.maps.importLibrary('marker')) as google.maps.MarkerLibrary;

    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;
    const innerMap = mapElement.innerMap;

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

        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('gmp-click', () => {
        infowindow.open(marker.map, marker);
    });
}

initMap();
index.ts

JavaScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('maps'));
    (await google.maps.importLibrary('marker'));
    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    const bounds = {
        north: -25.363882,
        south: -31.203405,
        east: 131.044922,
        west: 125.244141,
    };
    // Display the area between the location southWest and northEast.
    innerMap.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: innerMap,
        });
        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('gmp-click', () => {
        infowindow.open(marker.map, marker);
    });
}
initMap();
index.js
Zobacz przykład

Wypróbuj przykład

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

Żadne zdarzenie zmiany stanu MVC w systemie zdarzeń interfejsu Maps JavaScript API nie przekazuje argumentów po wywołaniu zdarzenia. (Zdarzenia użytkownika przekazują argumenty, które można sprawdzić). Jeśli chcesz sprawdzić właściwość podczas zmiany stanu MVC, musisz jawnie wywołać odpowiednią metodę getProperty() na tym obiekcie. To sprawdzenie zawsze pobiera bieżący stan obiektu MVC, który może nie być stanem, w jakim zdarzenie zostało wywołane po raz pierwszy.

Uwaga: jawne ustawienie właściwości w module obsługi zdarzeń, która reaguje na zmianę stanu tej konkretnej właściwości, może powodować nieprzewidywalne lub niepożądane zachowania. Ustawienie takiej właściwości spowoduje na przykład wywołanie nowego zdarzenia, a jeśli zawsze ustawiasz właściwość w tym module obsługi zdarzeń, możesz utworzyć nieskończoną pętlę.

Poniższy przykład pokazuje, jak skonfigurować procedurę obsługi zdarzeń, aby reagować na zdarzenia powiększenia, wyświetlając okno informacyjne z poziomem powiększenia.

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

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

Wypróbuj przykład

Usuwanie detektorów zdarzeń

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

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

google.maps.event.removeListener(listener1);

Aby usunąć wszystkich odbiorców z danej instancji, wywołaj metodę 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 dla konkretnego wystąpienia, wywołaj funkcję clearListeners(), przekazując nazwę wystąpienia 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 przestrzeni nazw google.maps.event.

Nasłuchiwanie błędów uwierzytelniania

Jeśli chcesz programowo wykrywać niepowodzenie uwierzytelniania (np. aby automatycznie wysyłać sygnał), możesz przygotować funkcję wywołania zwrotnego. Jeśli zdefiniowana jest poniższa funkcja globalna, zostanie ona wywołana, gdy uwierzytelnianie się nie powiedzie. function gm_authFailure() { /* Code */ };

W TypeScript może być konieczne dodanie funkcji do zakresu globalnego, jak pokazano poniżej:

// Define the callback function.
window.gm_authFailure = () => {
  console.error("Google Maps failed to authenticate.");
  /* Code */
};

// Add gm_authFailure to the global scope.
declare global {
  interface Window {
    gm_authFailure?: () => void;
  }
}
export {};