Google Maps API for Flash

登録して API キーを取得

Maps API for Flash
- デベロッパーガイド
  - チュートリアル
  - 基本
  - イベント
  - コントロール
  - オーバーレイ
  - サービス
- API リファレンス
- コードサンプル:
  - デモ
  - 例
- その他のリソース:

Maps API
- ホームページ
- ドキュメント

Mapplets Maps API
- ホームページ
- ドキュメント

Static Maps API
- デベロッパーガイド

Google Maps API for Flash - Flex SDK チュートリアル

開発環境を設定する
Maps API for Flash の「Hello World」の記述

開発環境を設定する

このチュートリアルは、Adobe Flex SDK の入手とセットアップ、開発環境の準備、ActionScript のプログラミングで初めて Google Maps API for Flash 地図を作成する方法について説明します。

注: FlexBuilder IDE を使用する場合は、「FlexBuilder チュートリアル」をご覧ください。

Adobe Flex SDK の入手とインストール

Google Maps を Flex アプリケーションに組み込むには、ActionScript コードだけでなく Flex MXML ファイルについての理解も必要です。このドキュメントに示す例では、Adobe Flex 3 SDK を自由に使用します。これは下記の URL から入手できます。

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

注: Flex SDK を実行するには (開発プラットフォームに応じて) Java 1.4 または 1.5 が必要です。Flex SDK を使った開発に必要なものはすべて下記の URL から入手できます。

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 のデバッグバージョンをインストールしてください。デバッグバージョンは下記の URL から入手できます。

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

デバッグバージョンを正常にインストールするには、デバッグバージョン以外の Flash プレーヤーのアンインストールやブラウザのシャットダウンが必要になる場合もあります。

開発ディレクトリの設定

New! Google Maps API for Flash は Flex 内の com.google.maps.Map オブジェクトに対するネイティブサポートを提供します。Map クラスを拡張して Map アプリケーションクラスを定義する必要はもうありません。Flex の中で Map コンポーネントを直接使用できます。

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 for Flash コンポーネントを「拡張」するコンポーネントは通常、一意の名前空間の中で ActionScript ライブラリとして提供されます。他のライブラリとの衝突を防ぐため、所有している名前空間を使用することを推奨します。これが特に重要なのは、多数の開発者が複数の flash コンポーネントの作業を同時に行う場合です。名前空間を使用すれば、ライブラリコードを「パッケージ」にまとめることもできるので、共通するコードの共有が簡単になります。

パッケージと名前空間は、トップレベルドメイン、組織ドメイン、サブドメインを使って定義します。たとえば、Google Maps 名前空間は 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 ファイル) はディレクトリ構造の「ルート」にあります。

Maps API for Flash の「Hello World」の記述

Google Maps API for Flash について学習する場合、簡単な例を見るのが最もやさしい方法です。このチュートリアルでは、ActionScript コードを使って地図を組み込んだ簡単な MXML ファイルを作成し、Flex SDK を使ってこのファイルを 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 ソースはこちらにあります)。この例を自分の Web サイトに表示するには、自分の API キーを使って SWF ファイルを作成する必要があります。

この簡単な例でも、次のいくつかの点について注意する必要があります。

最初に <mx:Application> を宣言し、Flex アプリケーションに必要なコードのすべてを収容します。この <mx:Application> オブジェクトの中で、xm 名前空間を宣言し、標準の Flex コンポーネントを参照します。
Map オブジェクトを <mx:Application> の子として宣言し、maps 名前空間を定義して com.google.maps.* からコードを参照します。id、mapevent_mapready ハンドラ、API key などのパラメータも定義します。これらのパラメータについては後で説明します。
子の <mx:Script> オブジェクトの中で ActionScript コードを定義します。
その ActionScript コードの中で、mapevent_mapready イベントを受け取ると、地図を中心に配置します。

これらの手順について、以下で詳しく説明します。

アプリケーションの宣言

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

Google Maps Flash アプリケーションには ActionScript コードだけでなく、地図と関連する UI 要素を Web ページに表示するためのユーザーインターフェースフレームワークも必要です。Flex フレームワークでは、これらの UI コンポーネントを MXML 宣言の中で指定します。MXML 宣言は .mxml という接尾辞の付いた構成ファイルです。この MXML ファイルは通常、ActionScript 開発ディレクトリのルートにあります。

Flash マップを Web ページに表示するには、少なくとも 1 回の 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 for 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>

Google Maps API for Flash の中の地図は、ActionScript 3.0 コードを使って操作します。ActionScript の詳細は、このチュートリアルでは説明しません。下記の ActionScript オンラインチュートリアルをご覧ください。

<mx:Script> オブジェクトは、ActionScript コードへの参照を収容する Flex コンポーネントです。MXML は XML の変種ですから、<![CDATA[][ および ]]> という区切り文字を使って、このファイル内の ActionScript コードを無視するように、MXML パーサーに知らせる必要があります。

注: 個別の 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 ライブラリを含めると、必要な Flex コンポーネント (ボタンなど) が 1 つだけの場合でも、SWF ファイルのサイズがかなり大きくなることに注意してください。

イベントリスナのセットアップ

ActionScript は JavaScript と同様、イベントドリブンのプログラミング言語です。Flash オブジェクト内部のユーザーインタラクションは、特定のイベントに合ったイベントリスナをオブジェクトに登録することによって処理します。

前のセクションに記載したコードスニペットの Map 宣言では、特殊なパラメータ mapevent_mapready を使って、MapEvent.MAP_READY イベントに合ったイベントリスナが Map オブジェクトに追加されました。このイベントハンドラは、Google Maps API for 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 ドキュメントの Map Events セクションで説明します。

注: それ以外に MapEvent.MAP_PREINITIALIZE イベントのインターセプト処理によって地図を初期化することもできます。このイベントについて詳しくは、MapOptions の説明をご覧ください。

イベントの詳細は、Google Maps Flash ドキュメントの Map Events セクションで説明します。

SWF ファイルのコンパイル

これでソースのルートディレクトリには HelloWorld.mxml、該当ファイルの <mx:Script> オブジェクトには ActionScript コードがそれぞれ組み込まれました。コードを SWF (Shockwave Flash) ファイルにコンパイルすることができます。これを実行するには Flex SDK の mxmlc コンパイラを使います。

mxmlc コンパイラにはターゲットの *.mxml ファイルが必要です。また、Google Maps API for Flash を使用するには、コンパイラの -library-path パラメータを使って、提供された Google Maps API for 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 ファイルが生成されたら、そのファイルを Web ページに組み込むことができます。

Web ページでの SWF ファイルのホスティング

Google Maps Flash SWF ファイルは、API キーを組み込んでコンパイルされていれば、スタンドアロンファイルとして簡単に表示することができます。これはテストには便利ですが、適正なページレイアウトのためには実用的ではないこともあります。そのような場合、HTML ページをセットアップして SWF ファイルを組み込もうということになるでしょう。SWF ファイルを Internet Explorer でも他のブラウザでも実行できるようにするには、必ず object と embed のどちらのタグにも SWF を追加してください。

HelloWorld.swf ファイルを組み込んだ簡単な HTML ページは以下のように表示されます。地図を Web ページに表示するには、そのための領域を用意する必要があります。そのためにこの例では、名前付きの 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 アプリケーションが完成しました。


例: "ajax apis" または "オープンソース"

Google Maps API for Flash

Maps API for Flash

チュートリアル

コード サンプル:

その他のリソース:

Maps API

Mapplets Maps API

Static Maps API