Google 地圖 API (Flash 版) 開發人員指南

全新的「Google 地圖 API (Flash 版)」讓您將互動式「Google 地圖」加入自己的網站，使用 Adobe's Flash® 外掛程式來顯示動態地圖內容！這個 API 是現有「JavaScript 地圖 API」完全獨立的替代方案，不僅保有大多數功能，還加入了將 Flash 內容與「Google 地圖」混合的能力。

「Google 地圖 API (Flash 版)」是新的產品，很需要您寶貴的意見。歡迎加入地圖 API (Flash 版) 討論群組，給予我們意見及回應。

目標讀者

本使用說明的目標讀者是熟悉 Flash、ActionScript® 程式設計以及物件導向程式設計概念的人。

本使用說明包含三個獨立的教學課程，涵蓋在其中一種可能的 Flash 開發環境中建立「Hello World」應用程式：

• Flex SDK 教學課程
• FlexBuilder® 教學課程
• Flash CS3 教學課程

如果是新手開發人員，請閱讀相關開發環境的適當教學課程，瞭解如何撰寫您的第一個「Google 地圖」Flash 應用程式。

此外，本使用說明也涵蓋下列主要範圍：

• Google 地圖 Flash 基本資料
• Google 地圖 Flash 事件
• Google 地圖 Flash 控制項
• Google 地圖 Flash 疊加層
• Google 地圖 Flash 服務

大部分的使用說明都著重於支援 Flex 開發人員。不過，我們會儘可能讓本使用說明對所有 Flash 開發人員都很有用。

簡介

「Google 地圖 API」有了 Flash 版本之後，Flash 開發人員就可以輕鬆地將「Google 地圖」整合進現有的 Flash 開發環境。同時，「Google 地圖 API (Flash 版)」開啟了全新局面，即使開發人員現在並未使用 Flash，也可以互動顯示和使用地圖內容。

本開發人員指南假設您已熟悉 Flash 開發和 ActionScript 程式設計。此外，雖然我們提供了不同開發環境的教學課程，但您並不需要使用任何特定的開發環境。

注意：本指南使用類似 UNIX 的命令列範例以及 Macintosh 螢幕擷取畫面，但其他開發人員的用法也大同小異。

設定開發環境

Flash 開發可接受很多格式。有些開發人員/設計人員作者只純粹使用 Flash CS3 應用程式來建立並安排內容，並在該架構中新增 ActionScript。其他開發人員則使用全功能的 IDE (例如 Adobe FlexBuilder®)，使用很多 ActionScript 來建立強大的應用程式。也有些開發人員使用 Adobe 提供的免費 Flex SDK®，並使用命令列來開發其應用程式。您可以自行決定使用哪一種開發環境。

本使用說明會涵蓋以上三種方式的教學課程，協助您順利進行。不過，本使用說明中的程式碼範例是以 MXML 檔案提供，可以在 FlexBuilder 或免費的 Flex SDK 中使用。直接在 Flash CS3 的那些檔案中、使用內嵌的 ActionScript 程式碼，非常直截了當。

「Google 地圖 API (Flash 版)」現在於 Flex 開發環境中直接支援 Adobe AIR® 應用程式。請查看在 FlexBuilder 中製作 AIR 應用程式的教學課程。

取得介面程式庫

如果要開發與「Google 地圖」整合的 Flash 內容，您的應用程式碼必須有「Google 地圖 API (Flash 版)」介面程式庫。這個程式庫是由「地圖 API (Flash 版) SDK」lib 目錄中的 *.swc 檔案組成，可於下列網址取得：

http://maps.googleapis.com/maps/flash/release/sdk.zip

本 SDK 包括兩個 SWC 檔案：一個 Flex 版本，供您在 FlexBuilder (或免費的 Flex SDK) 中使用；以及非 Flex 版本，供您在 Flash CS3 中使用。Flex *.swc 在檔名中會以 _flex 尾碼表示。

這些 SWC 檔案包含「Google 地圖 API (Flash 版)」開發環境中的所有公用類別介面。使用此程式庫編譯您的應用程式，可確保它可以利用執行階段「Google 地圖 API (Flash 版)」程式庫的所有公用功能，並與之溝通。每當用戶端載入您的應用程式時，就會從 Google 的伺服器抓取該程式庫。

請注意，實際執行「地圖」Flash 應用程式的大量程式碼，仍然位於個別的執行階段「Google 地圖 API (Flash 版)」程式庫中。這樣一來，即使我們加強功能、修正錯誤以及修改核心程式庫，您也不需要重新編譯應用程式。請注意，如果您想要使用的新功能需要新介面，就需要下載更新的 SWC 檔案，並重新編譯應用程式。

從介面程式庫檔名包含的尾碼，可看到其版本號碼。例如，map_flex_1_7.swc 表示是版本 1.7 的 Flex 介面程式庫，而 map_1_7.swc 表示是版本 1.7 的 Flash 介面程式庫。在您下載介面程式庫之後，請建立開發目錄，並將該檔案放在這個目錄的根目錄。

#
#Create a development directory
#
hostname$ mkdir myflashapp
hostname$ cd myflashapp
#
# Copy the Google Maps API for Flash SDK to the root of your working development directory
#
hostname$ cp ~/sdk.zip .
#
# Unzip the SDK. The SWC interface library is located within the "lib" directory
# Offline ASDoc HTML documentation is available within the "docs" directory
#
hostname$ unzip sdk.zip

請記住這個目錄位置。如果開發期間要連結到正確的 SWC 檔案，就需要此路徑。

取得地圖 API 金鑰

「Google 地圖 API (Flash 版)」與「Google JavaScript 地圖 API」類似，都需要使用免費的開發人員金鑰。您需要在下列三種位置之一指定此金鑰：

• (Flex 應用程式) 特殊的設定檔，稱為 MXML 宣告
• (Flash 應用程式) 您的 ActionScript 程式碼 (編譯成 SWF 檔)
• 您網頁中的包含 DOM 元素。

請注意，API 金鑰會編譯入 SWF 檔，而且必須符合主控 SWF 檔的網域 (這個不一定是主控 HTML 檔案的位置)。本說明文件集會顯示 Flex 範例，在 MXML 宣告中定義 API 金鑰。

版本設定

「Google 地圖 API (Flash 版)」介面程式庫包含 ActionScript 介面，允許您與實際的元件 (是由 Google 的執行階段程式庫所提供) 溝通。我們偶爾會自行更新這些元件。只要介面沒有變更，您就不需要做任何動作。該介面 SWC 檔將會自動取用最新的變更。

如果引進新功能和新特色 (因而需要更新介面)，我們也將需要更新介面 SWC 檔 (之後會提供下載)。這樣的版本將會根據版本架構來命名。(例如，與版本「1.3」關聯的介面程式庫將命名為「map_flex_1_3.swc」。您將需要下載這個介面程式庫的新版本，才能使用這些最新功能。請時常瀏覽「Google 地圖 API」網上論壇或網誌，以確保收到「Google 地圖 API (Flash 版)」的新版本通知。

如果將「地圖」的 version Property 設定為特定版本，可以將應用程式設定為只使用 Flash 程式庫的特定的「地圖 API」版本。但請注意，我們不建議您這樣做，因為這樣一來，您將無法享受到對於目前實作的任何改善或錯誤修正的好處。

教學課程

下列教學課程，將帶您使用「Google 地圖 API (Flash 版)」，在您喜好的開發環境中，逐步建立簡單的應用程式：

• Flex SDK 教學課程
• FlexBuilder 教學課程
• Flash CS3 教學課程

您不一定需要把三份教學課程都讀完。但如果能比較不同的開發程序，對您也應該會有一些幫助。