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, especificando 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 umLatLngque identifica o local inicial do marcador. Uma maneira de recuperar umLatLngé usando o serviço de geocodificação. -
map(opcional) especifica oMappara 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);
The marker's title will appear as a tooltip.
If you do not wish to pass any Marker options in the
marker's constructor, instead pass an empty object {} in the
last argument of the constructor.
Remove a marker
To remove a marker from the map, call the setMap() method
passing null as the argument.
marker.setMap(null);
Note that the above method does not delete the marker. It removes the
marker from the map. If instead you wish to delete the marker, you should
remove it from the map, and then set the marker itself to
null.
If you wish to manage a set of markers, you should create an array to hold
the markers. Using this array, you can then call setMap() on
each marker in the array in turn when you need to remove the markers. You
can delete the markers by removing them from the map and then setting the
array's length to 0, which removes all
references to the markers.
Customize a marker image
You can customize the visual appearance of markers by specifying an image file or vector-based icon to display instead of the default Google Maps pushpin icon. You can add text with a marker label, and use complex icons to define clickable regions, and set the stack order of markers.
Markers with image icons
In the most basic case, an icon can specify an image to use instead of the
default Google Maps pushpin icon. To specify such an icon, set the
marker's icon property to the URL of an image. The Maps JavaScript API will size the icon automatically.
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. 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));
becomes
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)
};
Optimize markers
Optimization enhances performance by rendering many markers as a single static element. This is useful in cases where a large number of markers is required. By default, the Maps JavaScript API will decide whether a marker will be optimized. When there is a large number of markers, the Maps JavaScript API will attempt to render markers with optimization. Not all Markers can be optimized; in some situations, the Maps JavaScript API may need to render Markers without optimization. Disable optimized rendering for animated GIFs or PNGs, or when each marker must be rendered as a separate DOM element. The following example shows creating an optimized marker:
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:
-
DROPindica 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, eanimationvolta a sernull. Geralmente, esse tipo de animação é especificado durante a criação doMarker. -
BOUNCEindica que o marcador deve saltar no lugar. Ele continua em movimento até que a propriedadeanimationseja explicitamente definida comonull.
Você pode iniciar uma animação em um marcador chamando 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.
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2024-06-25 UTC.