Carica l'API Maps JavaScript

Questa guida mostra come caricare l'API Maps JavaScript. Puoi farlo in tre modi:

Usa importazione libreria dinamica

L'importazione dinamica di librerie offre la possibilità di caricare librerie in fase di runtime. Ciò ti consente di richiedere le librerie necessarie nel momento in cui ne hai bisogno, anziché tutte contemporaneamente al momento del caricamento. Inoltre, protegge la pagina dal caricamento ripetuto dell'API Maps JavaScript.

Carica l'API Maps JavaScript aggiungendo il bootstrap in linea al codice dell'applicazione, come mostrato nello snippet seguente:

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

Puoi anche aggiungere il codice del bootstrap loader direttamente al tuo codice JavaScript.

Per caricare le librerie in fase di runtime, utilizza l'operatore await per chiamare importLibrary() dall'interno di una funzione async, come mostrato nell'esempio di codice che segue:

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

Se hai aggiunto una mappa utilizzando l'elemento gmp-map, la funzione initMap() può caricare le librerie senza dichiarare una variabile per le classi necessarie:

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

initMap();

In alternativa, puoi caricare le librerie direttamente in HTML come mostrato di seguito:

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

Scopri come eseguire la migrazione all'API Dynamic Library Upload.

Parametri obbligatori

  • key: la tua chiave API. L'API Maps JavaScript non si carica se non viene specificata una chiave API valida.

Parametri facoltativi

  • v: la versione dell'API Maps JavaScript da caricare.

  • libraries: un elenco separato da virgole di librerie dell'API Maps JavaScript aggiuntive da caricare. In genere non è consigliabile specificare un insieme fisso di librerie, ma è disponibile per gli sviluppatori che vogliono ottimizzare il comportamento di memorizzazione nella cache sul proprio sito web.

  • language: la lingua da utilizzare. Questa modifica riguarda nomi dei controlli, note sul copyright, indicazioni stradali ed etichette di controllo, nonché le risposte alle richieste di servizio. Consulta l'elenco delle lingue supportate.

  • region: il codice della regione da utilizzare. Questo modifica il comportamento della mappa in base a un determinato paese o territorio.

  • authReferrerPolicy: i clienti di Maps JS possono configurare restrizioni per i referrer HTTP nella console Cloud per limitare gli URL autorizzati a utilizzare una determinata chiave API. Per impostazione predefinita, queste restrizioni possono essere configurate per consentire l'utilizzo di una chiave API solo su determinati percorsi. Se un URL dello stesso dominio o della stessa origine può utilizzare la chiave API, puoi impostare authReferrerPolicy: "origin" in modo da limitare la quantità di dati inviati quando autorizzi le richieste dall'API Maps JavaScript. Quando questo parametro viene specificato e le restrizioni dei referrer HTTP sono attivate su Cloud Console, l'API Maps JavaScript può essere caricata solo se esiste una restrizione dei referrer HTTP che corrisponde al dominio del sito web corrente senza un percorso specificato.

  • mapIds: un array di ID mappa. Consente di precaricare la configurazione degli ID mappa specificati.

  • channel: consulta Monitoraggio dell'utilizzo per canale.

  • solutionChannel: Google Maps Platform fornisce molti tipi di codice campione per aiutarti a iniziare rapidamente. Per monitorare l'adozione dei nostri esempi di codice più complessi e migliorare la qualità della soluzione, Google include il parametro di query solutionChannel nelle chiamate API nel nostro codice campione.

Utilizzare il tag di caricamento diretto dello script

Questa sezione mostra come utilizzare il tag di caricamento diretto dello script. Poiché lo script diretto carica le librerie quando viene caricata la mappa, può semplificare le mappe create utilizzando un elemento gmp-map eliminando la necessità di richiedere esplicitamente librerie in fase di runtime. Tuttavia, fai attenzione a includerlo solo una volta per caricamento pagina.

Aggiungere un tag script

Per caricare l'API Maps JavaScript in linea in un file HTML, aggiungi un tag script come mostrato di seguito.

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

Parametri URL per il caricamento diretto dello script

In questa sezione vengono descritti tutti i parametri che puoi specificare nella stringa di query dell'URL di caricamento dello script durante il caricamento dell'API Maps JavaScript. Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come standard per gli URL, tutti i parametri vengono separati mediante il carattere della e commerciale (&).

Il seguente URL di esempio contiene segnaposto per tutti i parametri possibili:

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"

L'URL nel seguente tag script di esempio carica l'API Maps JavaScript:

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

Parametri obbligatori (diretto)

I seguenti parametri sono obbligatori durante il caricamento dell'API Maps JavaScript.

  • key: la tua chiave API. L'API Maps JavaScript non viene caricata se non viene specificata una chiave API valida.

Parametri facoltativi (diretto)

Utilizza questi parametri per richiedere una versione specifica dell'API Maps JavaScript, caricare librerie aggiuntive, localizzare la mappa o specificare il criterio di controllo dei referrer HTTP

  • loading: la strategia di caricamento del codice che l'API Maps JavaScript può utilizzare. Imposta il valore su async per indicare che l'API Maps JavaScript non è stata caricata in modo sincrono e che nessun codice JavaScript è stato attivato dall'evento load dello script. Ti consigliamo vivamente di impostare questo valore su async quando possibile per migliorare le prestazioni. Utilizza il parametro callback per eseguire azioni quando è disponibile l'API Maps JavaScript. Disponibile a partire dalla versione 3.55.

  • callback: il nome di una funzione globale da chiamare dopo il completamento del caricamento dell'API Maps JavaScript.

  • v: la versione dell'API Maps JavaScript da utilizzare.

  • libraries: un elenco separato da virgole di librerie dell'API Maps JavaScript aggiuntive da caricare.

  • language: la lingua da utilizzare. Sono interessati i nomi dei controlli, le note sul copyright, le indicazioni stradali e le etichette di controllo, nonché le risposte alle richieste di servizio. Consulta l'elenco delle lingue supportate.

  • region: il codice della regione da utilizzare. Questo modifica il comportamento della mappa in base a un determinato paese o territorio.

  • auth_referrer_policy: i clienti possono configurare restrizioni per i referrer HTTP nella console Cloud per limitare gli URL autorizzati a utilizzare una determinata chiave API. Per impostazione predefinita, queste restrizioni possono essere configurate per consentire l'utilizzo di una chiave API solo su determinati percorsi. Se un URL dello stesso dominio o della stessa origine può utilizzare la chiave API, puoi impostare auth_referrer_policy=origin in modo da limitare la quantità di dati inviati quando autorizzi le richieste dall'API Maps JavaScript. Questa funzionalità è disponibile a partire dalla versione 3.46. Quando questo parametro viene specificato e le restrizioni dei referrer HTTP sono attivate nella console Cloud, l'API Maps JavaScript può essere caricata solo se esiste una restrizione HTTP che corrisponde al dominio del sito web corrente senza un percorso specificato.

  • mapIds: un elenco di ID mappa separati da virgole. Consente di precaricare la configurazione degli ID mappa specificati.

  • channel: consulta Monitoraggio dell'utilizzo per canale.

  • solution_channel: Google Maps Platform fornisce molti tipi di codice campione per aiutarti a iniziare rapidamente. Per monitorare l'adozione dei nostri esempi di codice più complessi e migliorare la qualità della soluzione, Google include il parametro di query solution_channel nelle chiamate API nel nostro codice campione.

Utilizzo del pacchetto js-api-loader di Gestione dei partner di rete

È disponibile il pacchetto @googlemaps/js-api-loader per il caricamento tramite il gestore di pacchetti della gestione dei partner di rete. Installalo utilizzando questo comando:

npm install @googlemaps/js-api-loader

Questo pacchetto può essere importato nell'applicazione con:

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

Il caricatore mostra un'interfaccia Promise e callback. Di seguito viene illustrato l'utilizzo del metodo Promise predefinito 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

Guarda un esempio di js-api-loader.

L'esempio seguente mostra l'utilizzo di loader.importLibrary() per caricare le librerie:

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
});

Esegui la migrazione all'API Dynamic Library Import

Questa sezione illustra i passaggi necessari per eseguire la migrazione dell'integrazione in modo da utilizzare l'API Dynamic Library Import.

Passi per la migrazione

Innanzitutto, sostituisci il tag di caricamento dello script diretto con il tag del bootstrap loader in linea.

Prima

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

Dopo

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

Quindi, aggiorna il codice della tua applicazione:

  • Modifica la funzione initMap() in modo che sia asincrona.
  • Chiama importLibrary() per caricare e accedere alle librerie di cui hai bisogno.

Prima

let map;

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

window.initMap = initMap;

Dopo

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();