Google Mapplets 开发指南

Mapplets 是在 Google 地图中运行的迷你应用程序。许多开发者已经创建了在地图上标注有相片、天气情况和汽油价格之类信息的 Mapplets。您可以在 Google Maps 目录（英文）和 Google 地图目录中找到这些 Mapplets，甚至更多。

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

读者

本文档设计用于熟悉 JavaScript 编程和面向对象编程概念的人。 Mapplets 是一种特殊的“Google Gadget”，所以您也应该查询 Google Gadgets API 文档。

本文档的讨论主题主要分为如下几个主要领域：

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

所有的新开发者都应该阅读这两个文档，其中一个解释了怎样安装和发布 Mapplets，另一个文档 Mapplets 的“Hello World”解释了怎样编写该程序。如果您已经对 Google 地图 API 有一定的了解，那么您可能会对 Mapplets 与标准地图 API 有什么不同中的章节感兴趣。此指南不是在假定您已熟悉 Google Gadgets API 或 Google 地图 API 的基础上编写的。

什么是 Mapplets？

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

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

为减少您站点的负载，gmodules.com 会将 Mapplet 源代码缓存几小时。绕过缓存唯一的方法是安装 Developer Mapplet。

重要的开发工具

开始编写 Mapplet 前，应先添加以下开发工具：

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

编写您的 Mapplet

一旦正确设置了您的开发环境，下一步要做的就是编写 mapplet 自身了。Mapplet 就是放置在为与 ditu.google.com 上的主地图建立通讯而设计的特殊的 “GoogleGadget” 中的一些 JavaScript 代码。编写首个 Mapplet 的详细练习工作包含在 Mapplet 基础的Mapplets 的 “Hello World” 部分中。

发布您的 Mapplet

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

安装并运行您的 Mapplet

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

与他人共享您的 Mapplet

使用下面的 URL 使他人可运行您的 Mapplet：

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

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

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

Mapplets 与标准地图 API 有什么不同

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

更简单的初始化

<Require feature="sharedmap"/> 自动为您初始化 API，这样您就不用手动装载 Javascript 库或传入 API 密匙。不可将 <div> 传递到 GMap2 构造函数中，因为它总是将引用返回到主地图。

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

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

禁止非标准的地图操作

我们不允许 Mapplets 更改 Google 地图的标准行为，所以我们移除了禁止双击缩放等方法。

与地图的通讯是异步的

Mapplet 和 Google 地图站点之间的通讯是异步的。所以，一些方法与它们的标准 Google 地图 API 版本中的方法不同。在很大程度上，修改地图的操作（例如，setCenter()，addOverlay()）与地图 API 中的操作是相同的。但是，从地图获取返回值的操作需要回调函数。在 Mapplets 中，我们将 Async 追加到所有受它影响的地图 API 方法的名称上，其返回值作为参数传递给回调函数。

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

var zoom = map.getZoom();
alert("当前缩放级别为 " + zoom);
alert("这在您看到缩放级别消息后发生");

不管在 Mapplet 中的任何位置，这都必须编写为：

map.getZoomAsync(function(zoom) {
alert("当前缩放级别为 " + zoom);
});  
alert("这可能在您看到缩放级别消息之前或之后发生");

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

GAsync(map, 'getZoom', 'getCenter', function(zoom,center) {
//这里是代码
}

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

GAsync(map, 'getZoom', 'getCenter', marker, 'getPoint',
  function(zoom,center,point) {
//这里是代码
}

安全问题和信息窗口内容过滤机制

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

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

远程数据请求由 Google 代理

Mapplets 由 gmodules.com 提供，它是由 Google 运行的服务器。浏览器安全模型不允许 gmodules.com 上的 Javascript 从其他域请求数据，所以您不能在您的 Mapplet 中使用 GDownloadUrl（或 GXml）从您的服务器获取数据。

不过 Google Gadgets API 提供以下调用，它通过 gmodules.com 上运行的代理获取内容：

• _IG_FetchContent(url, callback) -- 以文本形式返回 url 对应的内容。 使用此函数获取 HTML 或纯文本内容。
• _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 调用自动缓存内容，以减少您服务器上的负载。请参阅 Gadgets API 文档的刷新缓存部分，来了解关于更改缓存期限或禁用缓存的信息。

如何将现有的地图 API 应用转换为 Mapplet

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

继续 Mapplet 编程基础。