Introdução
Neste tutorial, mostramos como adicionar um mapa do Google simples com um marcador a uma página da Web. Ele foi desenvolvido para pessoas com conhecimento básico ou intermediário de HTML e CSS e que sabem um pouco de JavaScript.
Ao longo deste tutorial, você vai criar o mapa abaixo. O marcador está posicionado em Uluru (também conhecido como Ayers Rock), no Parque Nacional Uluru-Kata Tjuta.
Como começar
Estas são as três etapas para criar um mapa do Google com um marcador na sua página da Web:
Você vai precisar de um navegador da Web. Escolha uma opção conhecida na lista de navegadores compatíveis, como Google Chrome (recomendado), Firefox, Safari ou Edge, dependendo da sua plataforma.
Etapa 1: gerar uma chave de API
Nesta seção, explicamos como autenticar o app na API Maps JavaScript usando sua própria chave de API.
Siga estas etapas para gerar uma chave:
Acesse o console do Google Cloud.
Crie ou selecione um projeto.
Clique em Continuar para ativar a API e os serviços relacionados.
Na página Credenciais, gere uma chave de API e defina as restrições dela. Observação: você vai poder usar uma chave irrestrita ou com restrições a navegadores, se tiver uma.
Para evitar roubo de cota e proteger sua chave, consulte Usar chaves de API.
Ative o faturamento. Consulte Utilização e faturamento para mais informações.
Após obter a chave de API, clique em "YOUR_API_KEY" para adicioná-la a este snippet. Copie e cole a tag do script do carregador de inicialização para usá-la na sua página da Web.
<script> (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({ key: "YOUR_API_KEY", v: "weekly", // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.). // Add other bootstrap parameters as needed, using camel case. }); </script>
Etapa 2: criar uma página HTML
Este é o código de uma página HTML básica da Web:
<!doctype html>
<!--
@license
Copyright 2019 Google LLC. All Rights Reserved.
SPDX-License-Identifier: Apache-2.0
-->
<html>
<head>
<title>Add Map</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<h3>My Google Maps Demo</h3>
<!--The div element for the map -->
<div id="map"></div>
<!-- prettier-ignore -->
<script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
</body>
</html>
Essa página é bem básica, com um cabeçalho de três níveis (h3) e um único elemento div. Você pode adicionar o conteúdo que quiser à página da Web.
Entender o código
Nesta fase do exemplo, temos:
- Declarar o aplicativo como HTML5 usando a declaração
!DOCTYPE html. - Criou um elemento div chamado "map" para conter o mapa.
- Carregou a API Maps JavaScript usando o carregador bootstrap.
Declarar o aplicativo como HTML5
Recomendamos que você declare um DOCTYPE verdadeiro dentro de seu aplicativo da Web.
Nestes exemplos, declaramos nossos aplicativos como HTML5 usando o
DOCTYPE HTML5 simples, como mostrado abaixo:
<!DOCTYPE html>
A maioria dos navegadores atuais renderiza o conteúdo declarado com este DOCTYPE
no "modo padrão", o que significa que seu aplicativo precisa ter mais
compatibilidade entre navegadores. O DOCTYPE também foi projetado para ficar defasado.
Os navegadores que não o entendem, o ignoram e usam o "modo quirks" para
mostrar o conteúdo.
Alguns CSS que funcionam no modo quirks não são válidos no modo padrão. Especificamente, todos os tamanhos baseados em porcentagem precisam herdar elementos de bloco pai e, se um dos ancestrais não especificar um tamanho, supõe-se que o tamanho seja 0 x 0 pixels. Por
esse motivo, incluímos a declaração style a seguir:
<style>
#map {
height: 100%;
}
html, body {
height: 100%;
margin: 0;
padding: 0;
}
</style>Criar um elemento div
Para que o mapa apareça em uma página da Web, precisamos reservar um lugar para ele. Normalmente,
fazemos isso criando um elemento chamado div e obtendo uma referência a ele
no DOM (modelo de objeto do documento) do navegador.
Ele define uma área da página para seu mapa do Google.
<!--The div element for the map --> <div id="map"></div>
Neste estágio do tutorial, div aparece como um bloco cinza, porque você ainda não adicionou um mapa. O código abaixo descreve o CSS que define o tamanho e a cor de div.
/* Set the size of the div element that contains the map */ #map { height: 400px; /* The height is 400 pixels */ width: 100%; /* The width is the width of the web page */ }
Acima, o elemento style configura o tamanho de div. Para que o mapa fique visível, a largura e a altura de div têm que ser maiores do que zero. Neste caso, div é configurado com uma altura de 400 pixels e uma largura de 100%, que ocupa toda a página da Web. Os divs normalmente herdam a largura
do elemento contêiner. Divs vazios normalmente têm a altura 0. Por esse
motivo, sempre defina explicitamente uma altura no div.
Carregar a API Maps JavaScript
O carregador bootstrap prepara a API Maps JavaScript para o carregamento (nenhuma biblioteca é carregada até que importLibrary() seja chamado).
<script> (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({ key: "YOUR_API_KEY", v: "weekly", // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.). // Add other bootstrap parameters as needed, using camel case. }); </script>
Consulte a Etapa 3: gerar uma chave de API para saber como ter sua própria chave de API.
Etapa 3: adicionar um mapa com um marcador
Nesta seção, mostramos como carregar a API Maps JavaScript na sua página da Web e escrever seu próprio JavaScript que usa a API para adicionar um mapa com um marcador.
TypeScript
// Initialize and add the map let map; async function initMap(): Promise<void> { // The location of Uluru const position = { lat: -25.344, lng: 131.031 }; // Request needed libraries. //@ts-ignore const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary; const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary; // The map, centered at Uluru map = new Map( document.getElementById('map') as HTMLElement, { zoom: 4, center: position, mapId: 'DEMO_MAP_ID', } ); // The marker, positioned at Uluru const marker = new AdvancedMarkerElement({ map: map, position: position, title: 'Uluru' }); } initMap();
JavaScript
// Initialize and add the map let map; async function initMap() { // The location of Uluru const position = { lat: -25.344, lng: 131.031 }; // Request needed libraries. //@ts-ignore const { Map } = await google.maps.importLibrary("maps"); const { AdvancedMarkerElement } = await google.maps.importLibrary("marker"); // The map, centered at Uluru map = new Map(document.getElementById("map"), { zoom: 4, center: position, mapId: "DEMO_MAP_ID", }); // The marker, positioned at Uluru const marker = new AdvancedMarkerElement({ map: map, position: position, title: "Uluru", }); } initMap();
No código acima, as bibliotecas Map e AdvancedMarkerElement são carregadas
quando a função initMap() é chamada.
Entender o código
Neste estágio do tutorial, temos:
- Definiu uma função JavaScript que cria um mapa no div.
- Crie um
AdvancedMarkerElementpara adicionar um marcador ao mapa.
Adicionar um mapa
O código abaixo cria um objeto no mapa do Google e adiciona propriedades a ele, incluindo o centro e o nível de zoom. Consulte a documentação para conhecer outras opções de propriedades.
TypeScript
// The location of Uluru const position = { lat: -25.344, lng: 131.031 }; // Request needed libraries. //@ts-ignore const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary; const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary; // The map, centered at Uluru map = new Map( document.getElementById('map') as HTMLElement, { zoom: 4, center: position, mapId: 'DEMO_MAP_ID', } );
JavaScript
// The location of Uluru const position = { lat: -25.344, lng: 131.031 }; // Request needed libraries. //@ts-ignore const { Map } = await google.maps.importLibrary("maps"); const { AdvancedMarkerElement } = await google.maps.importLibrary("marker"); // The map, centered at Uluru map = new Map(document.getElementById("map"), { zoom: 4, center: position, mapId: "DEMO_MAP_ID", });
Há duas opções obrigatórias para cada mapa: center e zoom. No código acima, new Map() cria um novo objeto no mapa do Google. A propriedade center informa à API onde centralizar o mapa.
A propriedade zoom especifica o nível de zoom do mapa. Zero é o nível mais baixo e mostra toda a Terra. Defina o valor mais alto para aumentar o zoom em resoluções mais altas.
A disponibilização de um mapa de todo o planeta como uma única imagem exigiria um mapa imenso ou um mapa pequeno com resolução muito baixa. Como resultado, as imagens de mapa no Google Maps e na API Maps JavaScript são divididas em "blocos" e "níveis de zoom". Em níveis baixos de zoom, um pequeno conjunto de blocos de mapa cobre uma grande área. Em níveis de zoom mais altos, os blocos têm maior resolução e cobrem uma área menor. A lista a seguir mostra o nível aproximado de detalhamento que você pode esperar em cada nível de zoom:
- 1: Mundo
- 5: terra ou continente
- 10: cidade
- 15: ruas
- 20: construções
As três imagens a seguir refletem a mesma localização de Tóquio, nos níveis de zoom 0, 7 e 18.
Adicionar um marcador
O código abaixo coloca um marcador no mapa. A propriedade position define a posição dele.
TypeScript
// The marker, positioned at Uluru const marker = new AdvancedMarkerElement({ map: map, position: position, title: 'Uluru' });
JavaScript
// The marker, positioned at Uluru const marker = new AdvancedMarkerElement({ map: map, position: position, title: "Uluru", });
Exemplo de código completo
Confira o exemplo de código completo aqui:
TypeScript
// Initialize and add the map let map; async function initMap(): Promise<void> { // The location of Uluru const position = { lat: -25.344, lng: 131.031 }; // Request needed libraries. //@ts-ignore const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary; const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary; // The map, centered at Uluru map = new Map( document.getElementById('map') as HTMLElement, { zoom: 4, center: position, mapId: 'DEMO_MAP_ID', } ); // The marker, positioned at Uluru const marker = new AdvancedMarkerElement({ map: map, position: position, title: 'Uluru' }); } initMap();
JavaScript
// Initialize and add the map let map; async function initMap() { // The location of Uluru const position = { lat: -25.344, lng: 131.031 }; // Request needed libraries. //@ts-ignore const { Map } = await google.maps.importLibrary("maps"); const { AdvancedMarkerElement } = await google.maps.importLibrary("marker"); // The map, centered at Uluru map = new Map(document.getElementById("map"), { zoom: 4, center: position, mapId: "DEMO_MAP_ID", }); // The marker, positioned at Uluru const marker = new AdvancedMarkerElement({ map: map, position: position, title: "Uluru", }); } initMap();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ #map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; }
HTML
<html>
<head>
<title>Add Map</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<h3>My Google Maps Demo</h3>
<!--The div element for the map -->
<div id="map"></div>
<!-- prettier-ignore -->
<script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
</body>
</html>Testar amostra
Saiba mais sobre marcadores:
Dicas e solução de problemas
- Saiba mais sobre como receber coordenadas de latitude/longitude ou converter um endereço em coordenadas geográficas.
- É possível modificar as opções, como estilo e propriedades, para personalizar o mapa. Para mais informações sobre como personalizar mapas, leia os guias sobre estilizar e desenhar no mapa.
- Use o console de Ferramentas para desenvolvedores no navegador da Web para testar e executar o código, ler relatórios de erros e resolver problemas.
- Use estes atalhos do teclado para abrir o console no Chrome:
Command + Option + J (no Mac) ou Control + Shift + J (no Windows). Siga as etapas abaixo para gerar as coordenadas de latitude e longitude de um local no Google Maps.
- Abra o Google Maps em um navegador.
- Clique com o botão direito do mouse no local exato das coordenadas no mapa.
- Selecione O que há aqui? no menu de contexto que aparece. O mapa mostra um card na parte de baixo da tela. Veja as coordenadas de latitude e longitude na última linha dele.
Use o serviço de geocodificação para converter um endereço em coordenadas de latitude e longitude. Os guias para desenvolvedores apresentam informações detalhadas sobre como começar a usar o serviço de geocodificação.