Carregar a API Maps JavaScript

Neste guia, mostramos como carregar a API Maps JavaScript. Existem três maneiras de fazer isso:

Usar a API Dynamic Library Import

A importação dinâmica de biblioteca oferece a capacidade de carregar bibliotecas no momento da execução. Isso permite que você solicite as bibliotecas necessárias no momento em que elas são necessárias, em vez de todas de uma só vez no momento do carregamento. Ela também protege sua página contra o carregamento da API Maps JavaScript várias vezes.

Para carregar a API Maps JavaScript, adicione um carregador bootstrap inline ao código do aplicativo, como mostrado no snippet a seguir:

<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>

Também é possível incluir o código do carregador bootstrap diretamente no código JavaScript.

Para carregar bibliotecas no momento da execução, use o operador await para chamar importLibrary() em uma função async. Declarar variáveis para as classes necessárias permite pular o uso de um caminho qualificado (por exemplo, google.maps.Map), conforme mostrado no exemplo de código abaixo:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.js

A função também pode carregar bibliotecas sem declarar uma variável para as classes necessárias, o que é especialmente útil se você adicionou um mapa usando o elemento gmp-map:

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

Como alternativa, carregue as bibliotecas diretamente no HTML, conforme mostrado aqui:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Saiba como migrar para a API Dynamic Library Loading.

Parâmetros obrigatórios

  • key: sua chave de API. A API Maps JavaScript só é carregada quando uma chave de API válida é especificada.

Parâmetros opcionais

  • v: a versão da API Maps JavaScript que será carregada.

  • libraries: uma lista separada por vírgulas de outras bibliotecas da API Maps JavaScript que serão carregadas. Em geral, não é recomendável especificar um conjunto fixo de bibliotecas, mas talvez seja útil para desenvolvedores interessados em ajustar o comportamento de armazenamento em cache no próprio site.

  • language: o idioma que será usado. Isso afeta os nomes de controles, notificações de direitos autorais, rotas de carro e etiquetas de controle, além das respostas às solicitações de serviço. Consulte a lista de idiomas compatíveis.

  • region: o código da região a ser usado. Esse parâmetro muda o comportamento do mapa com base em um determinado país ou território.

  • authReferrerPolicy: os clientes do Maps JS podem configurar restrições de referenciadores HTTP no console do Cloud e assim limitar os URLs com permissão para usar uma determinada chave de API. Por padrão, essas restrições são configuradas para que apenas alguns caminhos possam usar uma chave de API. Se qualquer URL no mesmo domínio ou origem puder usar a chave de API, defina o parâmetro authReferrerPolicy: "origin" para limitar a quantidade de dados enviados ao autorizar solicitações da API Maps JavaScript. Quando esse parâmetro for especificado, só vai ser possível carregar a API Maps JavaScript se as restrições de referenciadores HTTP estiverem ativadas e uma delas corresponder ao domínio do site atual sem um caminho definido.

  • mapIds: uma matriz de IDs de mapa. Faz com que a configuração dos IDs de mapa especificados seja pré-carregada.

  • channel: consulte Rastreamento de uso por canal.

  • solutionChannel: a Plataforma Google Maps oferece muitos tipos de exemplo de código para que você comece a usar o produto rapidamente. O Google inclui o parâmetro de consulta solutionChannel nas chamadas de API no exemplo de código para acompanhar a implementação dos exemplos mais complexos e melhorar a qualidade da solução.

Usar a tag de carregamento de script direto

Esta seção mostra como usar a tag de carregamento direto de script. Como o script direto carrega bibliotecas quando o mapa é carregado, ele pode simplificar os mapas criados usando um elemento gmp-map, removendo a necessidade de solicitar bibliotecas explicitamente no momento de execução. Como a tag de carregamento de script direto carrega todas as bibliotecas solicitadas de uma só vez, o desempenho pode ser afetado em alguns aplicativos. Inclua a tag de carregamento direto de script apenas uma vez por carregamento de página.

Adicionar uma tag de script

Para carregar a API Maps JavaScript inline em um arquivo HTML, adicione uma tag script, como mostrado abaixo.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Parâmetros de URL de carregamento de script direto

Nesta seção, abordamos todos os parâmetros que podem ser especificados na string de consulta referente ao URL de carregamento do script ao carregar a API Maps JavaScript. Alguns parâmetros são obrigatórios, outros são opcionais. Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&).

O URL de exemplo a seguir tem marcadores de posição para todos os parâmetros possíveis:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

O URL no exemplo de tag script a seguir carrega a API Maps JavaScript:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Parâmetros obrigatórios (diretos)

Estes são os parâmetros obrigatórios ao carregar a API Maps JavaScript.

  • key: sua chave de API. A API Maps JavaScript só é carregada quando uma chave de API válida é especificada.

Parâmetros opcionais (diretos)

Use estes parâmetros para solicitar uma versão específica da API Maps JavaScript, carregar outras bibliotecas, localizar seu mapa ou especificar a política sobre verificação do referenciador HTTP.

  • loading: a estratégia de carregamento de código que a API Maps JavaScript pode usar. Defina como async para indicar que a API Maps JavaScript não foi carregada de forma síncrona e que nenhum código JavaScript é acionado pelo evento load do script. É altamente recomendável definir esse valor como async sempre que possível para melhorar a performance. Use o parâmetro callback para realizar ações quando a API Maps JavaScript estiver disponível. Disponível a partir da versão 3.55.

  • callback: o nome de uma função global que será chamada após o carregamento completo da API Maps JavaScript.

  • v: a versão da API Maps JavaScript a ser usada.

  • libraries: uma lista separada por vírgulas de outras bibliotecas da API Maps JavaScript a serem carregadas.

  • language: o idioma a ser usado. Esse parâmetro afeta os nomes de controles, notificações de direitos autorais, rotas de carro e rótulos de controle, além das respostas às solicitações de serviço. Consulte a lista de idiomas compatíveis.

  • region: o código da região a ser usado. Esse parâmetro muda o comportamento do mapa com base em um determinado país ou território.

  • auth_referrer_policy: os clientes podem configurar restrições de referenciadores HTTP no console do Cloud para limitar os URLs com permissão para usar uma determinada chave de API. Por padrão, essas restrições são configuradas para que apenas alguns caminhos possam usar uma chave de API. Se qualquer URL no mesmo domínio ou origem puder usar a chave de API, defina auth_referrer_policy=origin para limitar a quantidade de dados enviados ao autorizar solicitações da API Maps JavaScript. Disponível a partir da versão 3.46. Quando esse parâmetro for especificado, só vai ser possível carregar a API Maps JavaScript se as restrições de referenciadores HTTP estiverem ativadas e uma delas corresponder ao domínio do site atual sem um caminho definido.

  • mapIds: uma lista separada por vírgulas de IDs de mapas. Faz com que a configuração dos IDs de mapa especificados seja pré-carregada.

  • channel: consulte Rastreamento de uso por canal.

  • solution_channel: a Plataforma Google Maps oferece muitos tipos de exemplo de código para que você comece a usar o produto rapidamente. O Google inclui o parâmetro de consulta solution_channel nas chamadas de API no exemplo de código para acompanhar a implementação dos exemplos mais complexos e melhorar a qualidade da solução.

Usar o pacote js-api-loader do NPM

O pacote @googlemaps/js-api-loader (link em inglês) está disponível para carregamento usando o gerenciador de pacotes do NPM. Instale-o com o seguinte comando:

npm install @googlemaps/js-api-loader

Esse pacote pode ser importado para o aplicativo com:

import { Loader } from "@googlemaps/js-api-loader"

O carregador expõe uma interface de callback e promessa. Confira a seguir o uso do método de promessa padrão load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

Confira um exemplo com js-api-loader.

O exemplo a seguir mostra como usar loader.importLibrary() para carregar bibliotecas:

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

Migrar para a API Dynamic Library Import

Nesta seção, abordamos as etapas necessárias para migrar a integração e usar a API Dynamic Library Import.

Etapas da migração

Primeiro, substitua a tag de carregamento de script direto pela tag inline do carregador bootstrap.

Antes

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&callback=initMap">
</script>

Depois

<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>

Em seguida, atualize o código do aplicativo:

  • Mude a função initMap() para ser assíncrona.
  • Chame importLibrary() para carregar e acessar as bibliotecas necessárias.

Antes

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

Depois

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();