Google Mapplets 開發人員指南

Mapplet 是在 Google 地圖中執行的迷你應用程式。已經有很多開發人員用 Mapplet 在地圖上疊加各種資訊，例如相片、氣象狀況以及汽油價格。請參見 Google 地圖目錄，瞭解 Mapplet 及更多資訊。

Mapplet 才推出不久，如果使用時有任何問題和意見，請不吝和我們分享。我們也歡迎您加入地圖 API 討論群組，提出您的想法和回應。

目標讀者

本使用說明的目標讀者是熟悉 JavaScript 程式設計與物件導向程式設計概念的人。Mapplet 是特殊類型的小工具，因此您也可以參考小工具 API 使用說明。

我們最近重新整理了這篇使用說明，加入了詳細的概念資訊，並將討論群組區分為下列幾個重點：

• Mapplet 程式設計基礎
• Mapplet 事件
• Mapplet 疊加層
• Mapplet 服務

本文件將說明如何安裝和發佈 Mapplet，而 Mapplet 的「Hello World」則會說明撰寫 Mapplet 的方式，都請新進的開發人員務必閱讀。如果您已經熟悉「Google 地圖 API」，則可以跳至 Mapplet 與標準地圖 API 不同之處章節。此指南的假設是您對於小工具 API 或「Google 地圖 API」還不是那麼熟悉。

什麼是 Mapplet？

Mapplet 是包裝迷你網頁的 XML 檔案。您可以先將任何東西放入此迷你網頁，再將此迷你網頁放入一般網頁，包括 HTML、Javascript 以及 Flash。Google 提供一種 Javascript API，可以允許 Mapplet 與「Google 地圖」網站進行通訊、從遠端網站擷取內容以及儲存使用者喜好設定。

使用者執行您的 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 程式碼放在特殊的小工具中，和 maps.google.com 上的主要地圖通訊。在 Mapplet 基本資料的 Mapplet 的「Hello World」章節，會詳細告訴您如何寫出您的第一個 Mapplet。

發佈您的 Mapplet

您需要將自己的 Mapplet 儲存於公開網站。如果您沒有自己的網站，我們建議您試試 Google Page Creator。不過，請勿使用 WYSIWYG 編輯程式。請改用 [網站管理員]，並使用右邊的 [上載] 連結。然後按一下已上載內容部分中的檔案名稱，取得您 Mapplet 的網址。

安裝並執行您的 Mapplet

執行 Mapplet 之前，需要先安裝，請移至 Google 地圖目錄，並按一下頁面上方之 [搜尋 Google 地圖內容] 按鈕旁的 [新增網址] 連結。然後輸入您 Mapplet 的網址，並按一下 [新增] 按鈕。您返回 Google 地圖時，Mapplet 將會顯示在我的地圖標籤之下。

與其他人分享您的 Mapplet

使用下列網址，讓其他人執行您的 Mapplet：

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

使用者只要按一下此網址，就會導向另一個網頁，並提示他們安裝該 Mapplet。例如，如果您的 Mapplet 原始碼位於 http://www.google.com/mapfiles/mapplets/distance/distance.xml，您要提供的網址就是：

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

將您的 Mapplet 提交到目錄

如果您希望自己的 Mapplet 納入 Google 地圖目錄，請使用此提交表格。我們希望目錄裡能夠有各式各樣的高品質 Mapplet，不僅有用、而且有趣。雖然我們不可能照單全收，但一定會盡力收集。

Mapplet 與標準地圖 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()) 與「地圖 API」中的操作是相同的。然而，如果是從地圖取得傳回值的操作，就需要回呼函式。在 Mapplet 中，我們將 Async 附加至受此影響之所有「地圖 API」方法的名稱，而它們的傳回值會改以引數方式傳送給回呼函式。

例如，在「地圖 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。不過，地圖 (以及地圖上顯示的所有事項) 是主控於 maps.google.com 網域，因此在 Mapplet 要求我們顯示資訊視窗的時候，我們會先清理資訊視窗的內容，再交給地圖。資訊視窗中不得有 Javascript，只能有 HTML 標籤和 CSS 的允許清單。

此外，如果是新增新地圖控制項和地圖類型之類的操作，目前都需要第三方 Javascript 程式碼在地圖之中執行，因此我們現在還不允許。

遠端資料的要求是由 Google 進行 Proxy

Mapplet 是由 gmodules.com 提供服務，該網站位於 Google 管理的伺服器。瀏覽器的安全性模型不允許 gmodules.com 的 Javascript 向任何其他網域要求資料，因此您不能在 Mapplet 中使用 GDownloadUrl (或 GXml)，從您的伺服器擷取資料。

然而，小工具 API 可以提供下列呼叫，透過 gmodules.com 執行的 Proxy 來擷取內容：

• _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 呼叫會自動快取內容，以減少伺服器的負載。請參閱小工具 API 使用說明的重新整理快取章節，以取得變更快取期間或停用快取的詳細資訊。

如何將現有地圖 API 混搭轉換為 Mapplet

如果您已經有使用「Google 地圖 API」建置的網站，請參閱將地圖 API 混搭轉換為 Mapplet 的文章。

繼續前往 Mapplet 程式設計基本資料。