모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Maps JavaScript API 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Maps JavaScript API 및 관련 서비스 활성화
  3. 적합한 키 생성
계속

이벤트

이 페이지에서는 여러분이 프로그래밍 방식으로 수신하고 처리할 수 있는 사용자 인터페이스 이벤트와 오류 이벤트에 대해 설명합니다.

사용자 인터페이스 이벤트

브라우저 내의 JavaScript는 이벤트 구동 방식입니다. 즉, JavaScript가 이벤트를 생성하여 상호작용에 응답하고, 프로그램이 관련 이벤트를 수신할 것으로 예상합니다. 이벤트에는 두 가지 유형이 있습니다.

  • 사용자 이벤트(예: 마우스 "클릭" 이벤트)는 DOM에서 Google Maps JavaScript API로 전달됩니다. 이 이벤트는 표준 DOM 이벤트와 별개로 구분됩니다.
  • MVC 상태 변경 알림은 Maps JavaScript API 객체의 변경 사항을 반영하고 property_changed 규약에 따라 이름이 지정됩니다.

각 Maps JavaScript API 객체는 다양한 이름이 지정된 이벤트를 내보냅니다. 특정 이벤트와 관련된 프로그램은 해당 이벤트에 대한 JavaScript 이벤트 리스너를 등록하고, 해당 객체에서 이벤트 핸들러를 등록할 addListener()를 호출하여 해당 이벤트가 수신될 때 코드를 실행합니다.

아래 샘플은 지도와 상호작용할 때 google.maps.Map가 어떤 이벤트를 실행하는지 보여줍니다.

전체 이벤트 목록은 Google Maps JavaScript API 참조를 참조하세요. 이벤트는 이벤트를 포함하는 각 객체에 대한 별도 섹션에 나열되어 있습니다.

UI 이벤트

Google Maps JavaScript API 내의 일부 객체는 마우스나 키보드 이벤트 등의 사용자 이벤트에 응답하도록 설계되었습니다. 예를 들어, 다음은 google.maps.Marker 객체가 수신할 수 있는 몇 가지 사용자 이벤트입니다.

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

전체 목록은 마커 클래스를 참조하세요. 이러한 이벤트는 표준 DOM 이벤트처럼 보일지 모르지만 사실은 Maps JavaScript API의 일부입니다. 브라우저마다 다른 DOM 이벤트 모델을 구현하므로, Maps JavaScript API는 다양한 브라우저 간 특수성을 처리하지 않고도 DOM 이벤트를 수신하고 여기에 응답하는 메커니즘을 제공합니다. 또한, 이러한 이벤트는 대개 이벤트 내에서 몇 가지 UI 상태(예: 마우스 위치)를 나타내는 인수를 전달합니다.

MVC 상태 변경

MVC 객체는 대개 상태를 포함합니다. 객체의 속성이 변경될 때마다 Google Maps JavaScript API가 속성이 변경되었음을 알려주는 이벤트를 실행합니다. 예를 들어, API는 지도의 확대/축소 수준이 변경되면 지도에서 zoom_changed 이벤트를 실행합니다. 해당 객체에서 이벤트 핸들러를 등록할 addListener()를 호출하여 이러한 상태 변경을 막을 수 있습니다.

사용자 이벤트와 MVC 상태 변경은 비슷해 보이지만, 일반적으로 코드에서는 다르게 취급할 수 있습니다. 예를 들어, MVC 이벤트는 이벤트 안에서 인수를 전달하지 않습니다. 해당 객체에서 적절한 getProperty 메서드를 호출하여 MVC 상태 변경에서 변경된 속성을 검사할 수 있습니다.

이벤트 처리

이벤트 알림을 등록하려면 addListener() 이벤트 핸들러를 사용합니다. 이 메서드는 수신할 이벤트 그리고 지정된 이벤트가 발생했을 때 호출할 함수를 취합니다.

예시: 지도 및 마커 이벤트

다음 코드는 사용자 이벤트를 상태 변경 이벤트와 혼용합니다. 클릭했을 때 지도를 확대/축소하는 마커에 이벤트 핸들러를 연결합니다. 또한, center 속성이 변경되면 지도에 이벤트 핸들러를 추가하고, center_changed 이벤트를 수신하고 3초 후에 지도를 다시 마커로 패닝합니다.

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());
  });
}

예시 보기(event-simple.html).

: 뷰포트의 변경 사항을 알아내려면, 구성 요소인 zoom_changedcenter_changed 이벤트가 아니라 특정한 bounds_changed 이벤트를 사용합니다. Maps JavaScript API는 후자의 이벤트를 독립적으로 실행하므로, 뷰포트가 지시에 따라 변경된 후에 getBounds()가 유용한 결과를 보고하지 않을 수도 있습니다. 이러한 이벤트 이후 getBounds()를 원하면 대신 bounds_changed 이벤트를 수신하세요.

예시: 셰이프 수정 및 드래그 이벤트

셰이프가 수정되거나 드래그되면 그 동작이 완료되는 즉시 이벤트가 발생합니다. 이벤트 목록과 코드 스니펫은 셰이프를 참조하세요.

예시 보기(rectangle-event.html)

UI 이벤트에서 인수 액세스

Google Maps JavaScript API 내 UI 이벤트는 일반적으로 이벤트 인수를 전달합니다. 이 인수는 이벤트 리스너로 액세스할 수 있고 이벤트가 발생할 때 UI 상태를 알립니다. 예를 들어 UI 'click' 이벤트는 일반적으로 latLng 속성이 포함된 MouseEvent를 전달하고, 지도에서 클릭된 위치를 나타냅니다. 이 동작은 UI 이벤트에만 적용됩니다. MVC 상태 변경은 해당 이벤트에 인수를 전달하지 않습니다.

객체의 속성에 액세스하는 것과 동일한 방식으로, 이벤트 리스너 내에서 이벤트의 인수에 액세스할 수 있습니다. 다음 예시는 지도에 이벤트 리스너를 추가하고, 사용자가 지도를 클릭하면 클릭한 위치에 마커를 생성합니다.

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

예시 보기(event-arguments.html).

이벤트 리스너에서 클로저 사용

이벤트 리스너를 실행할 때 객체에 비공개 데이터와 영구 데이터를 모두 첨부하는 것이 유용한 경우가 많습니다. JavaScript는 "비공개" 인스턴스 데이터를 지원하지 않지만 내부 함수가 외부 변수에 액세스할 수 있는 클로저를 지원합니다. 클로저는 이벤트 리스너 내에서 평소에는 이벤트가 발생하는 객체에 연결되지 않는 변수에 액세스하는 데 유용합니다.

다음 예시는 이벤트 리스너의 함수 클로저를 사용하여 마커 집합에 비밀 메시지를 할당합니다. 각 마커를 클릭하면 마커 자체에는 포함되어 있지 않은 비밀 메시지가 표시됩니다.

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

예시 보기(event-closure.html).

이벤트 핸들러 내에서 속성 가져오기 및 설정

Google Maps JavaScript API 이벤트 시스템의 MVC 상태 변경 이벤트는 이벤트가 발생했을 때 인수를 전달하지 않습니다. (사용자 이벤트가 인수를 전달하고, 이를 검사할 수 있습니다.) MVC 상태 변경에서 속성을 검사하려면, 해당 객체에서 적절한 getProperty() 메서드를 명시적으로 호출해야 합니다. 이 검사는 항상 MVC 객체의 현재 상태를 검색하며, 이벤트가 최초로 발생했을 때의 상태가 아닐 수도 있습니다.

참고: 해당 특정 속성의 상태 변경에 응답하는 이벤트 핸들러 내에서 명시적으로 속성을 설정하면 예상치 못하거나 원치 않는 동작이 발생할 수 있습니다. 이러한 속성을 설정하면 새 이벤트가 발생합니다. 예를 들어, 항상 이 이벤트 핸들러 내에서 속성을 설정하면 무한 루프가 생성될 수도 있습니다.

아래 예시에서는 확대/축소 수준을 표시하는 정보 창을 나타내는 방식으로 확대/축소 이벤트에 응답하도록 이벤트 핸들러를 설정합니다.

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());
  });
}

예시 보기(event-properties.html).

DOM 이벤트 수신

Google Maps JavaScript API 이벤트 모델은 자체적인 사용자 지정 이벤트를 생성하고 관리합니다. 그러나 브라우저 내의 DOM(Document Object Model)도 사용 중인 특정 브라우저 이벤트 모델에 따라 자체 이벤트를 생성하고 전달합니다. 이 이벤트를 캡처하고 여기에 응답하고 싶다면, Maps JavaScript API가 DOM 이벤트를 수신하고 바인딩할 addDomListener() 정적 메서드를 제공합니다.

이 편의 메서드는 아래와 같은 서명이 있습니다.

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

여기서 instance는 다음을 포함하여 브라우저가 지원하는 모든 DOM 요소가 될 수 있습니다.

  • window 또는 document.body.myform과 같은 DOM의 계층적 멤버
  • document.getElementById("foo")와 같이 이름이 지정된 요소

참고로 addDomListener()는 지정된 이벤트를 브라우저에 전달할 뿐이며, 브라우저의 DOM 이벤트 모델에 따라 처리합니다. 하지만 거의 모든 최신 브라우저가 적어도 DOM 레벨 2를 지원합니다. (DOM 레벨 이벤트에 대한 자세한 내용은 Mozilla DOM 레벨 참조를 참조하세요.)

지금까지 이 문서를 읽었다면, 하나의 DOM 이벤트에 친숙해졌을 것입니다. 이는 window.onload 이벤트로, 우리는 <body> 태그 내에서 처리했습니다. 우리는 HTML 페이지가 완전히 로드되면 아래와 같이 이 이벤트를 사용하여 최초 JavaScript 코드를 실행합니다.

<script>
  function initialize() {

    // Map initialization

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

이 이벤트가 여기서는 <body> 요소에 첨부되지만, 사실 window 이벤트로, window 요소 아래의 DOM 계층이 완전히 빌드되거나 렌더링되었음을 나타냅니다.

이해하기는 쉽지만 <body> 태그 내에 onload 이벤트가 있으면 콘텐츠와 동작이 섞입니다. 일반적으로 콘텐츠 코드(HTML)와 동작 코드(JavaScript)를 분리하고, 프레젠테이션 코드(CSS)도 별도로 제공하는 것이 좋은 방법입니다. 그렇게 하려면 다음과 같이 Maps JavaScript API 코드 내에서 인라인 onload 이벤트 핸들러를 DOM 리스너로 대체합니다.

<script>
  function initialize() {

    // Map initialization

  }

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

예시 보기(event-domListener.html)

위 코드가 Maps JavaScript API 코드이기는 하지만, addDomListener() 메서드는 브라우저의 window 객체와 바인딩되고, API는 정규 도메인 외부의 객체와 통신할 수 있게 됩니다.

이벤트 리스너 제거

특정 이벤트 리스너를 제거하려면 리스너가 변수에 할당되어 있어야 합니다. removeListener()를 호출하고 리스너가 할당된 변수 이름을 전달합니다.

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

google.maps.event.removeListener(listener1);

특정 인스턴스에서 모든 리스너를 제거하려면 clearInstanceListeners()를 호출하고 인스턴스 이름을 전달합니다.

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

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

특정 인스턴스에 대한 특정 이벤트 유형에 대해 모든 리스너를 제거하려면 clearListeners()를 호출하고 인스턴스 이름과 이벤트 이름을 전달합니다.

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

자세한 내용은 google.maps.event namespace 참조 문서를 참조하세요.

인증 오류 수신

인증 실패를 프로그래밍 방식으로 감지하려면(예: 비콘을 자동으로 전송하려면) 콜백 함수를 준비할 수 있습니다. 다음과 같은 전역 함수가 정의된 경우, 인증이 실패할 때 이 함수가 호출됩니다. function gm_authFailure() { /* Code */ };

다음에 대한 의견 보내기...

Google Maps JavaScript API
Google Maps JavaScript API
도움이 필요하시나요? 지원 페이지를 방문하세요.