Google Mapplet 开发人员指南

Mapplet 是在 Google 地图中运行的迷你应用程序。许多开发人员已经创建了在地图上叠加相片、天气情况和汽油价格之类信息的 Mapplet。您可以在 Google 地图目录中找到这些 Mapplet，甚至更多。

Mapplet 是一项新功能，所以如果您在使用时发现任何问题，我们很乐意倾听您的反馈。我们鼓励您加入 Google 地图 API 讨论组，给我们留下反馈意见。

读者

本文档设计用于熟悉 JavaScript 编程和面向对象编程概念的人。Mapplet 是一种特殊类型的小工具，因此您也可以查阅小工具 API 文档。

我们最近重新组织了本文档，添加了更多概念性的信息，并将讨论内容划分为以下主要领域：

• Mapplet 编程基础知识
• Mapplet 事件
• Mapplet 叠加层
• Mapplet 服务

所有的新开发人员都应该阅读两个文档，其中本文档解释了怎样安装和发布 Mapplet，另一个文档 Mapplet 的“Hello World”解释了怎样编写 Mapplet。如果您已经对 Google 地图 API 有一定的了解，那么您可能要看看关于“Mapplet 与标准 Google 地图 API 有什么不同”部分。本指南假设您对小工具 API 或 Google 地图 API 并不了解。

什么是 Mapplet？

Mapplet 是一个封装有迷你网页的 XML 文件。您可以在此迷你网页中放入任何可以放入正常网页的东西，包括 HTML、Javascript 和 Flash。Google 提供了让 Mapplet 与 Google 地图站点进行通信，从远程网站中抓取内容并存储用户偏好的 Javascript API。

当用户运行您的 Mapplet 时，Google 将从您的网络服务器上抓取 Mapplet 源代码，然后在 Google 地图站点的 IFrame 中提供该迷你网页。出于安全原因，迷你网页托管在 gmodules.com。

为减少贵站点的负载，gmodules.com 会将 Mapplet 源代码缓存几小时。绕过缓存处理唯一的方法是安装开发人员 Mapplet。

重要的开发人员工具

开始编写 Mapplet 前，应先转至 Google 地图目录的开发人员工具部分，并添加以下工具：

• 开发人员 Mapplet：安装此工具后，“重新加载”链接会添加到您运行的每个 Mapplet 中。这就允许您绕过 Mapplet 源代码的自动缓存。请相信我们，如果不安装开发人员 Mapplet，您很快就会在使用中备感受挫。
• Mapplet Scratch Pad：此工具可以让您交互式编写 Mapplet 代码并立即进行预览。您可以将此指南中的所有示例复制粘贴到 Scratch Pad 上。

编写您的 Mapplet

正确设置了您的开发环境后，下一步要做的就是编写 mapplet 了。Mapplet 就是放置在某个特定的小工具内的 JavaScript 代码，从而实现与 ditu.google.cn 上的主地图进行通信。编写首个 Mapplet 的详细解说位于 Mapplet 基础知识的 Mapplet 的“Hello World”部分。

发布您的 Mapplet

您需要在公开网站上保存您的 Mapplet。如果您还没有自己的网站，我们建议您试一试 Google Page Creator。但是，请不要使用所见即所得编辑器。而要转至站点管理器，并使用右边的上传链接。然后点击上传的资料部分的文件名，获取您 Mapplet 的网址。

安装并运行您的 Mapplet

在运行 Mapplet 前，您需要转至 Google 地图目录，并点击页面顶端搜索 Google 地图内容按钮旁的按网址添加链接进行安装。然后输入您 Mapplet 的网址并点击添加按钮。当您返回 Google 地图时，Mapplet 将显示在我的地图标签下。

与他人共享您的 Mapplet

使用下面的网址可以让他人运行您的 Mapplet：

http://ditu.google.cn/ig/add?synd=mpl&pid=mpl&moduleurl=< URL of your mapplet>

点击此网址的用户将会转到提示他们安装 Mapplet 的页面。例如，如果您 Mapplet 的源代码位于 http://www.google.cn/mapfiles/mapplets/distance/distance.xml，那么您将共享下面的网址：

http://ditu.google.cn/ig/add?synd=mpl&pid=mpl&moduleurl=http://www.google.cn/mapfiles/mapplets/distance/distance.xml

将您的 Mapplet 提交到目录

如果想让您的 Mapplet 包含在 Google Mapplet 目录中，那么请使用此提交表单。我们的目标是通过目录为用户提供既实用又具娱乐性的高质量 Mapplet。虽然我们无法包含所有提交的内容，但是我们会在目录中包含尽可能多的内容。

Mapplet 与标准 Google 地图 API 有什么不同

处理地图的 API 调用衍生自标准 Google 地图 API，其中大多数都是相同的。但是，应该注意以下细微的差别。

初始化更简单

<Require feature="sharedmap"/>自动为您初始化 API，这样您就无须手动加载 Javascript 库或传入 API 密钥。您不用传递 <div> 到 GMap2 构造函数，原因是构造函数总会返回主地图的引用。

如果有用户加载了您的 Mapplet，那么您可以安心地认为它们使用的是与 Google 地图兼容的浏览器，所以 GBrowserIsCompatible 检查是不必要的，在 Mapplet 中也不受支持。

在 Google 地图 API 中，我们必须通过使用 setCenter() 方法将地图定位来对其进行“初始化”。因为我们已经有了适合的已初始化地图，所以 Mapplet 中无需此定位步骤。

我们不允许不规范的行为

我们不允许 Mapplet 更改 Google 地图的标准行为，所以我们删除了禁用拖动、双击缩放等方法。

与地图的通信是异步的

Mapplet 和 Google 地图站点之间的通信是异步的。所以，一些方法与它们的标准 Google 地图 API 版本中的表现方法不同。修改地图的操作大部分（例如，setCenter()、addOverlay()）与在 Google 地图 API 上执行的操作相同。但是，从地图获取返回值的操作需要回调函数。在 Mapplet 中，我们将 Async 附加到所有受此条限制影响的 Google 地图 API 方法的名称上，其返回值会作为参数传递给回调函数。

例如，在 Google 地图 API 中，有人编写：

var zoom = map.getZoom();
alert("Current zoom level is " + zoom);
alert("This happens after you see the zoom level message");

但在 Mapplet 中，必须编写为：

map.getZoomAsync(function(zoom) {
  alert("Current zoom level is " + zoom);
});  
alert("This might happen before or after you see the zoom level message");

通常，您可能需要一次执行若干异步请求。不同于连续执行这些请求或将它们彼此相互嵌套，Mapplet 提供了一个 GAsync() 实用工具函数，可在单次调用中执行若干请求。要使用 GAsync()，需要将一个对象传递给它，该对象后面跟着要调用的方法，用引号引起来，并以回调函数作为最后的参数：

GAsync(map, 'getZoom', 'getCenter', function(zoom,center) {
  // code here
}

要对一个以上的对象执行请求，请传递另一个对象，后面紧跟着方法，用引号引起来：

GAsync(map, 'getZoom', 'getCenter', marker, 'getPoint',
  function(zoom,center,point) {
  // code here
}

安全问题和信息窗口过滤设施

Mapplet 在托管在 gmodules.com 上的 iframe 中运行，所以它无法存取 Google 用户的 cookie，也不会破坏 Google 地图站点上的 Javascript。但是，地图（及上面显示的所有内容）都托管在 ditu.google.cn 域中，所以当 Mapplet 请求显示信息窗口时，我们会在将其提交给地图前过滤信息窗口中的内容。我们不允许信息窗口中有 Javascript 存在，我们仅允许 HTML 标签和 CSS 的白名单。

此外，添加新地图控件和地图类型等操作目前需要在地图中执行第三方 Javascript 代码，所以我们目前禁止这些操作。

远程数据的请求由 Google 代理

Mapplet 由 gmodules.com 提供服务，后者位于由 Google 运行的服务器上。浏览器的安全模型并不允许 gmodules.com 上的 Javascript 从其他任何域请求数据，因此您不能使用自己的 Mapplet 内的 GDownloadUrl（和 GXml）从服务器抓取数据。

而且，小工具 API 提供以下调用，将通过在 gmodules.com 上运行代理程序来抓取内容：

• _IG_FetchContent(url, callback) -- 将url中的内容以文本形式返回。使用此功能来抓取必须解析的 XML 内容。
• _IG_FetchXmlContent(url, callback) -- 将url中的 XML 内容作为 DOM 对象返回并对其进行操作。使用此功能来抓取必须解析的 XML 内容。

这些方法在以下方面与 GDownloadUrl 和 GXml 表现不同：

• _IG_FetchContent 和 _IG_FetchXmlContent 调用可以从互联网上的任何网站抓取数据。
• _IG_FetchXmlContent 比 GXml 更严格，而且要求 XML 文件以 <?xml version="1.0" encoding="UTF-8"?> 开头。
• _IG_FetchContent 和 _IG_FetchXmlContent 调用会自动缓存内容以减少服务器的负载。请参阅小工具 API 文档的刷新缓存部分以获取关于怎样更改缓存持续时间或禁用缓存的信息。

怎样将现有的 Google 地图 API 混搭转换为 Mapplet

如果您已经有使用 Google 地图 API 构建的现有站点，请参阅有关将 Google 地图 API 混搭转换为 Mapplet的文章。

继续转到 Mapplet 编程基础知识。