Mapplet 基础知识

Mapplet 的“Hello World”

任何 Google Mapplet 中的基本元素都是地图本身，当然也就是 ditu.google.cn 上托管的地图。本部分讨论怎样获得对基础 GMap2 对象的引用以及基本地图操作。

Mapplet 是种小工具

Mapplet 是一种特殊类型的小工具，所以我们先从编写小工具规范开始，规范只是一些含元数据的 XML。向用户显示的 HTML 位于 <Content> 标签中，您可以在其中存入任何可以存入常规网页的内容。

下面的示例将在左侧面板中显示“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 看起来很相似，但却包含 Mapplet Javascript 代码和一些将小工具指定为 mapplet 的额外 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)

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

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

下面说明了这些步骤。

加载 Google Mapplet API

<Require feature="sharedmap"/>

在 <ModulePrefs> 标签内添加 <Require feature="sharedmap"/> 将指引小工具载入可以让其与地图进行通信的 Mapplet Javascript API。在 <Content> 标签内，我们随后添加一些与此 API 对话的 Javascript 代码。

GMap2 - 基本对象

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

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

此代码可定义变量（名为 map），并将该变量分配给新 GMap2 对象。函数 GMap2() 称为“构造函数”，其定义（来自 Google Mapplet API 参考）如下所示：

构造函数	说明
GMap2()	返回主地图的句柄。

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

基本地图操作

既然我们知道了怎样创建 mapplet 和初始化 mapplet 代码，我们还需要一种方法来引用地图上的位置和执行基本操作。本部分讲述怎样使用 Mapplet API 对地图执行基本操作。

经度和纬度

在 Mapplet 中，GLatLng 对象提供了一种引用地点的方式。可以构造一个 GLatLng 对象，以 {经度, 纬度} 的顺序传递其参数：

  var myGeographicCoordinates = new GLatLng(myLatitude, myLongitude)

注意：将“地址”转变为地理点的过程称为“地址解析”，将在“Mapplet API 服务”部分中详细讨论。请查阅该部分，以获取有关将地址转换为地理坐标的详细信息。

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

GLatLng 对象在 Google 地图 API 中用途广泛。例如，GMarker 对象在其构造函数中具有 GLatLng，并在地图上的指定地理位置放置标记“叠加层”。

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

  var map = new GMap2();
  map.setCenter(new GLatLng(39.9493, 116.3975), 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 地图 API 中，地图使用标准的“绘制”图块显示。但是，Google 地图 API 也支持其他地图类型。以下是标准地图类型：

• G_NORMAL_MAP- 默认视图
• G_SATELLITE_MAP - 显示 Google 地球卫星图像
• G_HYBRID_MAP - 混合显示普通视图和卫星视图
• G_DEFAULT_MAP_TYPES - 这三个类型的数组，在需要重复处理的情况下非常有用

可以使用 GMap2 对象的 setMapType() 方法设置地图类型。例如，下面的代码将地图设置为使用 Google 地球的卫星视图：

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

地图还包含对了解情况非常有用的大量属性。例如，要了解当前视口的尺寸，可使用 GMap2 对象的 getBounds() 方法来返回 GLatLngBounds 值。

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

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

地图交互

Mapplet 不应只是被动的，您会想要与地图进行交互。GMap2 对象支持通过编程方式改变地图状态的许多方法。例如，setCenter()、panTo() 和 zoomIn() 方法对地图进行操作，而不是通过用户交互的方式进行操作。

下面的示例跳到了北京的故宫博物院，等待两秒钟，然后平移到新中心点。panTo 方法将地图中心设置在指定点处。如果指定点位于地图的可见部分，（称为“视口”），则地图会平稳地平移到该点，否则会跳至该点。

var map = new GMap2();
map.setCenter(new GLatLng(39.9493, 116.3975), 13);
window.setTimeout(function() {
  map.panTo(new GLatLng(39.927, 116.407));
}, 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 事件模型。