Introdução
Um marcador identifica uma localização no mapa. Os marcadores normalmente usam uma imagem padrão, mas podem mostrar imagens personalizadas. Nesse caso, eles são chamados de "ícones". Marcadores e ícones são objetos do tipo Marker
. Defina um ícone personalizado no construtor do marcador ou chamando setIcon()
no marcador. Saiba mais sobre como personalizar a imagem do marcador.
De modo geral, os marcadores são um tipo de sobreposição. Consulte Desenhar no mapa para conferir informações sobre outros tipos de sobreposição.
Os marcadores foram criados para serem interativos. Por exemplo, eles recebem eventos 'click'
por padrão. Então, você pode adicionar um listener de eventos para abrir uma janela de informações que mostra dados personalizados. Para que os usuários consigam mover um marcador no mapa, defina a propriedade draggable
dele como true
. Confira abaixo mais informações sobre marcadores arrastáveis.
Adicionar um marcador
O construtor google.maps.Marker
usa um único literal de objeto Marker options
que especifica as propriedades iniciais do marcador.
Os campos a seguir são especialmente importantes e costumam ser definidos na construção de um marcador:
-
position
(obrigatório) especifica umLatLng
que identifica o local inicial do marcador. Uma maneira de recuperar umLatLng
é usando o serviço de geocodificação. -
map
(opcional) especifica oMap
para posicionar o marcador. Quando você não especifica o mapa na construção, o marcador é criado, mas não anexado (ou mostrado) no mapa. É possível adicionar o marcador posteriormente chamando o métodosetMap()
dele.
O exemplo a seguir adiciona um marcador simples a um mapa em Uluru, no centro da Austrália:
TypeScript
function initMap(): void { const myLatLng = { lat: -25.363, lng: 131.044 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 4, center: myLatLng, } ); new google.maps.Marker({ position: myLatLng, map, title: "Hello World!", }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
function initMap() { const myLatLng = { lat: -25.363, lng: 131.044 }; const map = new google.maps.Map(document.getElementById("map"), { zoom: 4, center: myLatLng, }); new google.maps.Marker({ position: myLatLng, map, title: "Hello World!", }); } window.initMap = initMap;
Testar amostra
No exemplo acima, o marcador é posicionado no mapa durante a criação, usando a propriedade map
nas opções.
Também é possível adicionar o marcador ao mapa diretamente usando o método setMap()
, como mostrado no exemplo abaixo:
var myLatlng = new google.maps.LatLng(-25.363882,131.044922); var mapOptions = { zoom: 4, center: myLatlng } var map = new google.maps.Map(document.getElementById("map"), mapOptions); var marker = new google.maps.Marker({ position: myLatlng, title:"Hello World!" }); // To add the marker to the map, call setMap(); marker.setMap(map);
O title
do marcador aparece como uma dica.
Se você não quiser transmitir Marker options
no construtor do marcador, use um objeto vazio {}
no último argumento.
Remover um marcador
Para remover um marcador do mapa, chame o método setMap()
e transmita null
como argumento.
marker.setMap(null);
O método acima não exclui o marcador, apenas o remove do mapa. Se a sua intenção é a exclusão, remova o marcador do mapa e defina o próprio marcador como null
.
Para gerenciar um grupo de marcadores, crie uma matriz com todos eles e chame setMap()
em cada um quando precisar remover os marcadores. Para excluir, remova os marcadores do mapa e defina o length
da matriz como 0
, eliminando todas as referências a eles.
Personalizar a imagem de um marcador
Para personalizar a aparência dos marcadores, mostre um arquivo de imagem ou um ícone vetorial em vez do ícone de alfinete padrão do Google Maps. Adicione texto com um rótulo de marcador e use ícones complexos para definir regiões clicáveis e a ordem de pilha dos marcadores.
Marcadores com ícones de imagem
No caso mais básico, é possível especificar uma imagem a ser usada em vez do ícone de alfinete padrão do Google Maps. Para isso, defina a propriedade icon
do marcador como o URL de uma imagem. A API Maps JavaScript vai dimensionar o ícone automaticamente.
TypeScript
// This example adds a marker to indicate the position of Bondi Beach in Sydney, // Australia. function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 4, center: { lat: -33, lng: 151 }, } ); const image = "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png"; const beachMarker = new google.maps.Marker({ position: { lat: -33.89, lng: 151.274 }, map, icon: image, }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example adds a marker to indicate the position of Bondi Beach in Sydney, // Australia. function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 4, center: { lat: -33, lng: 151 }, }); const image = "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png"; const beachMarker = new google.maps.Marker({ position: { lat: -33.89, lng: 151.274 }, map, icon: image, }); } window.initMap = initMap;
Testar amostra
Marcadores com ícones vetoriais
Use os caminhos de vetor SVG personalizados para definir a aparência dos marcadores, transmitindo um literal de objeto Symbol
com o trajeto desejado para a propriedade icon
. Defina um caminho personalizado usando a notação de caminho SVG ou aproveite um dos caminhos predefinidos em google.maps.SymbolPath. A propriedade anchor
é obrigatória para a renderização correta do marcador quando o zoom é ajustado. Saiba mais sobre como usar símbolos para criar ícones vetoriais em marcadores (e polilinhas).
TypeScript
// This example uses SVG path notation to add a vector-based symbol // as the icon for a marker. The resulting icon is a marker-shaped // symbol with a blue fill and no border. function initMap(): void { const center = new google.maps.LatLng(-33.712451, 150.311823); const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 9, center: center, } ); const svgMarker = { path: "M-1.547 12l6.563-6.609-1.406-1.406-5.156 5.203-2.063-2.109-1.406 1.406zM0 0q2.906 0 4.945 2.039t2.039 4.945q0 1.453-0.727 3.328t-1.758 3.516-2.039 3.070-1.711 2.273l-0.75 0.797q-0.281-0.328-0.75-0.867t-1.688-2.156-2.133-3.141-1.664-3.445-0.75-3.375q0-2.906 2.039-4.945t4.945-2.039z", fillColor: "blue", fillOpacity: 0.6, strokeWeight: 0, rotation: 0, scale: 2, anchor: new google.maps.Point(0, 20), }; new google.maps.Marker({ position: map.getCenter(), icon: svgMarker, map: map, }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example uses SVG path notation to add a vector-based symbol // as the icon for a marker. The resulting icon is a marker-shaped // symbol with a blue fill and no border. function initMap() { const center = new google.maps.LatLng(-33.712451, 150.311823); const map = new google.maps.Map(document.getElementById("map"), { zoom: 9, center: center, }); const svgMarker = { path: "M-1.547 12l6.563-6.609-1.406-1.406-5.156 5.203-2.063-2.109-1.406 1.406zM0 0q2.906 0 4.945 2.039t2.039 4.945q0 1.453-0.727 3.328t-1.758 3.516-2.039 3.070-1.711 2.273l-0.75 0.797q-0.281-0.328-0.75-0.867t-1.688-2.156-2.133-3.141-1.664-3.445-0.75-3.375q0-2.906 2.039-4.945t4.945-2.039z", fillColor: "blue", fillOpacity: 0.6, strokeWeight: 0, rotation: 0, scale: 2, anchor: new google.maps.Point(0, 20), }; new google.maps.Marker({ position: map.getCenter(), icon: svgMarker, map: map, }); } window.initMap = initMap;
Testar amostra
Rótulos de marcadores
Um rótulo de marcador é um número ou uma letra que aparece dentro dele. A imagem do marcador nesta seção mostra um rótulo com a letra "B". Especifique um rótulo de marcador como uma string ou um objeto MarkerLabel
que inclui uma string e outras propriedades de rótulo.
Ao criar um marcador, defina uma propriedade label
no objeto MarkerOptions
. Também é possível chamar setLabel()
no objeto Marker para definir o rótulo de um marcador atual.
O exemplo a seguir mostra marcadores rotulados quando o usuário clica no mapa:
TypeScript
// In the following example, markers appear when the user clicks on the map. // Each marker is labeled with a single alphabetical character. const labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"; let labelIndex = 0; function initMap(): void { const bangalore = { lat: 12.97, lng: 77.59 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 12, center: bangalore, } ); // This event listener calls addMarker() when the map is clicked. google.maps.event.addListener(map, "click", (event) => { addMarker(event.latLng, map); }); // Add a marker at the center of the map. addMarker(bangalore, map); } // Adds a marker to the map. function addMarker(location: google.maps.LatLngLiteral, map: google.maps.Map) { // Add the marker at the clicked location, and add the next-available label // from the array of alphabetical characters. new google.maps.Marker({ position: location, label: labels[labelIndex++ % labels.length], map: map, }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// In the following example, markers appear when the user clicks on the map. // Each marker is labeled with a single alphabetical character. const labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"; let labelIndex = 0; function initMap() { const bangalore = { lat: 12.97, lng: 77.59 }; const map = new google.maps.Map(document.getElementById("map"), { zoom: 12, center: bangalore, }); // This event listener calls addMarker() when the map is clicked. google.maps.event.addListener(map, "click", (event) => { addMarker(event.latLng, map); }); // Add a marker at the center of the map. addMarker(bangalore, map); } // Adds a marker to the map. function addMarker(location, map) { // Add the marker at the clicked location, and add the next-available label // from the array of alphabetical characters. new google.maps.Marker({ position: location, label: labels[labelIndex++ % labels.length], map: map, }); } window.initMap = initMap;
Testar amostra
Ícones complexos
Especifique formas complexas para indicar regiões clicáveis e definir como os ícones devem aparecer em relação a outras sobreposições (a "ordem de pilha"). Os ícones especificados dessa forma devem configurar as propriedades icon
como um objeto do tipo Icon
.
Os objetos Icon
definem uma imagem, os parâmetros size
e origin
do ícone (se a imagem desejada fizer parte de uma imagem maior em um sprite, por exemplo), além do anchor
em que o ponto de acesso do ícone deve estar localizado (de acordo com a origem).
Posicione o rótulo com um marcador personalizado (se estiver usando um) junto da propriedade labelOrigin
no objeto Icon
.
TypeScript
// The following example creates complex markers to indicate beaches near // Sydney, NSW, Australia. Note that the anchor is set to (0,32) to correspond // to the base of the flagpole. function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 10, center: { lat: -33.9, lng: 151.2 }, } ); setMarkers(map); } // Data for the markers consisting of a name, a LatLng and a zIndex for the // order in which these markers should display on top of each other. const beaches: [string, number, number, number][] = [ ["Bondi Beach", -33.890542, 151.274856, 4], ["Coogee Beach", -33.923036, 151.259052, 5], ["Cronulla Beach", -34.028249, 151.157507, 3], ["Manly Beach", -33.80010128657071, 151.28747820854187, 2], ["Maroubra Beach", -33.950198, 151.259302, 1], ]; function setMarkers(map: google.maps.Map) { // Adds markers to the map. // Marker sizes are expressed as a Size of X,Y where the origin of the image // (0,0) is located in the top left of the image. // Origins, anchor positions and coordinates of the marker increase in the X // direction to the right and in the Y direction down. const image = { url: "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png", // This marker is 20 pixels wide by 32 pixels high. size: new google.maps.Size(20, 32), // The origin for this image is (0, 0). origin: new google.maps.Point(0, 0), // The anchor for this image is the base of the flagpole at (0, 32). anchor: new google.maps.Point(0, 32), }; // Shapes define the clickable region of the icon. The type defines an HTML // <area> element 'poly' which traces out a polygon as a series of X,Y points. // The final coordinate closes the poly by connecting to the first coordinate. const shape = { coords: [1, 1, 1, 20, 18, 20, 18, 1], type: "poly", }; for (let i = 0; i < beaches.length; i++) { const beach = beaches[i]; new google.maps.Marker({ position: { lat: beach[1], lng: beach[2] }, map, icon: image, shape: shape, title: beach[0], zIndex: beach[3], }); } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// The following example creates complex markers to indicate beaches near // Sydney, NSW, Australia. Note that the anchor is set to (0,32) to correspond // to the base of the flagpole. function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 10, center: { lat: -33.9, lng: 151.2 }, }); setMarkers(map); } // Data for the markers consisting of a name, a LatLng and a zIndex for the // order in which these markers should display on top of each other. const beaches = [ ["Bondi Beach", -33.890542, 151.274856, 4], ["Coogee Beach", -33.923036, 151.259052, 5], ["Cronulla Beach", -34.028249, 151.157507, 3], ["Manly Beach", -33.80010128657071, 151.28747820854187, 2], ["Maroubra Beach", -33.950198, 151.259302, 1], ]; function setMarkers(map) { // Adds markers to the map. // Marker sizes are expressed as a Size of X,Y where the origin of the image // (0,0) is located in the top left of the image. // Origins, anchor positions and coordinates of the marker increase in the X // direction to the right and in the Y direction down. const image = { url: "https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png", // This marker is 20 pixels wide by 32 pixels high. size: new google.maps.Size(20, 32), // The origin for this image is (0, 0). origin: new google.maps.Point(0, 0), // The anchor for this image is the base of the flagpole at (0, 32). anchor: new google.maps.Point(0, 32), }; // Shapes define the clickable region of the icon. The type defines an HTML // <area> element 'poly' which traces out a polygon as a series of X,Y points. // The final coordinate closes the poly by connecting to the first coordinate. const shape = { coords: [1, 1, 1, 20, 18, 20, 18, 1], type: "poly", }; for (let i = 0; i < beaches.length; i++) { const beach = beaches[i]; new google.maps.Marker({ position: { lat: beach[1], lng: beach[2] }, map, icon: image, shape: shape, title: beach[0], zIndex: beach[3], }); } } window.initMap = initMap;
Testar amostra
Converter objetos MarkerImage
para o tipo Icon
Até a versão 3.10 da API Maps JavaScript, os ícones complexos eram definidos como objetos MarkerImage
. O literal de objeto Icon
foi incluído na versão 3.10 e substitui MarkerImage
da versão 3.11 em diante.
Os literais de objeto Icon
são compatíveis com os mesmos parâmetros que MarkerImage
. Isso possibilita converter um objeto MarkerImage
em Icon
com facilidade ao remover o construtor, unir os parâmetros anteriores em {}
e adicionar os nomes de cada parâmetro. Por exemplo:
var image = new google.maps.MarkerImage( place.icon, new google.maps.Size(71, 71), new google.maps.Point(0, 0), new google.maps.Point(17, 34), new google.maps.Size(25, 25));
se torna
var image = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25) };
Otimizar marcadores
A otimização melhora a performance ao renderizar vários marcadores como um único elemento estático. Isso é útil quando o uso de um grande número de marcadores é obrigatório. Por padrão, a API Maps JavaScript define se um marcador vai ser otimizado. Quando há um grande número de marcadores, a API Maps JavaScript tenta otimizar a renderização deles, mas às vezes isso não é possível. Desative a renderização otimizada para PNGs ou GIFs animados ou quando cada marcador precisar ser renderizado como um elemento DOM diferente. O exemplo a seguir mostra como criar um marcador otimizado:
var marker = new google.maps.Marker({ position: myLatlng, title:"Hello World!", optimized: true });
Tornar um marcador acessível
Para tornar um marcador acessível, adicione um evento de listener de clique e defina optimized
como false
. O listener de clique faz com que o marcador tenha semântica de botão, que pode ser acessado com a navegação pelo teclado, leitores de tela, entre outros. Use a opção title
para apresentar um texto acessível ao marcador.
No exemplo a seguir, o foco vai para o primeiro marcador quando a tecla "Tab" é pressionada. Use as teclas de seta para navegar entre os marcadores. Pressione "Tab" novamente para passar a outros controles do mapa. Se o marcador tiver uma janela de informações, clique nele ou pressione a tecla "Enter" ou a barra de espaços quando ele estiver selecionado para abrir. O foco retorna ao marcador associado quando a janela de informações é fechada.
TypeScript
// The following example creates five accessible and // focusable markers. function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 12, center: { lat: 34.84555, lng: -111.8035 }, } ); // Set LatLng and title text for the markers. The first marker (Boynton Pass) // receives the initial focus when tab is pressed. Use arrow keys to // move between markers; press tab again to cycle through the map controls. const tourStops: [google.maps.LatLngLiteral, string][] = [ [{ lat: 34.8791806, lng: -111.8265049 }, "Boynton Pass"], [{ lat: 34.8559195, lng: -111.7988186 }, "Airport Mesa"], [{ lat: 34.832149, lng: -111.7695277 }, "Chapel of the Holy Cross"], [{ lat: 34.823736, lng: -111.8001857 }, "Red Rock Crossing"], [{ lat: 34.800326, lng: -111.7665047 }, "Bell Rock"], ]; // Create an info window to share between markers. const infoWindow = new google.maps.InfoWindow(); // Create the markers. tourStops.forEach(([position, title], i) => { const marker = new google.maps.Marker({ position, map, title: `${i + 1}. ${title}`, label: `${i + 1}`, optimized: false, }); // Add a click listener for each marker, and set up the info window. marker.addListener("click", () => { infoWindow.close(); infoWindow.setContent(marker.getTitle()); infoWindow.open(marker.getMap(), marker); }); }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// The following example creates five accessible and // focusable markers. function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 12, center: { lat: 34.84555, lng: -111.8035 }, }); // Set LatLng and title text for the markers. The first marker (Boynton Pass) // receives the initial focus when tab is pressed. Use arrow keys to // move between markers; press tab again to cycle through the map controls. const tourStops = [ [{ lat: 34.8791806, lng: -111.8265049 }, "Boynton Pass"], [{ lat: 34.8559195, lng: -111.7988186 }, "Airport Mesa"], [{ lat: 34.832149, lng: -111.7695277 }, "Chapel of the Holy Cross"], [{ lat: 34.823736, lng: -111.8001857 }, "Red Rock Crossing"], [{ lat: 34.800326, lng: -111.7665047 }, "Bell Rock"], ]; // Create an info window to share between markers. const infoWindow = new google.maps.InfoWindow(); // Create the markers. tourStops.forEach(([position, title], i) => { const marker = new google.maps.Marker({ position, map, title: `${i + 1}. ${title}`, label: `${i + 1}`, optimized: false, }); // Add a click listener for each marker, and set up the info window. marker.addListener("click", () => { infoWindow.close(); infoWindow.setContent(marker.getTitle()); infoWindow.open(marker.getMap(), marker); }); }); } window.initMap = initMap;
Testar amostra
Animar um marcador
Crie animações em marcadores para que eles tenham movimento dinâmico em diversas circunstâncias. Se quiser especificar a forma de animação de um marcador, use a propriedade animation
do tipo google.maps.Animation
. Este valores Animation
são compatíveis:
-
DROP
indica que o marcador deve cair da parte de cima do mapa até sua posição final na primeira vez em que é posicionado no mapa. A animação termina quando o marcador para de se mover, eanimation
volta a sernull
. Geralmente, esse tipo de animação é especificado durante a criação doMarker
. -
BOUNCE
indica que o marcador deve saltar no lugar. Ele continua em movimento até que a propriedadeanimation
seja explicitamente definida comonull
.
Para iniciar uma animação em um marcador, chame setAnimation()
no objeto Marker
.
TypeScript
// The following example creates a marker in Stockholm, Sweden using a DROP // animation. Clicking on the marker will toggle the animation between a BOUNCE // animation and no animation. let marker: google.maps.Marker; function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 13, center: { lat: 59.325, lng: 18.07 }, } ); marker = new google.maps.Marker({ map, draggable: true, animation: google.maps.Animation.DROP, position: { lat: 59.327, lng: 18.067 }, }); marker.addListener("click", toggleBounce); } function toggleBounce() { if (marker.getAnimation() !== null) { marker.setAnimation(null); } else { marker.setAnimation(google.maps.Animation.BOUNCE); } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// The following example creates a marker in Stockholm, Sweden using a DROP // animation. Clicking on the marker will toggle the animation between a BOUNCE // animation and no animation. let marker; function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 13, center: { lat: 59.325, lng: 18.07 }, }); marker = new google.maps.Marker({ map, draggable: true, animation: google.maps.Animation.DROP, position: { lat: 59.327, lng: 18.067 }, }); marker.addListener("click", toggleBounce); } function toggleBounce() { if (marker.getAnimation() !== null) { marker.setAnimation(null); } else { marker.setAnimation(google.maps.Animation.BOUNCE); } } window.initMap = initMap;
Testar amostra
Quando há vários marcadores, não é recomendado colocar todos de uma vez no mapa. Use setTimeout()
para espaçar as animações dos marcadores com base em um padrão, conforme o mostrado abaixo:
function drop() { for (var i =0; i < markerArray.length; i++) { setTimeout(function() { addMarkerMethod(); }, i * 200); } }
Tornar um marcador arrastável
Quando você define draggable
como true
nas opções do marcador, os usuários podem arrastar esse elemento para um local diferente no mapa.
var myLatlng = new google.maps.LatLng(-25.363882,131.044922); var mapOptions = { zoom: 4, center: myLatlng } var map = new google.maps.Map(document.getElementById("map"), mapOptions); // Place a draggable marker on the map var marker = new google.maps.Marker({ position: myLatlng, map: map, draggable:true, title:"Drag me!" });
Outras personalizações de marcadores
Consulte o exemplo de pop-up personalizado para conferir um marcador totalmente personalizado.
Consulte bibliotecas de código aberto para informações sobre outras extensões da classe de marcadores, clustering e gerenciamento de marcadores e personalização de sobreposição.