Anda sudah siap!

Untuk mulai mengembangkan, masuklah ke dokumentasi developer kami.

Aktifkan Google Maps JavaScript API

Untuk membantu Anda memulai, kami akan memandu Anda melalui Google Developers Console untuk melakukan beberapa hal terlebih dahulu:

  1. Buat atau pilih sebuah proyek
  2. Aktifkan Google Maps JavaScript API dan layanan terkait
  3. Buat kunci yang sesuai
Lanjutkan

Kejadian

Laman ini menjelaskan kejadian antarmuka pengguna dan kejadian kesalahan yang bisa Anda pantau dan tangani lewat program.

Kejadian Antarmuka Pengguna

JavaScript dalam browser digerakkan oleh kejadian, yang berarti bahwa JavaScript merespons interaksi dengan menghasilkan kejadian, dan mengharapkan program untuk memantau kejadian yang menarik. Ada dua tipe kejadian:

  • Kejadian pengguna (misalnya kejadian mouse "klik") disebarluaskan dari DOM ke Google Maps JavaScript API. Semua kejadian ini terpisah dan berbeda dari kejadian 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 kejadian yang telah dinamai. Program yang tertarik dengan kejadian tertentu akan mendaftarkan event listener JavaScript untuk kejadian tersebut dan mengeksekusi kode bila kejadian tersebut diterima dengan memanggil addListener() untuk mendaftarkan penangan kejadian pada objek.

Contoh di bawah akan menampilkan kepada Anda kejadian yang dipicu oleh google.maps.Map saat Anda berinteraksi dengan peta.

Untuk daftar lengkap kejadian, lihat Referensi Google Maps JavaScript API. Kejadian dicantumkan dalam bagian terpisah untuk setiap objek yang berisi kejadian.

Kejadian UI

Beberapa objek dalam Google Maps JavaScript API didesain untuk merespons kejadian pengguna seperti kejadian mouse atau keyboard. Misalnya, ini adalah beberapa kejadian pengguna yang bisa dipantau oleh objek google.maps.Marker:

  • 'click'
  • 'dblclick'
  • 'mouseup'
  • 'mousedown'
  • 'mouseover'
  • 'mouseout'

Untuk daftar lengkapnya, lihat kelas Marker. Kejadian ini mungkin terlihat seperti kejadian DOM standar, namun sebenarnya adalah bagian dari Maps JavaScript API. Karena browser yang berbeda mengimplementasikan model kejadian DOM yang berbeda, Maps JavaScript API menyediakan mekanisme ini untuk memantau dan merespons kejadian DOM tanpa perlu menangani beragam kekhasan lintas-browser. Kejadian ini juga biasanya meneruskan argumen dalam kejadian dengan memerhatikan beberapa status UI (seperti posisi mouse).

Perubahan Status MVC

Objek MVC biasanya berisi status. Setiap kali properti objek berubah, Google Maps JavaScript API akan memicu kejadian yang telah diubah properti. Misalnya, API akan memicu kejadian zoom_changed pada peta bila tingkat zoom peta tersebut berubah. Anda bisa mencegat perubahan status ini dengan memanggil addListener() untuk mendaftarkan penangan kejadian pada objek.

Kejadian pengguna dan perubahan status MVC mungkin tampak serupa, namun biasanya Anda ingin memperlakukannya secara berbeda dalam kode. Kejadian MVC, misalnya, tidak meneruskan argumen dalam kejadiannya. Anda nanti perlu memeriksa properti yang berubah saat perubahan status MVC dengan memanggil metode getProperty yang sesuai pada objek itu.

Menangani Kejadian

Untuk mendaftar notifikasi kejadian, gunakan event handler addListener(). Metode itu mengambil sebuah kejadian yang akan dipantau, dan sebuah fungsi yang akan dipanggil bila terjadi kejadian yang ditetapkan.

Contoh: Kejadian Peta dan Kejadian Marker

Kode berikut mencampur kejadian pengguna dengan kejadian perubahan status. Kami melekatkan sebuah event handler pada marker yang akan memperbesar peta bila diklik. Kami juga menambahkan event handler pada peta untuk perubahan pada properti center dan menggeser peta kembali ke marker setelah 3 detik sejak menerima kejadian center_changed:

function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}
<div id="map"></div>
/* 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;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var myLatlng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatlng
  });

  var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    title: 'Click to zoom'
  });

  map.addListener('center_changed', function() {
    // 3 seconds after the center of the map has changed, pan back to the
    // marker.
    window.setTimeout(function() {
      map.panTo(marker.getPosition());
    }, 3000);
  });

  marker.addListener('click', function() {
    map.setZoom(8);
    map.setCenter(marker.getPosition());
  });
}

Tampilkan contoh (event-simple.html)

Tip: Jika Anda mencoba mendeteksi perubahan di viewport, pastikan menggunakan kejadian bounds_changed spesifik daripada kejadian konstituen zoom_changed dan center_changed. Karena Maps JavaScript API memicu kejadian belakangan secara independen, getBounds() mungkin tidak melaporkan hasil yang berguna hingga tampilan yang terlihat secara otoritatif berubah. Jika Anda menginginkan getBounds() setelah kejadian seperti itu, pastikan memantau kejadian bounds_changed sebagai gantinya.

Contoh: Kejadian Pengeditan Bentuk dan Menyeret

Bila sebuah bentuk diedit atau diseret, sebuah kejadian akan dipicu setelah tindakan selesai. Untuk daftar kejadian dan beberapa cuplikan kode, lihat Bentuk.

Tampilkan contoh (rectangle-event.html)

Mengakses Argumen di Kejadian UI

Kejadian UI dalam Google Maps JavaScript API biasanya meneruskan argumen kejadian, yang bisa diakses oleh event listener, dengan memperhatikan status UI saat kejadian tersebut terjadi. Misalnya, kejadian UI 'click' biasanya meneruskan MouseEvent berisi properti latLng yang menunjukkan lokasi yang diklik pada peta. Perhatikan, perilaku ini unik untuk kejadian UI; perubahan status MVC tidak meneruskan argumen dalam kejadiannya.

Anda bisa mengakses argumen kejadian dalam event listener dengan cara yang sama seperti mengakses properti objek. Contoh berikut menambahkan event listener untuk peta, dan membuat marker bila pengguna mengeklik peta di lokasi yang diklik.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

function placeMarkerAndPanTo(latLng, map) {
  var marker = new google.maps.Marker({
    position: latLng,
    map: map
  });
  map.panTo(latLng);
}
<div id="map"></div>
/* 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;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  map.addListener('click', function(e) {
    placeMarkerAndPanTo(e.latLng, map);
  });
}

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

Tampilkan contoh (event-arguments.html)

Menggunakan Closures di Event Listener

Saat mengeksekusi event listener, sering kali akan menguntungkan bila melekatkan data pribadi dan data bertahan pada objek. JavaScript tidak mendukung data instance "private", namun mendukung closures yang memungkinkan fungsi bagian dalam untuk mengakses variabel luar. Closures berguna dalam event listener untuk mengakses variabel yang biasanya tidak melekat pada objek yang menjadi tempat kejadian berlangsung.

Contoh berikut menggunakan closure fungsi dalam event listener untuk memberikan pesan rahasia pada satu set marker. Mengeklik setiap marker akan mengungkapkan sebagian pesan rahasia tersebut, yang tidak ada dalam marker itu sendiri.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var 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.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var marker = new google.maps.Marker({
      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) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}
<div id="map"></div>
/* 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;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -25.363882, lng: 131.044922 }
  });

  var 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.
  var secretMessages = ['This', 'is', 'the', 'secret', 'message'];
  var lngSpan = bounds.east - bounds.west;
  var latSpan = bounds.north - bounds.south;
  for (var i = 0; i < secretMessages.length; ++i) {
    var marker = new google.maps.Marker({
      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) {
  var infowindow = new google.maps.InfoWindow({
    content: secretMessage
  });

  marker.addListener('click', function() {
    infowindow.open(marker.get('map'), marker);
  });
}

Tampilkan contoh (event-closure.html)

Mendapatkan dan Menyetel Properti dalam Event Handler

Tidak satu pun dari kejadian perubahan status MVC di sistem kejadian Google Maps JavaScript API yang meneruskan argumen bila kejadian ini terpicu. (Kejadian pengguna meneruskan argumen yang bisa diperiksa.) Jika Anda perlu memeriksa properti pada perubahan status MVC, Anda harus secara eksplisit memanggil metode getProperty() pada objek itu. Pemeriksaan ini akan selalu mengambil status saat ini dari objek MVC, yang mungkin bukanlah status saat kejadian itu pertama kali dipicu.

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

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

function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}
<div id="map"></div>
/* 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;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var originalMapCenter = new google.maps.LatLng(-25.363882, 131.044922);
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: originalMapCenter
  });

  var infowindow = new google.maps.InfoWindow({
    content: 'Change the zoom level',
    position: originalMapCenter
  });
  infowindow.open(map);

  map.addListener('zoom_changed', function() {
    infowindow.setContent('Zoom: ' + map.getZoom());
  });
}

Tampilkan contoh (event-properties.html)

Memantau kejadian DOM

Model kejadian Google Maps JavaScript API membuat dan mengelola sendiri kejadian khusus. Akan tetapi, DOM (Document Object Model) dalam browser juga membuat dan menugaskan kejadiannya sendiri, sesuai dengan model kejadian browser tertentu yang digunakan. Jika Anda ingin merekam dan merespons kejadian ini, Maps JavaScript API menyediakan metode statis addDomListener() untuk memantau dan mengikat ke kejadian DOM.

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

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

dalam hal ini instance bisa berupa elemen DOM didukung oleh browser, termasuk:

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

Perhatikan, addDomListener() hanya meneruskan kejadian yang ditunjukkan pada browser, yang menanganinya sesuai dengan model kejadian DOM browser; akan tetapi, hampir semua browser modern setidaknya mendukung DOM Level 2. (Untuk informasi selengkapnya tentang kejadian level DOM, lihat referensi Mozilla DOM Levels.)

Jika sudah membaca dokumentasi sejauh ini, Anda mungkin sudah paham dengan satu kejadian DOM: kejadian window.onload, yang telah kita tangani dalam tag <body>. Kita menggunakan kejadian ini untuk memicu kode JavaScript awal begitu laman HTML sepenuhnya dimuat, seperti yang ditampilkan di bawah ini:

<script>
  function initialize() {

    // Map initialization

  }
</script>
<body onload="initialize()">
  <div id="map"></div>
</body>

Meskipun kejadian ini melekat pada elemen <body> di sini, sebenarnya ini adalah kejadian window yang menunjukkan bahwa hierarki DOM di bawah elemen window telah sepenuhnya dibangun dan dirender.

Meskipun mudah dipahami, menempatkan kejadian onload dalam tag <body> akan mencampur materi dengan perilaku. Biasanya, praktik yang baik adalah memisah kode materi (HTML) dari kode perilaku (JavaScript) dan menyediakan kode presentasi (CSS) Anda secara terpisah. Anda bisa melakukannya dengan mengganti penangan kejadian onload inline dengan DOM listener dalam kode Maps JavaScript API, seperti:

<script>
  function initialize() {

    // Map initialization

  }

  google.maps.event.addDomListener(window, 'load', initialize);
</script>
<body>
  <div id="map"></div>
</body>

Tampilkan contoh (event-domListener.html)

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

Menghilangkan Event Listener

Untuk membuang event listener, maka harus diberikan dahulu ke sebuah variabel. Anda kemudian bisa memanggil removeListener(), dengan meneruskan nama variabel yang diberikan ke listener.

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

google.maps.event.removeListener(listener1);

Untuk membuang semua listener 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 membuang semua listener yang bertipe kejadian tertentu untuk instance spesifik, panggil clearListeners(), dengan meneruskan nama instance dan nama kejadian.

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 google.maps.event namespace.

Memantau kesalahan autentikasi

Jika Anda ingin mendeteksi kegagalan autentikasi lewat program (misalnya untuk mengirim suar secara otomatis) Anda bisa mempersiapkan fungsi callback. Jika fungsi global berikut telah didefinisikan, ia akan dipanggil bila autentikasi gagal. function gm_authFailure() { /* Code */ };

Kirim masukan tentang...

Google Maps JavaScript API
Google Maps JavaScript API
Butuh bantuan? Kunjungi halaman dukungan kami.