Inclui licença e suporte para empresas
Este tutorial descreve como obter e configurar o Adobe Flex SDK, como configurar seu ambiente de desenvolvimento e como programar em ActionScript para construir seu primeiro mapa da API do Google Maps para Flash.
Observação: Se desejar usar o IDE do FlexBuilder, consulte o Tutorial do FlexBuilder.
A incorporação do Google Maps em um aplicativo do Flex exige conhecimento não apenas do código ActionScript, mas também de arquivos Flex MXML. Os exemplos nesta documentação usam o Adobe Flex 3 SDK disponível gratuitamente no seguinte endereço:
http://www.adobe.com/products/flex/overview/#section-3
Observação: O Flex SDK exige Java 1.4 ou 1.5 (dependendo da plataforma de desenvolvimento). Os requisitos completos para desenvolvimento com o Flex SDK estão disponíveis em:
http://www.adobe.com/products/flex/systemreqs/
Após o download do SDK, descompacte-o em um diretório de trabalho e certifique-se de que seja possível executar o Compilador de MXML (mxmlc) a partir da linha de comando. O compilador mxmlc está localizado no diretório bin do Flex SDK. A execução do compilador com a opção -help deve ter o seguinte resultado.
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. ...
Recomendamos também adicionar o diretório flex_sdk/bin ao seu $PATH, de modo que você possa executar o compilador a partir de qualquer diretório.
Antes de iniciar o desenvolvimento, instale primeiro uma versão de depuração do Adobe Flash Player. As versões de depuração do player estão disponíveis no seguinte endereço:
http://www.adobe.com/support/flashplayer/downloads.html
Talvez seja necessário desinstalar quaisquer versões do Flash player que não sejam de depuração e/ou encerrar seu navegador para que a versão de depuração seja instalada com êxito.
Novo! A API do Google Maps para Flash oferece agora suporte original para o objeto com.google.maps.Map no Flex. Não é mais necessário estender a classe Map para definir a classe do seu aplicativo de mapa. Além disso, você pode usar um componente de mapa diretamente no Flex.
Os aplicativos Flex são definidos em declarações MXML. Normalmente, é necessário fornecer esses arquivos MXML na raiz do diretório do seu código-fonte.
# 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
Os componentes que estendem quaisquer componentes existentes da API do Google Maps para Flash devem, normalmente, ser fornecidos como bibliotecas ActionScript em um espaço para nome exclusivo. O Google recomenda o uso de um espaço para nome próprio para impedir colisões com outras bibliotecas; isso é importante especialmente se muitos desenvolvedores estiverem trabalhando em diversos componentes Flash ao mesmo tempo. O uso de espaços para nome também permite o agrupamento do código da sua biblioteca em pacotes, o que permite um compartilhamento facilitado de código comum.
Pacotes e espaços para nome devem ser definidos usando o seu domínio de nível superior, o domínio e o subdomínio da sua organização. Por exemplo, o espaço para nome do Google Maps é definido como com.google.maps e um pacote examples dentro desse espaço para nome seria definido como com.google.maps.examples. Você pode usar esse espaço para nome para definir implicitamente a estrutura de diretórios do seu aplicativo (por exemplo, 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)
Esse espaço para nome é usado para definir um pacote dentro do seu código ActionScript e para definir seu aplicativo na declaração MXML. Normalmente, o código ActionScript (arquivos *.as) está localizado no diretório mais inferior de qualquer espaço para nome definido, enquanto as declarações MXML (arquivos *.mxml) residem na "raiz" da estrutura de diretórios.
A forma mais fácil de começar a aprender sobre a API do Google Maps para Flash é vendo um simples exemplo. Neste tutorial, criaremos um arquivo MXML simples contendo um mapa que utiliza código ActionScript, compilaremos esse arquivo em um arquivo SWF usando o Flex SDK, incluiremos esse arquivo SWF em uma página HTML e a exibiremos.
A declaração MXML define os elementos da interface do usuário em um aplicativo Flex, enquanto o código incorporado ActionScript na tag <mx:Script> define as ações nesses elementos da interface. No caso mais simples, basta declarar um objeto com.google.maps.Map no MXML e inicializar o mapa com o código 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>
Este exemplo está localizado no endereço gmaps-samples-flash.googlecode.com/svn/trunk/examples/HelloWorld.html. O código-fonte MXML está localizado aqui. É necessário construir seu próprio arquivo SWF, com sua própria chave de API, para que esse exemplo apareça em seu site.
Mesmo nesse exemplo simples, há algumas coisas a serem observadas:
<mx:Application> inicial para conter todo o código, conforme exigido para aplicativos Flex. Dentro desse objeto <mx:Application>, declaramos um espaço para nome xm para referenciar os componentes padrão Flex.Map como filho de <mx:Application> e definimos um espaço para nome maps para fazer referenciar o código de com.google.maps.*. Também definimos parâmetros incluindo um id, um manipulador mapevent_mapready e uma key de API. Esses parâmetros serão explicados posteriormente.<mx:Script> filho.mapevent_mapready.Estas etapas são explicadas abaixo com mais detalhes.
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
Os aplicativos do Google Maps para Flash exigem não apenas o código ActionScript, mas também uma estrutura de interface de usuário para exibir o mapa e quaisquer elementos de interface associados em uma página da web. Na estrutura Flex, esses elementos da interface do usuário são especificados dentro de uma declaração MXML. Uma declaração MXML é composta por um arquivo de configuração com o sufixo .mxml. O arquivo MXML normalmente está localizado na raiz do seu diretório de desenvolvimento do ActionScript.
Para exibir seu mapa em Flash em uma página da web, será necessário no mínimo uma declaração MXML. Todas as declarações MXML exigem um componente <mx:Application> raiz. Além disso, <mx:Application> também registra o prefixo mx para referenciar os componentes padrão Flex.
As declarações MXML podem ser bastante complexas e o layout dos componentes de interface do usuário em uma declaração MXML está além do escopo desta documentação. Para obter mais informações, consulte os exemplos fornecidos e consulte a documentação do Flex SDK.
<maps:Map xmlns:maps="com.google.maps.*" id="map" mapevent_mapready="onMapReady(event)" width="100%" height="100%" key="your_api_key"/>
A API do Google Maps para Flash inclui agora suporte original para o objeto Map definido no pacote com.google.maps.*. Adicionamos um Map aqui como filho de <mx:Application>, definimos seu espaço para nome como maps (vinculando-o ao código com.google.maps.*), estabelecemos um id a partir do qual podemos referenciar o mapa de dentro do código ActionScript e configuramos um manipulador mapevent_mapready. Consulte Manipulação de evento a seguir.
A declaração <maps:Map> também especifica os parâmetros width e height para definir como o mapa aparecerá dentro do aplicativo. Mais importante, a declaração MXML age como um local conveniente para colocar sua key de API exclusiva.
<mx:Script>
<![CDATA[
// ActionScript Code
]]>
</mx:Script>
Os mapas na API do Google Maps para Flash são manipulados usando o código do ActionScript 3.0. Este tutorial não tem como objetivo ensinar os detalhes do ActionScript. Os tutoriais on-line sobre ActionScript estão disponíveis nos seguintes locais:
O objeto <mx:Script> é um componente Flex que armazena uma referência ao código ActionScript. Como o MXML é uma variante de XML, também precisamos informar ao analisador do MXML que ignore o código ActionScript contido neste arquivo com o uso dos delimitadores <![CDATA[][ e ]]>.
Observação: Você também pode fornecer seu ActionScript em arquivos de ActionScript (*.as) separados. Dessa forma, será possível referenciar o arquivo de ActionScript incluindo um parâmetro source na tag <mx:Script>:
<mx:Script source="HelloWorld.as"></mx:Script>
Normalmente, inserir o código em arquivo separados é recomendável se você tiver aplicativos grandes e complexos. No entanto, para maior simplicidade, na base deste documento mostraremos todo o código alinhado nas declarações MXML.
import com.google.maps.LatLng;
import com.google.maps.Map;
import com.google.maps.MapEvent;
import com.google.maps.MapType;
As bibliotecas ActionScript são importadas com a declaração import. No código de exemplo acima, importamos diversas bibliotecas do Google Maps para Flash.
Certifique-se de importar as bibliotecas para os tipos necessários no seu código de exemplo. Recomendamos que apenas as classes necessárias sejam importadas. Na maioria dos exemplos nesta documentação, estruturamos nosso código de modo que o <mx:Application> não utilize os componentes da interface do usuário do Flex. Ao fazer isso, proporcionamos um mapa básico e leve. A inclusão de quaisquer bibliotecas Flex pode aumentar bastante o tamanho dos seus arquivos SWF, ainda que você precise de apenas um componente específico Flex (como um botão).
ActionScript, como JavaScript, é uma linguagem de programação orientada a eventos. As interações de usuário nos objetos Flash são manipuladas pelo registro de escutas de evento em objetos para eventos específicos.
No snippet de código da seção anterior, a declaração Map adicionou uma escuta de evento ao objeto Map para o evento MapEvent.MAP_READY usando o parâmetro especial mapevent_mapready. Esse manipulador de evento age como um "gancho" para inicialização do aplicativo da API do Google Maps para Flash. Quando o mapa recebe esse evento, ele chama a função onMapReady, exibida abaixo.
function onMapReady(event:MapEvent):void {
setCenter(new LatLng(40.736072,-73.992062), 14, MapType.NORMAL_MAP_TYPE);
}
Essa função onMapReady() passa um parâmetro event do tipo MapEvent (que é ignorado nesse caso) e chama setCenter() usando os parâmetros fornecidos (que definem um local, um nível de zoom e o tipo do mapa a ser exibido).
Normalmente recomenda-se "inicializar" seu mapa dessa maneira, interceptando e manipulando o evento MapEvent.MAP_READY. Os eventos são discutidos com mais detalhes na seção Eventos de mapa da documentação sobre Google Maps para Flash.
Observação: Você também pode inicializar seu mapa interceptando e manipulando o evento MapEvent.MAP_PREINITIALIZE. Para obter informações sobre esse evento, consulte a discussão sobre MapOptions.
Os eventos são discutidos com mais detalhes na seção Eventos de mapa da documentação sobre Google Maps para Flash.
Agora temos um HelloWorld.mxml no diretório raiz da do código-fonte e um código ActionScript no objeto <mx:Script> desse arquivo. Estamos prontos para compilar nosso código em um arquivo SWF (Shockwave Flash). Fazemos isso usando o compilador mxmlc do Flex SDK.
O compilador mxmlc requer um arquivo *.mxml de destino. Além disso, para usar a API do Google Maps para Flash, usamos o parâmetro -library-path do compilador para adicionar o local da biblioteca da API do Google Maps para Flash (maps_flex_1_7.swc) fornecida. Veja um exemplo de chamada abaixo:
# 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)
Em caso de problemas com a compilação:
mxmlc (convém alterar seu caminho para adicionar o diretório bin do Flex SDK.library-path usando o operador "mais igual a" (+=).Assim que tiver um arquivo HelloWorld.swf, você poderá colocar esse arquivo em uma página da web.
Se os arquivos SWF do Google Maps para Flash forem compilados com a chave de API incluída, poderão simplesmente ser exibidos como arquivos autônomos. Isso é útil para testes, mas pode não ser prático para o layout apropriado da página. Como resultado, é recomendável configurar uma página HTML para conter o arquivo SWF. Para garantir que o seu arquivo SWF seja executado no Internet Explorer e em outros navegadores, você deverá adicionar o SWF nas tags object e embed.
Uma página HTML simples que contém o arquivo HelloWorld.swf aparece abaixo. Para que o mapa seja exibido em uma página da web, precisamos reservar um ponto para ele. Isso pode ser feito neste exemplo criando um elemento div nomeado e adicionando o elemento object a ele.
<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>
Adicionamos o parâmetro da chave de API a um parâmetro flashVars. Esse método de registro é uma alternativa à compilação da sua chave no arquivo SWF dentro da declaração MXML. Se os valores forem especificados aqui, irão substituir os valores contidos no arquivo SWF ou nas declarações MXML. Além disso, a chave de API deve corresponder exatamente ao domínio no qual o arquivo SWF está hospedado, não ao domínio no qual o arquivo HTML pode estar hospedado.
A página HTML resultante é exibida abaixo.
Ver código-fonte (HelloWorld.mxml)
Parabéns! Você escreveu seu primeiro aplicativo do Google Maps para Flash!