Carica l'API Maps JavaScript

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

Utilizzare l'importazione di librerie dinamiche

L'importazione di librerie dinamiche consente di caricare le librerie in fase di esecuzione. In questo modo puoi richiedere le librerie necessarie quando ti servono, anziché tutte contemporaneamente al momento del caricamento. Inoltre, impedisce alla pagina di caricare l'API Maps JavaScript più volte.

Carica l'API Maps JavaScript aggiungendo il caricatore di bootstrap incorporato 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 caricatore di bootstrap direttamente al codice JavaScript.

Per caricare le librerie in fase di esecuzione, utilizza l'operatore await per chiamare importLibrary() dall'interno di una funzione async. La dichiarazione delle variabili per le classi necessarie consente di saltare l'utilizzo di un percorso qualificato (ad es. google.maps.Map), come mostrato nel seguente esempio di codice:

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

La funzione può anche caricare le librerie senza dichiarare una variabile per le classi necessarie, il che è particolarmente utile se hai aggiunto una mappa utilizzando l'elemento gmp-map:

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

Parametri obbligatori

  • key: la tua chiave API. L'API Maps JavaScript non verrà caricata a meno che non venga specificata una chiave API valida.

Parametri facoltativi

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

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

  • language: la lingua da usare. Ciò influisce sui nomi dei controlli, sulle notifiche sul copyright, sulle indicazioni stradali e sulle etichette dei controlli, nonché sulle risposte alle richieste di servizio. Consulta l'elenco delle lingue supportate.

  • region: il codice della regione da utilizzare. In questo modo, il comportamento della mappa viene modificato in base a un determinato paese o territorio.

  • authReferrerPolicy: i clienti di Maps JS possono configurare le limitazioni dei referrer HTTP nella console Cloud per limitare gli URL che possono utilizzare una determinata chiave API. Per impostazione predefinita, queste limitazioni possono essere configurate in modo da consentire solo a determinati percorsi di utilizzare una chiave API. Se qualsiasi URL nello stesso dominio o nella stessa origine può utilizzare la chiave API, puoi impostare authReferrerPolicy: "origin" per limitare la quantità di dati inviati durante l'autorizzazione delle richieste dall'API Maps JavaScript. Quando questo parametro è specificato e le restrizioni per i referrer HTTP sono attivate nella console Cloud, l'API Maps JavaScript potrà essere caricata solo se esiste una limitazione per i 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 per gli ID mappa specificati.

  • channel: consulta la sezione Monitoraggio dell'utilizzo per canale.

  • solutionChannel: Google Maps Platform fornisce molti tipi di codice di esempio per aiutarti a iniziare a utilizzare rapidamente la piattaforma. 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 al caricamento della mappa, può semplificare le mappe create utilizzando un elemento gmp-map rimuovendo la necessità di richiedere esplicitamente le librerie in fase di esecuzione. Poiché il tag di caricamento diretto dello script carica tutte le librerie richieste contemporaneamente al caricamento dello script, il rendimento potrebbe essere interessato per alcune applicazioni. Includi il tag di caricamento diretto dello script una sola 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

Questa sezione illustra tutti i parametri che puoi specificare nella stringa di query dell'URL di caricamento dello script quando carichi l'API Maps JavaScript. Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come è standard negli URL, tutti i parametri sono separati utilizzando il carattere 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 tag script dell'esempio seguente 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 (diretti)

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

  • key: la tua chiave API. L'API Maps JavaScript non verrà caricata a meno che non venga specificata una chiave API valida.

Parametri facoltativi (diretti)

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

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

  • callback: il nome di una funzione globale da chiamare una volta caricata completamente l'API Maps JavaScript.

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

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

  • language: la lingua da usare. Ciò influisce sui nomi dei controlli, sulle notifiche sul copyright, sulle indicazioni stradali e sulle etichette dei controlli, nonché sulle risposte alle richieste di servizio. Consulta l'elenco delle lingue supportate.

  • region: il codice della regione da utilizzare. In questo modo, il comportamento della mappa viene modificato in base a un determinato paese o territorio.

  • auth_referrer_policy: i clienti possono configurare le limitazioni dei referrer HTTP nella console Cloud per limitare gli URL che possono utilizzare una determinata chiave API. Per impostazione predefinita, queste limitazioni possono essere configurate in modo da consentire solo a determinati percorsi di utilizzare una chiave API. Se qualsiasi URL nello stesso dominio o nella stessa origine può utilizzare la chiave API, puoi impostare auth_referrer_policy=origin per limitare la quantità di dati inviati durante l'autorizzazione delle richieste dall'API Maps JavaScript. Questa funzionalità è disponibile a partire dalla versione 3.46. Quando questo parametro è specificato e le restrizioni per i referrer HTTP sono attivate in Cloud Console, l'API Maps JavaScript potrà essere caricata solo se esiste una restrizione per i referrer 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 per gli ID mappa specificati.

  • channel: consulta la sezione Monitoraggio dell'utilizzo per canale.

  • solution_channel: Google Maps Platform fornisce molti tipi di codice di esempio per aiutarti a iniziare a utilizzare rapidamente la piattaforma. 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.

Utilizza il pacchetto js-api-loader di NPM

È disponibile il pacchetto @googlemaps/js-api-loader per il caricamento tramite il gestore pacchetti NPM. Installalo utilizzando il comando seguente:

npm install @googlemaps/js-api-loader

Questo pacchetto può essere importato nell'applicazione con:

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

Il caricatore espone un'interfaccia Promise e callback. Di seguito viene mostrato 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 che utilizza 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
});

Eseguire 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 diretto dello script con il tag loader di bootstrap 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>

Aggiorna il codice dell'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();