Google Maps JavaScript API V2 のイベント

注: Google Maps JavaScript API バージョン 2 は、2010 年 5 月 19 日に正式にサポートが終了しました。この V2 API は Google のサポート終了ポリシーに従って引き続き機能しますが、コードを Maps JavaScript API バージョン 3 に移行することをおすすめします。

マップ イベントの概要

ブラウザ内の JavaScript はイベント駆動型で、JavaScript はイベントの生成によってインタラクションに応答し、プログラムが対象のイベントをリッスンすることを予期します。たとえば、ブラウザ内でユーザーがマウスやキーボードを操作すると、DOM 内に伝播するイベントが生成されます。特定のイベントを監視しているプログラムは、それらのイベントの JavaScript イベント リスナを登録して、これらのイベントが受信されたときにコードを実行します。

Google Maps API は、Maps API オブジェクトのカスタム イベントを定義することで、このイベント モデルを増強します。Maps API イベントは、標準の DOM イベントとは異なる個別のイベントである点に注意してください。ただし、ブラウザごとに異なる DOM イベント モデルが実装されますが、Maps API でも、さまざまなブラウザ固有の性質に対処しなくても、これらの DOM イベントをリッスンしたり応答したりできる機能を備えています。

イベント リスナ

Google Maps API 内のイベントは、GEvent 名前空間内のユーティリティ関数を使用してイベント リスナを登録することで処理されます。各 Maps API オブジェクトは、いくつかの名前付きイベントをエクスポートします。たとえば GMap2 オブジェクトは、click、dblclick、move のイベントと、その他のホストをエクスポートします。イベントは特定のコンテキストで発生し、そのコンテキストを識別する引数を渡すことができます。たとえば mousemove イベントは、ユーザーがマップ オブジェクト内でマウスを動かしたときに発生し、マウスが配置されている地理的位置の GLatLng を渡します。

GMap2 イベントとこれらが生成する引数の全リストについては、GMap2.イベントを参照してください。

これらのイベントの通知を登録するには、静的メソッド GEvent.addListener() を使用してください。このメソッドは、オブジェクト、リッスン対象のイベント、指定されたイベントの発生時に呼び出す関数を受け取ります。たとえば次のコード スニペットは、ユーザーが地図上でクリックするたびにアラートを表示します:

var map = new GMap2(document.getElementById("map"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
GEvent.addListener(map, "click", function() {
  alert("You clicked the map.");
});

例を表示（event-simple.html）

イベント リスナでクロージャを使用する

イベント リスナを実行するときは、オブジェクトにプライベート データと永続データの両方をアタッチすることが一般に有効です。JavaScript は「プライベート」のインスタンスはサポートしていませんが、クロージャはサポートしています。これにより、内部関数から外部の変数にアクセスすることができます。イベント リスナ内でクロージャを使用すると、イベントが発生したオブジェクトには通常アタッチされていない変数にアクセスできるので便利です。

次の例では、イベント リスナ内で関数クロージャを使用して、一連のマーカーに秘密のメッセージを割り当てています。各マーカーをクリックすると、そのマーカーそのものには含まれていない秘密のメッセージの一部が表示されます。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

// Creates a marker at the given point
// The five markers show a secret message when clicked
// but that message is not within the marker's instance data

function createMarker(point, number) {
  var marker = new GMarker(point);
  var message = ["This","is","the","secret","message"];
  marker.value = number;
  GEvent.addListener(marker, "click", function() {
    var myHtml = "<b>#" + number + "</b><br/>" + message[number -1];
    map.openInfoWindowHtml(point, myHtml);
  });
  return marker;
}

// Add 5 markers to the map at random locations
var bounds = map.getBounds();
var southWest = bounds.getSouthWest();
var northEast = bounds.getNorthEast();
var lngSpan = northEast.lng() - southWest.lng();
var latSpan = northEast.lat() - southWest.lat();
for (var i = 0; i < 5; i++) {
  var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
    southWest.lng() + lngSpan * Math.random());
  map.addOverlay(createMarker(point, i + 1));
}

例を表示（event-closure.html）

渡された引数をイベントで使用する

Maps API イベント システム内の多くのイベントは、そのイベントがトリガされたときに引数を渡します。たとえば GMap2 「クリック」イベントはオーバーレイ上で地図がクリックされたとき overlay と overlaylatlng を渡しますが、そうでないときは地図座標の latlng を渡します。これらの引数にアクセスするには、指定された記号をイベント リスナ内の関数に直接渡します。

下記の例では、まず latlng 引数が定義されているかどうかチェックして、クリックがマップ タイル上で行われたことを確認します。次にクリックされた座標の上に情報ウィンドウを開き、ピクセル空間に変換された座標とズーム レベルを表示します。

var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

GEvent.addListener(map,"click", function(overlay, latlng) {     
  if (latlng) { 
    var myHtml = "The GPoint value is: " + map.fromLatLngToDivPixel(latlng) + " at zoom level " + map.getZoom();
    map.openInfoWindow(latlng, myHtml);
  }
});
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());

例を表示（event-arguments.html）

イベントをオブジェクトにバインドする

イベントは通常、イベントを受け取るオブジェクト内で直接動作します。たとえば、'click' イベント リスナを GMap2 オブジェクトにアタッチした場合、通常は、イベント リスナのアタッチされた関数内で、マップそれ自体のメソッドを呼び出します。

この動作は、コード内のオブジェクトへの参照を this に置き換えればテストできます。イベント リスナが、イベントを受信するオブジェクト上で動作している場合には、this とオブジェクトへの参照の動作はどちらも同じです。

# The following event listeners are equivalent:

# Access the map using the 'map' symbol
var map = new GMap2(document.getElementById("map"));
GEvent.addListener(map, "moveend", function() {
  var center = map.getCenter();
  document.getElementById("message").innerHTML = center.toString();
});

# Access the map using the 'this' keyword
var map = new GMap2(document.getElementById("map"));
GEvent.addListener(map, "moveend", function() {
  var center = this.getCenter();
  document.getElementById("message").innerHTML = center.toString();
});

そうではなく、イベントへのレスポンスで別のオブジェクトのメソッドを呼び出す場合には、GEvent.bind() を使用して、メソッドをイベントを受信するオブジェクト以外のオブジェクトにバインドすることができます。

次の例では、イベント リスナはマップの 'click' イベントを Counter オブジェクトのインスタンスにバインドし、そのオブジェクト内で定義されたメソッドを呼び出しています:

function initialize() {
  if (GBrowserIsCompatible()) {
    var map = new GMap2(document.getElementById("map_canvas"));
    var myCounter = new Counter();
    map.setCenter(new GLatLng(37.4419, -122.1419), 13);
    GEvent.bind(map, "click", myCounter, myCounter.increment);
  }
}
    
function Counter() {
  this.counter = 0;
}
    
Counter.prototype.increment = function() {
  this.counter++;
  alert("You have clicked the map " + this.counter +
        (this.counter == 1 ?" time":" times"));
}

例を表示（event-bind.html）

DOM イベントをリッスンする

Google Maps API イベント モデルは、独自のカスタム イベントを作成して管理します。ただし DOM も、使用されている特定のブラウザ イベント モデルに従って独自のイベントを作成して送出します。これらのイベントを取得して応答する必要がある場合は、Google Maps API が提供するブラウザに依存しないラッパーを使用することで、カスタム コードを使用せずに DOM イベントをリッスンしてバインドできます。

GEvent.addDomListener() 静的メソッドは、DOM ノード上の DOM イベントのイベント ハンドラを登録します。同様に GEvent.bindDom() 静的メソッドを使用すると、クラス インスタンス上の DOM イベントのイベント ハンドラを登録できます。

イベント リスナを削除する

不要になったイベント リスナは削除する必要があります。リッスン対象のイベントが一度しか発生しない場合でも、削除が必要になることがあります。クロージャ内の名前のない関数を介して定義されたイベント リスナは、削除するのが難しい場合があります。ただし、addListener()、addDomListener()、bind()、bindDom() の各関数は、最終的にハンドラの登録を解除するために使用できる GEventListener ハンドルを返します。

次の例では、クリックに応じて地図上にマーカーを配置します。その後で再びクリックされるとイベント リスナが削除されます。removeOverlay() コードは結果として一度も実行されません。また、イベント リスナ自体からもそのイベント リスナを削除できる点にも注目してください。

function MyApplication() {
  this.counter = 0;
  this.map = new GMap2(document.getElementById("map"));
  this.map.setCenter(new GLatLng(37.4419, -122.1419), 13);
  var myEventListener = GEvent.bind(this.map, "click", this, function(overlay, latlng) {
    if (this.counter == 0) {
      if (latlng) {
        this.map.addOverlay(new GMarker(latlng))
        this.counter++;
      } else if (overlay instanceof GMarker) {
        this.removeOverlay(marker)
      }
    } else {
      GEvent.removeListener(myEventListener);
    }
  }); 
}

function load() {
  var application = new MyApplication();
}

例を表示（event-removal.html）