Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ative a Google Maps Android API

Para começar, orientaremos você pelo Google Developers Console para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ative a Google Maps Android API
  3. Criar chaves apropriadas
Continuar

Formas

A Google Maps API for Android oferece algumas formas simples de adicionar formas a mapas, personalizando-os para o aplicativo.

  • Uma Polyline é uma série de segmentos de linha conectados que pode criar qualquer forma desejada para marcar caminhos e rotas no mapa.
  • Um Polygon é uma forma delimitada que pode ser usada para marcar áreas no mapa.
  • Um Circle é uma projeção geograficamente precisa de um círculo na superfície do planeta desenhada no mapa.

É possível personalizar a aparência de todas essas formas alterando várias propriedades.

Exemplos de código

O repositório ApiDemos no GitHub inclui exemplos que demonstram o uso de formas e seus recursos:

Polilinhas

A classe Polyline define um conjunto de segmentos de linha conectados no mapa. Um objeto Polyline consiste em um conjunto de localizações LatLng e cria uma série de segmentos de linha que conecta essa localização em uma sequência ordenada.

Este vídeo oferece ideias sobre como ajudar os usuários a chegar a seus destinos usando polilinhas para desenhar um caminho no mapa.

Antes de criar uma polilinha, crie um objeto PolylineOptions e adicione pontos a ele. Os pontos representam um ponto na superfície do planeta e são expressos como um objeto LatLng. Os segmentos de linha são desenhados entre os pontos de acordo com a ordem em que são adicionados ao objeto PolylineOptions. Para adicionar pontos a um objeto PolylineOptions, chame PolylineOptions.add(). Observe que esse método aceita um número variável de parâmetros para permitir a adição de vários pontos de uma vez (também é possível chamar 'PolylineOptions.addAll(Iterable)' se os pontos já estão em uma lista).

Em seguida, você pode adicionar a polilinha a um mapa chamando GoogleMap.addPolyline(PolylineOptions). O método retorna um objeto Polyline que permite alterar a polilinha posteriormente.

O fragmento de código a seguir demonstra como adicionar um retângulo a um mapa:

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions rectOptions = new PolylineOptions()
        .add(new LatLng(37.35, -122.0))
        .add(new LatLng(37.45, -122.0))  // North of the previous point, but at the same longitude
        .add(new LatLng(37.45, -122.2))  // Same latitude, and 30km to the west
        .add(new LatLng(37.35, -122.2))  // Same longitude, and 16km to the south
        .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = myMap.addPolyline(rectOptions);

Para alterar a forma da polilinha após sua adição, chame Polyline.setPoints() e forneça uma nova lista de pontos para a polilinha.

É possível personalizar a aparência da polilinha antes e depois de adicioná-la ao mapa. Consulte a seção sobre personalização de aparências a seguir para obter mais detalhes.

Eventos de polilinha

Por padrão, as polilinhas não são clicáveis. Você pode ativar e desativar a capacidade de receber cliques chamando Polyline.setClickable(boolean).

Use um OnPolylineClickListener para detectar eventos de clique em uma polilinha clicável. Para definir esse ouvinte no mapa, chame GoogleMap.setOnPolylineClickListener(OnPolylineClickListener). Quando um usuário clicar em uma polilinha, você receberá um retorno de chamada onPolylineClick(Polyline).

Polígonos

Os objetos Polygon são similares aos objetos Polyline . Ambos consistem em uma série de coordenadas em uma sequência ordenada. No entanto, em vez de abertos, os polígonos foram projetados para definir regiões em um loop fechado com o interior preenchido.

Um Polygon pode ser adicionado ao mapa da mesma forma que uma Polyline. Crie antes um objeto PolygonOptions e adicione a ele alguns pontos. Esses pontos formam o contorno do polígono. Em seguida, adicione o polígono ao mapa chamando GoogleMap.addPolygon(PolygonOptions), que retorna um objeto Polygon.

O fragmento de código a seguir adiciona um retângulo a um mapa (observe que, como não definimos uma cor de preenchimento, que por padrão é transparente, o retângulo tem exatamente a mesma aparência da polilinha do fragmento da seção anterior):

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions rectOptions = new PolygonOptions()
              .add(new LatLng(37.35, -122.0),
                   new LatLng(37.45, -122.0),
                   new LatLng(37.45, -122.2),
                   new LatLng(37.35, -122.2),
                   new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = myMap.addPolygon(rectOptions);

Para alterar a forma do polígono após sua adição, chame Polygon.setPoints() e forneça uma nova lista de pontos para o contorno do polígono.

É possível personalizar a aparência do polígono antes e depois de adicioná-lo ao mapa. Consulte a seção sobre personalização de aparências a seguir para obter mais detalhes.

Finalização automática de polígonos

O polígono do exemplo acima consiste em cinco coordenadas. Observe que a primeira e a última coordenadas estão no mesmo local, definindo o loop. No entanto, na prática, como os polígonos definem áreas fechadas, não é necessário definir essa última coordenada. Se a última coordenada for diferente da primeira, a API "fechará" automaticamente o polígono acrescentando a primeira coordenada ao final da sequência de coordenadas.

Os dois polígonos a seguir são equivalentes. A chamada de polygon.getPoints() para cada um deles retornará todos os 4 pontos.

Polygon polygon = map.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(0, 0))
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE));

Polygon polygon = map.addPolygon(new PolygonOptions()
         .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5))
         .strokeColor(Color.RED)
         .fillColor(Color.BLUE));

Criar um polígono vazio

É possível combinar vários caminhos em um único objeto Polygon para criar formas complexas, como anéis preenchidos ou "roscas" (onde as áreas poligonais são exibidas dentro do polígono como "ilhas"). Formas complexas são sempre a combinação de vários caminhos simples.

É necessário definir dois caminhos na mesma área. A maior das duas regiões define a área de preenchimento e é um polígono simples sem opções adicionais. Em seguida, passe um segundo caminho ao método addHole(). Quando o segundo caminho menor for totalmente incluído no caminho maior, parecerá que uma parte do polígono foi removida. Se o buraco cruzar o contorno do polígono, o polígono será renderizado sem nenhum preenchimento.

O fragmento abaixo cria um retângulo simples com um buraco retangular menor.

mMap.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(3, 0), new LatLng(0, 0))
        .addHole(new LatLng(1, 1), new LatLng(1, 2), new LatLng(2, 2), new LatLng(2, 1), new LatLng(1, 1))
        .fillColor(Color.BLUE));

Eventos de polígono

Por padrão, os polígonos não são clicáveis. Você pode ativar e desativar a capacidade de receber cliques chamando Polygon.setClickable(boolean).

Use um OnPolygonClickListener para detectar eventos de clique em um polígono clicável. Para definir esse ouvinte no mapa, chame GoogleMap.setOnPolygonClickListener(OnPolygonClickListener). Quando um usuário clicar em um polígono, você receberá um retorno de chamada onPolygonClick(Polygon).

Círculos

Além da classe genérica Polygon, a Maps API também oferece classes específicas para objetos Circle, simplificando a construção.

Para construir um círculo, é preciso especificar estas duas propriedades:

  • center como um LatLng.
  • radius em metros.

Um círculo é definido como o conjunto de todos os pontos na superfície do planeta que estão a radius metros de um determinado center. Devido à forma como a projeção Mercator usada pela Maps API renderiza uma esfera em uma superfície plana, o círculo exibido será praticamente perfeito no mapa, quando localizado perto do equador, e será cada vez menos circular (na tela) à medida que se afasta do equador.

O fragmento de código a seguir adiciona um círculo ao mapa construindo um objeto CircleOptions e chamando GoogleMap.addCircle(CircleOptions):

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions = new CircleOptions()
    .center(new LatLng(37.4, -122.1))
    .radius(1000)); // In meters

// Get back the mutable Circle
Circle circle = myMap.addCircle(circleOptions);

Para alterar a forma do círculo após a adição, você pode chamar Circle.setRadius() ouCircle.setCenter() e informar novos valores.

É possível personalizar a aparência do círculo antes e depois de adicioná-lo ao mapa. Consulte a seção sobre personalização de aparências a seguir para obter mais detalhes.

Eventos de círculo

Por padrão, os círculos não são clicáveis. Você pode ativar e desativar a capacidade de receber cliques chamando GoogleMap.addCircle() com CircleOptions.clickable(boolean) ou chamando Circle.setClickable(boolean).

Use um OnCircleClickListener para detectar eventos de clique em um círculo clicável. Para definir esse ouvinte no mapa, chame GoogleMap.setOnCircleClickListener(OnCircleClickListener).

Quando o usuário clicar em um círculo, você receberá um retorno de chamada onCircleClick(Circle), como mostrado no exemplo de código a seguir:

public class MyActivity extends FragmentActivity
        implements OnMapReadyCallback {

        private GoogleMap mMap;
        private Circle circle;

        @Override
        public void onMapReady(GoogleMap map) {
            mMap = map;

            circle = mMap.addCircle(new CircleOptions()
                .center(new LatLng(37.4, -122.1))
                .radius(1000)
                .strokeWidth(10)
                .strokeColor(Color.GREEN)
                .fillColor(Color.argb(128, 255, 0, 0))
                .clickable(true);

            map.setOnCircleClickListener(new OnCircleClickListener() {

                @Override
                public void onCircleClick(Circle circle) {
                    // Flip the r, g and b components of the circle's
                    // stroke color.
                    int strokeColor = circle.getStrokeColor() ^ 0x00ffffff;
                    circle.setStrokeColor(strokeColor);
                }
            });
        }
}

Personalizar aparências

É possível alterar a aparência de uma forma antes de adicioná-la ao mapa (especificando a propriedade desejada no objeto de opções) ou depois da adição. Getters também são expostos para todas as propriedades, permitindo acessar facilmente o estado atual da forma.

O fragmento a seguir adiciona uma polilinha azul grossa com segmentos geodésicos de Melbourne a Perth. As seções abaixo explicam essas propriedades mais detalhadamente.

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Observação: Embora a maioria dessas propriedades possa ser aplicada a qualquer das formas descritas, é possível que algumas não façam sentido para determinadas formas (por exemplo, uma polilinha não pode ter uma cor de preenchimento porque não tem um interior).

Cor do traço

A cor do traço é um inteiro de 32 bits alpha-vermelho-verde-azul (ARGB) que especifica a opacidade e a cor do traço da forma. Defina essa propriedade no objeto de opções da forma chamando *Options.strokeColor() (ou PolylineOptions.color() para polilinhas). Se não especificada, a cor de traço padrão é preto (Color.BLACK).

Após a adição da forma ao mapa, é possível acessar a cor do traço chamando getStrokeColor() (ougetColor() para polilinhas) e alterá-la chamando setStrokeColor() (setColor() for a polyline).

Cor de preenchimento

A cor de preenchimento só se aplica a polígonos e círculos. Ela não se aplica a polilinhas, pois elas não têm interiores definidos. Para um polígono, as regiões dentro dos buracos não fazem parte do interior do polígono e não são coloridas quando uma cor de preenchimento é definida.

A cor de preenchimento é um inteiro de 32 bits alpha-vermelho-verde-azul (ARGB) que especifica a opacidade e a cor interior da forma. Defina essa propriedade no objeto de opções da forma chamando *Options.fillColor(). Se não especificada, a cor de traço padrão é transparente (Color.TRANSPARENT).

Após a adição da forma ao mapa, é possível acessar a cor do preenchimento chamando getFillColor() e alterá-la chamando setFillColor().

Largura do traço

A largura do traço da linha, como um número flutuante em pixels (px). A largura não é alterada com a mudança do zoom do mapa (ou seja, uma forma tem a mesma largura do traço em todos os níveis de zoom). Defina essa propriedade no objeto de opções da forma chamando *Options.strokeWidth() (ou PolylineOptions.width() para polilinhas). Se não especificada, a largura do traço padrão é 10 pixels.

Após a adição da forma ao mapa, é possível acessar a largura do traço chamando getStrokeWidth() (ougetWidth() para polilinhas) e alterá-la chamando setStrokeWidth() (setWidth() for a polyline).

Segmentos geodésicos

A configuração geodésica se aplica apenas a polilinhas e polígonos. Ela não se aplica a círculos, pois eles não são definidos como uma coleção de segmentos.

A configuração geodésica determina como são desenhados os segmentos de linha entre vértices consecutivos de polilinha/polígono. Os segmentos geodésicos são os que seguem o menor caminho sobre a superfície do planeta (uma esfera) e frequentemente são exibidos como linhas curvas em um mapa com projeção Mercator. Os segmentos não geodésicos são desenhados como linhas retas no mapa.

Defina essa propriedade no objeto de opções da forma chamando *Options.geodesic(), onde true indica que os segmentos serão desenhados como geodésicos e false indica que os segmentos serão desenhados como linhas retas. Se não especificada, o padrão é segmentos não geodésicos (false).

Após a adição da forma ao mapa, é possível acessar a configuração geodésica chamando isGeodesic() e alterá-la chamando setGeodesic().

Índice Z

O índice z especifica a ordem da pilha dessa forma em relação a outras sobreposições (outras formas, sobreposições de solo e sobreposições de blocos) no mapa. Uma sobreposição com índice z alto é desenhada sobre as sobreposições com índices z menores. Duas sobreposições com o mesmo índice z são desenhadas em uma ordem aleatória.

Observe que os marcadores são sempre desenhados sobre as outras sobreposições, independentemente do índice z das outras sobreposições.

Defina essa propriedade no objeto de opções da forma chamando *Options.zIndex(). Se não especificado, o índice z padrão é 0. Após a adição da forma ao mapa, é possível acessar o índice z chamando getZIndex() e alterá-lo chamando setZIndex().

Visibilidade

A visibilidade especifica se é preciso desenhar a forma no mapa, com true indicando que é preciso e false indicando que não é preciso. Ela permite deixar de exibir temporariamente uma forma no mapa. Para remover permanentemente a forma do mapa, chame remove() nessa forma.

Defina essa propriedade no objeto de opções da forma chamando *Options.visible(). Se não especificada, a visibilidade padrão é true. Após a adição da forma ao mapa, é possível acessar a visibilidade chamando isVisible() e alterá-la chamando setVisible().

Enviar comentários sobre…

Google Maps Android API
Google Maps Android API
Precisa de ajuda? Acesse nossa página de suporte.