マプレットの基本

マプレットでの「Hello World」

Google マプレットの基本要素は、maps.google.com で公開されている地図そのものです。ここでは、基本的な GMap2 オブジェクトへの参照を取得する方法と、地図操作の基本について説明します。

マプレットはガジェット

マプレットは特殊なタイプのガジェットであるため、最初にガジェットの仕様について説明します。このガジェットの仕様はメタデータを含む XML の一種です。ユーザーに表示される HTML は <Content> タグ内にあります。このタグ内には、通常の Web ページに配置できるすべての要素を配置できます。

次の例では、左側のパネルに「Hello World!」と表示します。

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Hello World" 
             description="Displays a Hello World message in the left panel"
             author="Your name"
             author_email="your-email@gmail.com"
             height="150">
</ModulePrefs>
<Content type="html"><![CDATA[

<h2>Hello World!</h2>

]]></Content>
</Module>

この例を実行する (hello-gadget.xml)

マプレットもよく似ていますが、Mapplet JavaScript コードと、ガジェットをマプレットとして指定する追加の XML データを含んでいます。次の例では、ワールド ビューにズームアウトして、「Hello World!」吹き出し付きのマーカーを地図に追加します。

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="The Hello World of Mapplets" 
             description="Displays a Hello World message on the map!"
             author="Your name"
             author_email="your-email@gmail.com"
             height="150">
  <Require feature="sharedmap"/>
</ModulePrefs>
<Content type="html"><![CDATA[

<h2>Hello World!</h2>

<script>
  // Center the map in the Mediterranean and zoom out to a world view
  var map = new GMap2();
  var point = new GLatLng(37.71859, 6.679688);
  map.setCenter(point, 2);

  // Add a marker to the center of the map
  var marker = new GMarker(point);
  map.addOverlay(marker);

  // Open a "Hello World" info window
  var message = "Hello World!";
  marker.openInfoWindowHtml(message);
</script>

]]></Content>
</Module>

この例を実行する (map-simple.xml)

簡単な例ですが、次の 3 点にご注意ください。

1. マプレットに <Require feature="sharedmap"/> を含めます。
2. "map" オブジェクトへの参照を作成するために JavaScript を記述します。
3. 地図の中央に指定された地点を表示します。

これらの手順を以下で説明します。

Google Mapplets API の読み込み

<Require feature="sharedmap"/>

<Require feature="sharedmap"/> を <ModulePrefs> タグ内に追加すると、ガジェットはマップとの通信を可能にするマプレット JavaScript API のロードを開始します。<Content> タグ内には、この API に指示するための JavaScript コードを追加します。

GMap2 - 基本オブジェクト

地図を表す JavaScript Mapplets クラスは GMap2 クラスです。JavaScript の new 演算子を使用して、このクラスの新しいインスタンスを作成します。マプレットは、このオブジェクトを使用してメイン地図への参照を自動的に取得します。

var map = new GMap2();
var point = new GLatLng(37.71859, 6.679688);
map.setCenter(point, 2);

このコードでは map という名前の変数を定義し、その変数を新しい GMap2 オブジェクトに割り当てます。関数 GMap2() を「コンストラクタ」と呼びます。その定義 (Google Mapplets API リファレンスから抜粋) を以下に示します。

コンストラクタ	説明
GMap2()	メイン地図へのハンドルを返します。

地図への参照を取得したら、地図の setCenter() メソッドを呼び出します。setCenter() メソッドには、GLatLng の座標とズーム レベルが必要です。この位置決めはマプレットでは不要ですが、Google Maps API では地図を適切に初期化するために必要です。マプレットでは、初期化済みの地図が既にあります。

基本的なマップ操作

マプレットを作成してマプレット コードを初期化する方法を理解したら、次に、地図上の位置を参照して基本的な操作を実行する方法を理解する必要があります。ここでは、Mapplets API を使用して地図上で基本的な操作を実行する方法を説明します。

緯度と経度

GLatLng オブジェクトはマプレット内の位置を参照するための方法を提供します。GLatLng オブジェクトを構築して、そのパラメータを { 緯度, 経度 } の順序で渡します。

  var myGeographicCoordinates = new GLatLng(myLatitude, myLongitude)

注: 「住所」を地理的位置に変換する処理を「ジオコーディング」と呼びます。Mapplets API サービスのセクションで詳しく説明しています。住所を地理的座標に変換する処理の詳細については、このセクションを参照してください。

このオブジェクトは、簡単に地理的位置を参照するために役立つだけでなく、オブジェクトの地理的な境界を定義するためにも役立ちます。たとえば、地図はビューポートと呼ばれる範囲内に世界全体の現在の「ウィンドウ」を表示します。このビューポートは、その四角形の角の地点によって定義できます。GLatLngBounds オブジェクトは、境界ボックスの南西と北東の角を表す 2 つの GLatLng オブジェクトを使用して四角形の範囲を定義することで、この機能を提供します。

GLatLng オブジェクトは、Google Maps API においてさまざまな用途があります。たとえば、GMarker オブジェクトはそのコンストラクタ内で GLatLng を取り、地図上の指定された地理的位置にマーカー 「オーバーレイ」を配置します。

次の例では、getBounds() を使用して現在のビューポートを返し、その後でそれらの境界内の地図上にランダムに 10 個のマーカーを配置します。

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

  // Add 10 markers to the map at random locations
  var bounds = map.getBoundsAsync(function(bounds) {
    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 < 10; i++) {
      var point = new GLatLng(southWest.lat() + latSpan * Math.random(),
        southWest.lng() + lngSpan * Math.random());
      map.addOverlay(new GMarker(point));
    }
  });

この例を実行する (map-markers.xml)

注: GMarker オブジェクトの詳細については、「オーバーレイ」のセクションを参照してください。

地図の属性

デフォルトでは、地図は標準の「塗りつぶされた」タイルを使用して Google Maps API 内に表示されます。ただし、Google Maps API では他のマップ タイプもサポートされています。標準のマップ タイプは次のとおりです。

• G_NORMAL_MAP - デフォルト ビュー
• G_SATELLITE_MAP - Google Earth の航空写真を表示
• G_HYBRID_MAP - 通常のビューと航空写真の混合表示
• G_DEFAULT_MAP_TYPES - これらの 3 タイプすべて。反復処理に役立ちます

GMap2 オブジェクトの setMapType() メソッドを使用してマップ タイプを設定できます。たとえば、次のコードでは Google Earth の航空写真を使用するように地図を設定します。

  var map = new GMap2();
  map.setMapType(G_SATELLITE_MAP);

地図には、確認目的に役立ついくつかの属性もあります。たとえば、現在のビューポートの範囲を知るには、GMap2 オブジェクトの getBounds() メソッドを使用して GLatLngBounds の値を返します。

各地図には現在のビューの解像度を定義する「ズーム レベル」もあります。通常のマップ ビュー内では、0 (最も低いズーム レベルで、1 つの地図で世界全体を表示可能) ～ 19 (最も高いズーム レベルで、個々の建物まで表示可能) のズーム レベルが使用可能です。地球上の地域によって地理データの詳細度が異なるため、ズーム レベルは表示している地域に応じて異なります。航空写真では最高でレベル 20 までのズーム レベルが使用できます。

地図で使用している現在のズーム レベルを取得するには、GMap2 オブジェクトの getZoomAsync() メソッドを使用します。

地図の操作

マプレットは能動的でなければなりません。ユーザーは地図を操作したいと思っています。GMap2 オブジェクトは、地図の状態をプログラムを通じて変更するいくつかのメソッドをサポートしています。たとえば setCenter() メソッド、panTo() メソッド、および zoomIn() メソッドは、ユーザーによる操作ではなくプログラムによって地図を操作します。

次の例ではカリフォルニア州のパロアルトにジャンプし、2 秒停止してから新しい中心地点へ移動します。panTo メソッドは、指定した地点を地図の中央に表示します。指定された地点が地図の表示範囲 (「ビューポート」) 内にあった場合、地図は滑らかにその地点まで移動しますが、表示範囲外にあった場合は地図はその地点にジャンプします。

var map = new GMap2();
map.setCenter(new GLatLng(37.4419, -122.1419), 13);
window.setTimeout(function() {
  map.panTo(new GLatLng(37.4569, -122.1569));
}, 2000);

この例を実行する (map-animation.xml)

情報ウィンドウを開く

Google Maps API 内の各地図は、1 つの「情報ウィンドウ」を表示できます。このウィンドウは、地図上のフローティング ウィンドウとして HTML コンテンツを表示します。情報ウィンドウは漫画の吹き出しに似ています。内容の部分と先が細くなった部分からなり、その先端が地図上の指定位置を指します。Google マップでマーカーをクリックすると、実際の情報ウィンドウを表示できます。

GMap2() コンストラクタを使用して地図への参照を作成すると、情報ウィンドウは自動的に地図に添付されます。特定の 1 つの地図に対して同時に複数の情報ウィンドウを表示することはできませんが、情報ウィンドウを移動して、必要に応じてその内容を変更することができます。

GMap2 オブジェクトでは、引数に地点と HTML DOM 要素を取る openInfoWindow() メソッドを使用することができます。HTML DOM 要素は情報ウィンドウのコンテナに挿入され、情報ウィンドウのヒントは指定された地点に固定されます。

情報ウィンドウを開くには、openInfoWindow メソッドを呼び出して、表示する位置と DOM 要素をこのメソッドに渡します。次のサンプルコードでは、地図の中心に固定された情報ウィンドウに「Hello, World」という簡単なメッセージを表示します。

var map = new GMap2();
map.getCenterAsync(function(center) {
  map.openInfoWindowHtml(center, "Hello World");
});

この例を実行する (infowindow.xml)

マプレット イベント モデルに続きます。