Pronto!

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

Ativar a Google Maps JavaScript API

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

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps JavaScript API e serviços relacionados
  3. Criar chaves apropriadas
Continuar

Sobreposições personalizadas

  1. Introdução
  2. Adicionar uma sobreposição personalizada
    1. Criar uma subclasse da sobreposição
    2. Inicializar a sobreposição
    3. Desenhar a sobreposição
  3. Remover uma sobreposição personalizada
  4. Ocultar e mostrar uma sobreposição personalizada

Introdução

As sobreposições são objetos no mapa vinculados a coordenadas de latitude/longitude. Portanto, eles se movem quando o mapa é arrastado ou o zoom é alterado. Para obter informações sobre os tipos de sobreposição predefinidos, consulte Desenho no mapa.

A Google Maps JavaScript API oferece uma classe OverlayView para que você crie sobreposições personalizadas. A OverlayView é uma classe básica que oferece diversos métodos que devem ser implementados para criar sobreposições. A classe também oferece alguns métodos que possibilitam a conversão entre coordenadas de tela e localizações no mapa.

Adicionar uma sobreposição personalizada

Veja a seguir um resumo das etapas necessárias para criar uma sobreposição personalizada:

  • Defina prototype no objeto da sobreposição personalizada como uma nova instância de google.maps.OverlayView(). Na prática, essa ação cria uma subclasse da classe de sobreposição.
  • Crie um construtor para a sobreposição personalizada e defina todos os parâmetros de inicialização.
  • Implemente um método onAdd() no protótipo e anexe a sobreposição ao mapa. OverlayView.onAdd() é chamado quando o mapa está pronto para a anexação da sobreposição.
  • Implemente um método draw() no protótipo e processe a exibição visual do objeto. OverlayView.draw() é chamado na primeira exibição do objeto.
  • Implemente também um método onRemove() para limpar todos os elementos adicionados à sobreposição.

Veja a seguir mais detalhes sobre cada etapa. Veja também o exemplo completo e funcional: Ver o exemplo (overlay-simple.html).

Criar uma subclasse da sobreposição

O exemplo abaixo usa OverlayView para criar uma sobreposição de imagem simples.

// This example creates a custom overlay called USGSOverlay, containing
// a U.S. Geological Survey (USGS) image of the relevant area on the map.

// Set the custom overlay object's prototype to a new instance
// of OverlayView. In effect, this will subclass the overlay class therefore
// it's simpler to load the API synchronously, using
// google.maps.event.addDomListener().
// Note that we set the prototype to an instance, rather than the
// parent class itself, because we do not wish to modify the parent class.

var overlay;
USGSOverlay.prototype = new google.maps.OverlayView();

// Initialize the map and the custom overlay.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 62.323907, lng: -150.109291},
    mapTypeId: 'satellite'
  });

  var bounds = new google.maps.LatLngBounds(
      new google.maps.LatLng(62.281819, -150.287132),
      new google.maps.LatLng(62.400471, -150.005608));

  // The photograph is courtesy of the U.S. Geological Survey.
  var srcImage = 'https://developers.google.com/maps/documentation/' +
      'javascript/examples/full/images/talkeetna.png';

  // The custom USGSOverlay object contains the USGS image,
  // the bounds of the image, and a reference to the map.
  overlay = new USGSOverlay(bounds, srcImage, map);
}

Agora, criamos um construtor para a classe USGSOverlay e inicializamos os parâmetros passados como propriedades do novo objeto.

/** @constructor */
function USGSOverlay(bounds, image, map) {

  // Initialize all properties.
  this.bounds_ = bounds;
  this.image_ = image;
  this.map_ = map;

  // Define a property to hold the image's div. We'll
  // actually create this div upon receipt of the onAdd()
  // method so we'll leave it null for now.
  this.div_ = null;

  // Explicitly call setMap on this overlay.
  this.setMap(map);
}

Ainda não é possível anexar essa sobreposição ao mapa no construtor da sobreposição. Antes, é necessário garantir que todos os painéis do mapa estejam disponíveis, pois eles especificam a ordem em que os objetos são exibidos no mapa. A API fornece um método auxiliar indicando que isso ocorreu. Falaremos sobre esse método na próxima seção.

Inicializar a sobreposição

Quando a sobreposição é instanciada pela primeira vez e está pronta para exibição, é necessário anexá-la ao mapa usando o DOM do navegador. A API indica que a sobreposição foi adicionada ao mapa invocando o método onAdd() da sobreposição. Para processar esse método, criamos um <div> para manter a imagem, adicionamos um elemento <img>, anexamos esse elemento ao <div> e anexamos a sobreposição a um dos painéis do mapa. Um painel é um nó na árvore do DOM.

Os painéis, do tipo MapPanes, especificam a ordem de empilhamento para as diferentes camadas no mapa. Os painéis a seguir estão disponíveis e são numerados na ordem em que estão empilhados, de baixo para cima:

  • mapPane é o painel mais baixo, e está acima dos blocos. Ele não pode receber eventos do DOM. (Painel 0).
  • overlayLayer contém polilinhas, polígonos, sobreposições de solo e sobreposições de camada de blocos. Ele não pode receber eventos do DOM. (Painel 1).
  • overlayShadow contém as sombras do marcador. Ele não pode receber eventos do DOM. (Painel 2).
  • overlayImage contém as imagens de primeiro plano do marcador. (Painel 3).
  • floatShadow contém a sombra da janela de informações. Ela fica acima de overlayImage, ou seja, os marcadores podem ficar na sombra da janela de informações. (Painel 4).
  • overlayMouseTarget contém elementos que recebem eventos de mouse do DOM, como alvos transparentes para marcadores. Ela fica acima de floatShadow, ou seja, os marcadores na sombra da janela de informações podem ser clicáveis. (Painel 5).
  • floatPane contém a janela de informações. Ela está acima de todas as sobreposições do mapa. (Painel 6).

Como a imagem é uma "sobreposição de solo", usamos o painel overlayLayer. Quando temos o painel, o objeto será anexado a ele como um filho.

/**
 * onAdd is called when the map's panes are ready and the overlay has been
 * added to the map.
 */
USGSOverlay.prototype.onAdd = function() {

  var div = document.createElement('div');
  div.style.borderStyle = 'none';
  div.style.borderWidth = '0px';
  div.style.position = 'absolute';

  // Create the img element and attach it to the div.
  var img = document.createElement('img');
  img.src = this.image_;
  img.style.width = '100%';
  img.style.height = '100%';
  img.style.position = 'absolute';
  div.appendChild(img);

  this.div_ = div;

  // Add the element to the "overlayLayer" pane.
  var panes = this.getPanes();
  panes.overlayLayer.appendChild(div);
};

Desenhar a sobreposição

Observe que não invocamos nenhuma exibição visual especial no código acima. A API invoca um método draw() separado na camada sempre que precisa desenhar a sobreposição no mapa, inclusive quando adicionada pela primeira vez.

Portanto, implementamos esse método draw(), recuperamos a MapCanvasProjection da sobreposição usando getProjection() e calculamos as coordenadas exatas para ancorar os pontos superior direito e inferior esquerdo do objeto. Em seguida, podemos redimensionar o <div>. Por sua vez, essa ação redimensiona a imagem para corresponder aos limites especificados no construtor da sobreposição.

USGSOverlay.prototype.draw = function() {

  // We use the south-west and north-east
  // coordinates of the overlay to peg it to the correct position and size.
  // To do this, we need to retrieve the projection from the overlay.
  var overlayProjection = this.getProjection();

  // Retrieve the south-west and north-east coordinates of this overlay
  // in LatLngs and convert them to pixel coordinates.
  // We'll use these coordinates to resize the div.
  var sw = overlayProjection.fromLatLngToDivPixel(this.bounds_.getSouthWest());
  var ne = overlayProjection.fromLatLngToDivPixel(this.bounds_.getNorthEast());

  // Resize the image's div to fit the indicated dimensions.
  var div = this.div_;
  div.style.left = sw.x + 'px';
  div.style.top = ne.y + 'px';
  div.style.width = (ne.x - sw.x) + 'px';
  div.style.height = (sw.y - ne.y) + 'px';
};

Remover uma sobreposição personalizada

Também adicionamos um método onRemove() para remover a sobreposição do mapa de forma limpa.

// The onRemove() method will be called automatically from the API if
// we ever set the overlay's map property to 'null'.
USGSOverlay.prototype.onRemove = function() {
  this.div_.parentNode.removeChild(this.div_);
  this.div_ = null;
};

Ocultar e mostrar uma sobreposição personalizada

Para ocultar ou mostrar uma sobreposição, em vez de simplesmente criá-la ou removê-la, implemente seus próprios métodos hide() e show() para ajustar a visibilidade da sobreposição. Como alternativa, desconecte a sobreposição do DOM do mapa, embora essa operação consuma um pouco mais de recursos. Observe que, se você anexar novamente a sobreposição ao DOM do mapa, o método onAdd() da sobreposição será invocado novamente.

O exemplo a seguir adiciona os métodos hide() e show() ao protótipo da sobreposição para alternar a visibilidade do contêiner <div>. Além disso, adicionamos um método toggleDOM(), que anexa a sobreposição ao mapa ou desconecta-a do mapa.

// Set the visibility to 'hidden' or 'visible'.
USGSOverlay.prototype.hide = function() {
  if (this.div_) {
    // The visibility property must be a string enclosed in quotes.
    this.div_.style.visibility = 'hidden';
  }
};

USGSOverlay.prototype.show = function() {
  if (this.div_) {
    this.div_.style.visibility = 'visible';
  }
};

USGSOverlay.prototype.toggle = function() {
  if (this.div_) {
    if (this.div_.style.visibility === 'hidden') {
      this.show();
    } else {
      this.hide();
    }
  }
};

// Detach the map from the DOM via toggleDOM().
// Note that if we later reattach the map, it will be visible again,
// because the containing <div> is recreated in the overlay's onAdd() method.
USGSOverlay.prototype.toggleDOM = function() {
  if (this.getMap()) {
    // Note: setMap(null) calls OverlayView.onRemove()
    this.setMap(null);
  } else {
    this.setMap(this.map_);
  }
};

Cuidar da interface do usuário:

<!-- Add an input button to initiate the toggle method on the overlay. -->
    <div id="floating-panel">
      <input type="button" value="Toggle visibility" onclick="overlay.toggle();"></input>
      <input type="button" value="Toggle DOM attachment" onclick="overlay.toggleDOM();"></input>
    </div>

Ver o exemplo (overlay-hideshow.html).

Enviar comentários sobre…

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