Mapplet 基础

Mapplets 的“Hello World”

任何 Google Mapplet 的基本元素都是地图本身，当然也就是 ditu.google.com 上存储的地图。本节讨论如何获得对 GMap2 基础对象的引用和地图的基本操作。

Mapplet 是一种 Gadget

Mapplet 是一种特殊类型的 Google Gadget，所以我们先从写 Gadget说明开始。它只是一种带有元数据的 XML，显示在用户面前的 HTML 位于 <Content> 标签中 — 您可以在其中放入任何可以放入常规网页的东西。

下面的示例将在左侧面板中显示“Hello World!”。

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Hello World" 
             description="在左侧面板中显示 Hello World 消息!"
             author="您的姓名"
             author_email="your-email@gmail.com"
             height="150">
</ModulePrefs>
<Content type="html"><![CDATA[

<h2>Hello World!</h2>

]]></Content>
</Module>

运行该示例 (hello-gadget.xml)

Mapplet 看起来很相似，但却包含 Mapplets Javascript 代码和一些将 gadget 指定为 mapplet 的额外 XML 数据。下面的示例缩小了地图视图，并用“Hello World!”信息窗口向地图添加了一个标记。

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Mapplets 的 Hello World" 
             description="在地图上显示 Hello World 消息！"
             author="您的姓名"
             author_email="your-email@gmail.com"
             height="150">
  <Require feature="sharedmap"/>
</ModulePrefs>
<Content type="html"><![CDATA[

<h2>Hello World!</h2>

<script>
  // 将地图中心定位于北京
  var map = new GMap2();
  var point = new GLatLng(39.92, 116.46);
  map.setCenter(point, 4);

  // 在地图中心添加一个标记
  var marker = new GMarker(point);
  map.addOverlay(marker);

  // 打开一个 "Hello World" 信息窗口
  var message = "Hello World!";
  marker.openInfoWindowHtml(message);
</script>

]]></Content>
</Module>

运行该示例 (map-simple.xml)

即使在此简单的示例中，也需要注意三点：

1. Mapplet 中包含<Require feature="sharedmap"/>。
2. 编写了一些 JavaScript 来创建对 "map" 对象的引用。
3. 将地图中的中心设置为给定的地理点。

下面说明了这些步骤。

加载 Google Mapplets API

<Require feature="sharedmap"/>

在<ModulePrefs>标签内添加 <Require feature="sharedmap"/> 可指示 gadget 加载允许它与地图通讯的 Mapplets Javascript API。在 <Content> 标签内，我们随后添加一些与 API 通讯的 Javascript 代码。

GMap2 - 基本对象

表示地图的 JavaScript Mapplets 类是 GMap2 类。我们使用 JavaScript new 操作符创建此类的一个新实例。Mapplet 将自动获得对使用该对象的主地图的引用。

var map = new GMap2();
var point = new GLatLng(39.92, 116.46);
map.setCenter(point, 4);

此代码定义一个变量（名为 map），并将该变量分配给新的 GMap2 对象。函数 GMap2() 称为构造函数 ，其定义（在 Google Mapplets API 参考中）如下所示：

构造函数	描述
GMap2()	将句柄返回给主地图。

注意，一旦我们获得了对地图的引用，随后就调用地图的 setCenter() 方法。setCenter() 方法需要 GLatLng 坐标和缩放级别。注意在 Mapplets 中不需要初始定位操作，尽管在 Google 地图 API 中需要该定位操作来正确初始化地图。在 Mapplets 中，我们已经有了已初始化的地图。

基本地图操作

既然现在我们知道了如何创建 mapplet 和初始化 mapplet 代码，还需要一种方式在地图上引用地点和执行基本操作。本节讲述如何使用 Mapplets API 在地图上执行基本操作。

经纬度

在 Mapplet 中，GLatLng 对象提供了一种引用地点的方式。可以构造一个 GLatLng 对象，以（纬度，经度）的顺序输入参数：

  var myGeographicCoordinates = new GLatLng(myLatitude, myLongitude)

注：将地址转换为地理点的过程称为地址解析（Geocoding），会在 Mapplets API 服务一节中详细讨论。请查阅该章节获取有关将地址转换为地理坐标的详细信息。

就象它可用于轻松地引用地理点一样，它也可用于定义对象的地理边界。例如，地图会有一个显示整个世界的当前“窗口”，称为视图。此视图可以通过四个角的点定义。GLatLngBounds 对象提供此功能，使用分别表示边界框的西南角和东北角的两个 GLatLng 对象定义一个矩形区域。

GLatLng 对象在 Google 地图 API 中有许多用途。例如，GMarker 对象在其构造函数中取 GLatLng，并在地图上给定的地理位置叠加一个叠加层。

以下示例使用 getBounds() 返回当前视图，然后在地图上这些边界内随机放置 10 个标记：

  var map = new GMap2();
  map.setCenter(new GLatLng(39.917, 116.397), 14);

  //在随机位置向地图中添加 10 个标记
  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 地图 API 中，地图会使用“绘制”的标准图块显示，类型如下：

• G_NORMAL_MAP- 默认视图

地图还包含用于获取各种状态信息的大量属性。例如，要了解当前视图的尺寸，请使用 GMap2 对象的 getBounds() 方法返回 GLatLngBounds 值。

每个地图还包含一个缩放级别，它定义当前视图的分辨率。普通地图视图中，可以使用 0（最低缩放级别，在一个地图上可以看到整个世界）和 19（最高缩放级别，可以看到每个建筑物）之间的缩放级别。缩放级别因所查看地区而异，因为地图上某些地区的数据比其它地区更详细。

可以通过使用 GMap2 对象的 getZoomAsync() 方法检索地图中正在使用的缩放级别。

地图交互

Mapplets 不应是被动的：您需要与地图进行交互。GMap2 对象支持通过程序改变地图状态的大量方法。例如，setCenter()、panTo() 和 zoomIn() 方法可对地图进行操作，而不通过用户交互。

以下示例跳到北京的故宫博物院，等两秒，然后滑移到新的中心点。panTo 方法将地图的中心设置在给定点。如果指定点在地图的可见部分（称为视图），则地图会平稳地滑移到该点，否则地图会跳到该点。

var map = new GMap2();
map.setCenter(new GLatLng(39.917, 116.397), 14);
window.setTimeout(function() {
  map.panTo(new GLatLng(39.932, 116.412));
}, 2000);

运行该示例 (map-animation.xml)

打开一个信息窗口

Google 地图 API 中的每个地图可以显示单个“信息窗口”，它在地图上方的浮动窗口中显示 HTML 内容。信息窗口的外观有点象漫画书上表示人谈话的气球状标识符；它有一个内容区域和锥形的箭头，箭头指向地图上的指定点。可以通过单击 Google 地图上的标记而看到活动的信息窗口。

当使用 GMap2() 构造函数创建对地图的引用时，会有一个信息窗口自动与地图关联。对给定的地图，一次不能显示多个信息窗口，但可以移动信息窗口并更改其内容（如果需要）。

GMap2 对象提供了一个 openInfoWindow() 方法，它取一个点和一个 HTML DOM 元素作为参数。HTML DOM 元素插入信息窗口容器中，信息窗口的头固定在给定点上。

要打开信息窗口，请调用 openInfoWindow 方法，并向它传递要显示的位置和 DOM 元素。以下示例代码显示固定到地图中心并显示简单的“Hello, world”消息的信息窗口。

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

运行该示例 (infowindow.xml)

继续 Mapplet 事件模型。