Acara

Pilih platform: Android iOS JavaScript

Halaman ini menjelaskan peristiwa antarmuka pengguna dan peristiwa error yang bisa Anda proses dan tangani secara terprogram.

Peristiwa Antarmuka Pengguna

JavaScript dalam browser didorong oleh peristiwa, yang berarti bahwa JavaScript merespons interaksi dengan menghasilkan peristiwa, dan mengharapkan program untuk memproses peristiwa yang menarik. Ada dua jenis peristiwa:

  • Peristiwa pengguna (seperti peristiwa mouse "klik") disebarkan dari DOM ke Maps JavaScript API. Semua peristiwa ini terpisah dan berbeda dari peristiwa DOM standar.
  • Notifikasi perubahan status MVC mencerminkan perubahan dalam objek Maps JavaScript API dan diberi nama menggunakan ketentuan property_changed.

Setiap objek Maps JavaScript API mengekspor sejumlah peristiwa yang telah diberi nama. Program yang tertarik dengan peristiwa tertentu akan mendaftarkan pemroses peristiwa JavaScript untuk peristiwa tersebut dan mengeksekusi kode jika peristiwa tersebut diterima dengan memanggil addListener() untuk mendaftarkan pengendali peristiwa pada objek.

Contoh berikut akan menunjukkan peristiwa mana yang dipicu oleh google.maps.Map saat Anda berinteraksi dengan peta.

Untuk mengetahui daftar lengkap peristiwa, lihat Referensi Maps JavaScript API. Peristiwa dicantumkan dalam bagian terpisah untuk setiap objek yang berisi peristiwa.

Peristiwa UI

Beberapa objek dalam Maps JavaScript API dirancang untuk merespons peristiwa pengguna seperti peristiwa mouse atau keyboard. Berikut beberapa contoh peristiwa pengguna yang dapat dipantau oleh objek google.maps.marker.AdvancedMarkerElement:

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

Untuk daftar lengkapnya, lihat class AdvancedMarkerElement. Peristiwa ini mungkin terlihat seperti peristiwa DOM standar, tetapi sebenarnya merupakan bagian dari Maps JavaScript API. Karena browser yang berbeda mengimplementasikan model peristiwa DOM yang berbeda, Maps JavaScript API akan menyediakan mekanisme ini untuk memantau dan merespons peristiwa DOM tanpa perlu menangani beragam kekhasan lintas-browser. Peristiwa ini juga biasanya meneruskan argumen dalam peristiwa dengan memperhatikan beberapa status UI (seperti posisi mouse).

Perubahan Status MVC

Objek MVC biasanya berisi status. Setiap kali properti objek berubah, Maps JavaScript API akan memicu peristiwa yang telah diubah oleh properti. Misalnya, API akan memicu peristiwa zoom_changed pada peta jika tingkat zoom peta berubah. Anda dapat mencegat perubahan status ini dengan memanggil addListener() untuk mendaftarkan pengendali peristiwa pada objek tersebut juga.

Peristiwa pengguna dan perubahan status MVC mungkin tampak serupa, tetapi biasanya Anda ingin menanganinya secara berbeda dalam kode. Peristiwa MVC, misalnya, tidak meneruskan argumen dalam peristiwanya. Sebaiknya Anda memeriksa properti yang berubah saat perubahan status MVC dengan memanggil metode getProperty yang sesuai pada objek tersebut.

Menangani Peristiwa

Untuk mendaftar notifikasi peristiwa, gunakan pengendali peristiwa addListener(). Metode itu mengambil sebuah peristiwa yang akan dipantau, dan sebuah fungsi yang akan dipanggil jika terjadi peristiwa yang ditentukan.

Contoh: Peristiwa Peta dan Penanda

Kode berikut mencampur peristiwa pengguna dengan peristiwa perubahan status. Kami melekatkan sebuah pengendali peristiwa pada penanda yang akan memperbesar peta jika diklik. Kami juga menambahkan pengendali peristiwa ke peta untuk perubahan di properti center dan menggeser peta kembali ke penanda 3 detik setelah menerima peristiwa center_changed:

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

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
Lihat contoh

Mencoba Contoh

Tips: Jika Anda mencoba mendeteksi perubahan di area pandang, pastikan menggunakan peristiwa bounds_changed spesifik, buka peristiwa zoom_changed dan center_changed konstituen. Karena Maps JavaScript API memicu peristiwa terakhir ini secara independen, getBounds() mungkin tidak melaporkan hasil yang berguna hingga area pandang berubah secara otoritatif. Jika Anda menginginkan getBounds() setelah peristiwa tersebut, pastikan untuk memantau peristiwa bounds_changed.

Contoh: Peristiwa Penarikan dan Pengeditan Bentuk

Saat sebuah bentuk diedit atau ditarik, sebuah peristiwa akan dipicu setelah tindakan selesai. Untuk daftar peristiwa dan beberapa cuplikan kode, lihat Bentuk.

Lihat contoh (rectangle-event.html)

Mengakses Argumen di Peristiwa UI

Peristiwa UI dalam Maps JavaScript API biasanya meneruskan argumen peristiwa, yang dapat diakses oleh pemroses peristiwa, dengan memperhatikan status UI saat peristiwa tersebut terjadi. Misalnya, peristiwa 'click' UI biasanya meneruskan MouseEvent yang berisi properti latLng yang menunjukkan lokasi yang diklik pada peta. Perhatikan, perilaku ini unik untuk peristiwa UI; perubahan status MVC tidak meneruskan argumen dalam peristiwanya.

Anda bisa mengakses argumen peristiwa dalam pemroses peristiwa dengan cara yang sama seperti mengakses properti objek. Contoh berikut menambahkan pemroses peristiwa untuk peta, dan membuat penanda jika pengguna mengklik peta di lokasi yang diklik.

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

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
Lihat contoh

Mencoba Contoh

Menggunakan Closure di Pemroses Peristiwa

Saat mengeksekusi pemroses peristiwa, sering kali akan menguntungkan jika Anda melekatkan data pribadi dan data persisten ke objek. JavaScript tidak mendukung data instance "pribadi", tetapi mendukung closures yang memungkinkan fungsi internal untuk mengakses variabel luar. Closures berguna dalam pemroses peristiwa untuk mengakses variabel yang biasanya tidak melekat pada objek tempat peristiwa terjadi.

Contoh berikut menggunakan closure fungsi dalam pemroses peristiwa untuk memberikan pesan rahasia pada satu set penanda. Mengklik setiap penanda akan mengungkapkan sebagian pesan rahasia tersebut, yang tidak ada dalam penanda itu sendiri.

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

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
Lihat contoh

Mencoba Contoh

Mendapatkan dan Menetapkan Properti dalam Pengendali Peristiwa

Tidak satu pun dari peristiwa perubahan status MVC di sistem peristiwa Maps JavaScript API yang meneruskan argumen jika peristiwa ini terpicu. (Peristiwa pengguna meneruskan argumen yang bisa diperiksa.) Jika Anda perlu memeriksa properti pada perubahan status MVC, Anda harus secara eksplisit memanggil metode getProperty() yang sesuai pada objek tersebut. Pemeriksaan ini akan selalu mengambil status saat ini dari objek MVC, yang mungkin bukan merupakan status saat peristiwa pertama kali dipicu.

Catatan: Menetapkan properti secara eksplisit dalam sebuah pengendali peristiwa yang merespons perubahan status properti tertentu mungkin menghasilkan perilaku yang tidak terduga dan/atau tidak diinginkan. Menetapkan properti tersebut akan memicu peristiwa baru, misalnya, dan jika selalu menetapkan properti dalam pengendali peristiwa ini, Anda mungkin akhirnya akan menciptakan loop tak terhingga.

Dalam contoh di bawah ini, kita menyiapkan sebuah pengendali peristiwa untuk merespons peristiwa zoom dengan memunculkan jendela info yang menampilkan tingkatan tersebut.

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
Lihat contoh

Mencoba Contoh

Memproses Peristiwa DOM

Model peristiwa Maps JavaScript API membuat dan mengelola peristiwa kustomnya sendiri. Namun, DOM (Document Object Model) dalam browser juga membuat dan menugaskan peristiwanya sendiri, sesuai dengan model peristiwa browser tertentu yang digunakan. Jika Anda ingin mencatat dan merespons peristiwa ini, Maps JavaScript API menyediakan metode statis addDomListener() untuk memantau dan mengikat peristiwa DOM.

Metode praktis ini memiliki tanda tangan seperti yang ditampilkan di bawah ini:

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

dengan instance dapat berupa elemen DOM apa pun yang didukung oleh browser, termasuk:

  • Anggota hierarki DOM seperti window atau document.body.myform
  • Elemen yang telah diberi nama seperti document.getElementById("foo")

Perhatikan bahwa addDomListener() meneruskan peristiwa yang ditunjukkan ke browser, yang menanganinya sesuai dengan model peristiwa DOM browser. Namun, hampir semua browser modern setidaknya mendukung DOM Level 2. (Untuk informasi selengkapnya tentang peristiwa level DOM, lihat referensi Mozilla DOM Levels.)

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

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

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
Lihat contoh

Mencoba Contoh

Meskipun jika kode di atas adalah kode Maps JavaScript API, metode addDomListener() akan diikat ke objek window browser dan memungkinkan API ini berkomunikasi dengan objek di luar domain normal API.

Menghapus Pemroses Peristiwa

Pemroses peristiwa tertentu harus ditetapkan ke sebuah variabel terlebih dahulu agar dapat dihapus. Anda kemudian dapat memanggil removeListener(), dengan meneruskan nama variabel yang diberikan ke pemroses.

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

google.maps.event.removeListener(listener1);

Untuk menghapus semua pemroses dari instance tertentu, panggil clearInstanceListeners() dengan meneruskan nama instance.

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

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

Untuk menghapus semua pemroses yang berjenis peristiwa tertentu untuk instance spesifik, panggil clearListeners(), dengan meneruskan nama instance dan nama peristiwa.

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

Untuk informasi selengkapnya, lihat dokumentasi referensi untuk namespace google.maps.event.

Memantau error autentikasi

Jika Anda ingin secara terprogram mendeteksi kegagalan autentikasi (misalnya untuk mengirim beacon secara otomatis), Anda bisa mempersiapkan fungsi callback. Jika sudah ditentukan, fungsi global berikut akan dipanggil ketika autentikasi gagal. function gm_authFailure() { /* Code */ };