Google Maps API（Flash 版）- Flex SDK 教程

设置开发环境

本教程介绍了怎样获得和设置 Adobe Flex SDK、怎样设置开发环境以及怎样在 ActionScript 中编程以建立第一个 Google Maps API（Flash 版）地图。

注意：如果您想要使用 FlexBuilder IDE，请参见 FlexBuilder 教程。

获得并安装 Adobe Flex SDK

要将 Google 地图合并到 Flex 应用程序中，不仅需要了解 ActionScript 代码，还需要了解 Flex MXML 文件。本文档中的示例使用可从以下网址免费获得的 Adobe Flex 3 SDK：

http://www.adobe.com/products/flex/overview/#section-3

注意：Flex SDK 需要 Java 1.4 或 1.5（具体取决于开发平台）。可从以下网址获得使用 Flex SDK 进行开发的完整要求：

http://www.adobe.com/products/flex/systemreqs/

下载 SDK 后，将其解压缩到一个工作目录并确保可以从命令行执行 MXML 编译程序 (mxmlc)。mxmlc 编译程序位于 Flex SDK 的 bin 目录中。使用 -help 选项执行该编译程序会导致输出以下内容。

hostname$ cd flex_sdk/bin
hostname$ ./mxmlc -help
Adobe Flex Compiler (mxmlc)
Version 3.0.0 build 477
Copyright (c) 2004-2007 Adobe Systems, Inc. All rights reserved.
...

您可能还需要将 flex_sdk/bin 目录添加到您的 $PATH，以便可以从任意目录执行该编译程序。

获得 Debug Flash Player

在进行开发前，您应当首先安装一个调试版的 Adobe Flash Player。可从以下网址获得播放器的调试版本：

http://www.adobe.com/support/flashplayer/downloads.html

您可能需要卸载所有非调试版的 Flash 播放器并且/或者关闭您的浏览器，才能成功安装调试版本。

设置开发目录

新！Google Maps API（Flash 版）现在提供对 Flex 内的 com.google.maps.Map 对象的本地支持。您不再需要扩展 Map 类来定义您的地图应用程序类，并且您可以在 Flex 中直接使用地图组件。

Flex 应用程序在 MXML 声明中定义。通常，您应在源代码目录的根目录中提供这些 MXML 文件。

# Google recommends that you create a "source" directory in the root of your 
# Application development directory
# "Source" MXML application definitions will go here:
hostname$ cd myflashapp
hostname$ mkdir src

使用命名空间管理扩展名

用于“扩展”任何现有的 Google Maps API（Flash 版）组件的组件通常都应作为唯一命名空间内的 ActionScript 库提供。Google 建议您使用您拥有的命名空间以防止与其他库发生冲突；如果您想让许多开发人员同时在多个 Flash 组件上工作，这一点尤其重要。使用命名空间还可让您将库代码捆绑成“包”，这样可以更轻松地共享通用代码。

应使用您的顶级域、组织域和子域来定义包和命名空间。例如，Google 地图命名空间定义为 com.google.maps，该命名空间中的 examples 包定义为 com.google.maps.examples。然后，您可使用该命名空间默认定义应用程序的目录结构（例如 com/google/maps/examples/）。

# Google recommends that you create a directory structure based on a unique
# namespace for development of application extensions
# Source ActionScript file will go here:
hostname$ cd myflashapp
hostname$ mkdir your_unique_domain (e.g. com/google/maps/examples)

可以使用该命名空间定义 ActionScript 代码中的包，并可以在 MXML 声明中定义您的应用程序。通常，ActionScript 代码（*.as 文件）位于定义命名空间的最低层目录中，而 MXML 声明（*.mxml 文件）位于该目录结构的“根目录”中。

编写 Google Maps API（Flash 版）的“Hello World”

初步了解 Google Maps API（Flash 版）的最简单方式就是看一个简单的示例。在本教程中，我们将使用 ActionScript 代码创建一个包含地图的简单 MXML 文件、使用 Flex SDK 将该文件编译成 SWF 文件、将该 SWF 文件加入 HTML 页面并显示该页面。

MXML 声明

MXML 声明定义 Flex 应用程序中的 UI 元素，而 <mx:Script> 标签中嵌入的 ActionScript 代码定义针对这些 UI 元素的操作。在最简单的示例中，您只需在 MXML 内声明一个 com.google.maps.Map 对象并使用 ActionScript 代码初始化地图即可：

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
<maps:Map xmlns:maps="com.google.maps.*" id="map" mapevent_mapready="onMapReady(event)" 
  width="100%" height="100%" key="your_api_key"/>
<mx:Script>
    <![CDATA[
   
    import com.google.maps.LatLng;
    import com.google.maps.Map;
    import com.google.maps.MapEvent;
    import com.google.maps.MapType;

    private function onMapReady(event:Event):void {
      this.map.setCenter(new LatLng(40.736072,-73.992062), 14, MapType.NORMAL_MAP_TYPE);
    }
    ]]>
</mx:Script>
</mx:Application>

该示例位于 gmaps-samples-flash.googlecode.com/svn/trunk/examples/HelloWorld.html 上。（MXML 源位于此处。）请注意，您需要使用自己的 API 密钥创建自己的 SWF 文件，本示例才能显示在您的网站中。

即使在此简单的示例中，也有几点需要注意：

1. 按照 Flex 应用程序的要求，我们声明初始 <mx:Application> 来存储所有代码。在该 <mx:Application> 对象中，我们声明 xm 命名空间来引用标准的 Flex 组件。
2. 我们将 Map 对象声明为 <mx:Application> 子项，并定义 maps 命名空间来引用来自 com.google.maps.* 的代码。我们还定义包含 id、mapevent_mapready 处理程序和 API key的参数。这些参数会在以后进行介绍。
3. 我们在 <mx:Script> 子对象中定义 ActionScript 代码。
4. 在该 ActionScript 代码中，我们在收到 mapevent_mapready 事件后使地图以某个位置为中心。

下面将详细介绍这些步骤。

声明应用程序

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">

Google Maps Flash 应用程序不仅需要 ActionScript 代码，而且还需要用户界面框架在网页上显示地图和任何关联的 UI 元素。在 Flex Framework 中，这些 UI 组件在 MXML 声明中指定。MXML 声明包含带有 .mxml 后缀的配置文件。该 MXML 文件通常位于 ActionScript 开发目录的根目录中。

要在网页上显示 Flash 地图，您至少需要一个 MXML 声明。所有 MXML 声明都需要 <mx:Application> 根组件。此外，<mx:Application> 也注册 mx 前缀以引用标准的 Flex 组件。

请注意，MXML 声明可能非常复杂，并且 MXML 声明中 UI 组件的布局未在本文档中进行介绍。有关详细信息，请查看提供的示例并参见 Flex SDK 文档。

声明地图

<maps:Map xmlns:maps="com.google.maps.*" id="map" mapevent_mapready="onMapReady(event)" 
  width="100%" height="100%" key="your_api_key"/>

Google Maps API（Flash 版）现在提供对 com.google.maps.* 包内定义的 Map 对象的本地支持。我们在此将 Map 添加为 <mx:Application> 的子项、将其命名空间定义为 maps（将它链接到 com.google.maps.* 代码）、设置可从 ActionScript 代码内引用地图的 id 并定义 mapevent_mapready 处理程序。（请参见下面的事件处理。）

<maps:Map> 声明还指定 width 和 height 参数，以定义地图在应用程序中的显示方式。更重要的是，MXML 声明是放置唯一 API key的便利位置。

编写 ActionScript 代码

<mx:Script>
    <![CDATA[
    
    // ActionScript Code
    
    ]]>
</mx:Script>

使用 ActionScript 3.0 代码在 Google Maps API（Flash 版）中操控地图。本教程不会详细介绍 ActionScript。可在以下位置中获得有关 ActionScript 的在线教程：

• http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/
• http://www.adobe.com/devnet/flex/quickstart/coding_with_mxml_and_actionscript/

<mx:Script> 对象是存储对 ActionScript 代码的引用的 Flex 组件。MXML 是 XML 的变体，因此我们还需要使用 <![CDATA[][ 和 ]]> 分隔符来告知 MXML 解析器忽略该文件中的 ActionScript 代码。

注意：您可能反而想要在单独的 ActionScript (*.as) 文件中提供您的 ActionScript。如果这样，您可以通过在 <mx:Script> 标签中加入 source 参数来引用 ActionScript 文件。

<mx:Script source="HelloWorld.as"></mx:Script>

如果您的应用程序较大或较复杂，则应将代码添加到单独的文件中。但是，在该文档中，我们会在 MXML 声明中显示所有代码内联以进行简化。

导入库

    import com.google.maps.LatLng;
    import com.google.maps.Map;
    import com.google.maps.MapEvent;
    import com.google.maps.MapType;

通过 import 声明导入 ActionScript 库。在以上示例代码中，导入了多个 Google Maps Flash 库。

您应当确保在示例代码中导入所需类型的库。建议您只导入需要的类。在该文档的大多数示例中，我们会组织代码的结构以便 <mx:Application> 不使用 Flex UI 组件。这样做会提供基本的轻量级地图。请注意，包含任意 Flex 库都可能大大增加 SWF 文件的大小，即使您只需要一个特定的 Flex 组件（例如按钮）。

设置事件侦听器

ActionScript（类似 JavaScript）是一种事件驱动编程语言。通过针对特定事件在对象上注册事件侦听器来处理在 Flash 对象内的用户互动。

在前一部分的代码段中，Map 声明使用特定参数 mapevent_mapready 针对 MapEvent.MAP_READY 事件将事件侦听器添加到了 Map 对象。该事件处理程序作为“钩子”来初始化 Google Maps API（Flash 版）应用程序。当地图收到该事件后，它会调用 onMapReady 函数（如下所示）。

function onMapReady(event:MapEvent):void {
  setCenter(new LatLng(40.736072,-73.992062), 14, MapType.NORMAL_MAP_TYPE);
}

该 onMapReady() 函数会传递类型为 MapEvent 的 event 参数（在本例中忽略），然后使用指定参数（定义要显示的地图的位置、缩放级别和类型）调用 setCenter()。

通常，通过截获和处理 MapEvent.MAP_READY 事件来以这样一种方式“初始化”地图是个不错的方法。在 Google Maps Flash 文档的地图事件部分中对事件进行了详细介绍。

请注意：您还可以通过截获和处理 MapEvent.MAP_PREINITIALIZE 事件来初始化地图。有关该事件的信息，请参见对 MapOptions 的介绍。

在 Google Maps Flash 文档的地图事件部分中对事件进行了详细介绍。

编译 SWF 文件

现在，在源的根目录中有 HelloWorld.mxml，在该文件的 <mx:Script> 对象中有 ActionScript 代码。我们已准备好将代码编译成 SWF (Shockwave Flash) 文件。我们使用 Flex SDK 的 mxmlc 编译程序进行此操作。

mxmlc 编译程序需要目标 *.mxml 文件。此外，为了使用 Google Maps API（Flash 版），我们使用该编译程序的 -library-path 参数添加为您提供的 Google Maps API（Flash 版）库 (maps_flex_1_7.swc) 的位置。下面显示一个简单的调用示例：

# Execute this command from the ROOT of your development directory, not from within 
# the leaf of the namespace (e.g. not in com/google/maps/examples)
#
hostname$:~/src/helloworld$ path_to_flex_sdk/bin/mxmlc HelloWorld.mxml -library-path+=maps_flex_1_7.swc
Loading configuration file /home/src/flex_sdk/frameworks/flex-config.xml
/home/src/helloworld/HelloWorld.swf (22223 bytes)

如果在编译时遇到麻烦：

• 确保您可以执行 mxmlc 编译程序（您可能需要更改您的路径以添加 Flex SDK 的 bin 目录）。
• 确保在适当的目录结构中设置您的 MXML 和 ActionScript 文件，以反映您声明的命名空间。
• 确保使用“加号等号”操作符 (+=) 添加 library-path 参数。

拥有 HelloWorld.swf 文件后，就可以在网页中放置该文件。

在网页中托管 SWF 文件

Google Maps Flash SWF 文件如果是使用附带的 API 密钥编译的，那么可以简单地显示为单独的文件。这一点在进行测试时很有用，但可能不适合进行适当的页面布局。因此，您可能需要设置 HTML 页面以包含该 SWF 文件。为了确保您的 SWF 文件可在 Internet Explorer 和其他浏览器中执行，您应在 object 和 embed 标签中都添加 SWF。

下面显示了包含 HelloWorld.swf 文件的简单 HTML 页面。要让地图在网页上显示，必须为其留出一个位置。本例中，我们通过创建指定的 div 元素并向该元素添加 object 元素来完成此操作。

  <div id="map_canvas" name="map_canvas">
    <object
      classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
      codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,29,0"
      width="800px"
      height="600px">
      <param name="movie" value="helloworld.swf">
      <param name="quality" value="high">
      <param name="flashVars" value="key=your_api_key">
      <embed
        width="800px"
        height="600px"
        src="helloworld.swf"
        quality="high"
        flashVars="key=your_api_key"
        pluginspage="http://www.macromedia.com/go/getflashplayer"
        type="application/x-shockwave-flash">
      </embed>
    </object>
  </div>

请注意，我们在 flashVars 参数中添加 API 密钥参数。该注册方法是在 MXML 声明中将密钥编译成 SWF 文件的一种备用方法。如果在此指定值，则这些值会覆盖 SWF 文件或 MXML 声明中所包含的值。另请注意，API 密钥必须和托管“SWF”文件的域匹配，而不是与可能用来托管 HTML 文件的域匹配。

下面显示了生成的 HTML 页面。

 

查看源 (HelloWorld.mxml)

恭喜您！您已经编写好了您的第一个 Google Maps Flash 应用程序！