Carica l'API Maps JavaScript

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

• Utilizza l'importazione dinamica della libreria
• Utilizza il tag di caricamento diretto dello script
• Utilizza il pacchetto js-api-loader di NPM

Utilizza l'importazione dinamica delle librerie

L'importazione dinamica delle librerie consente di caricare le librerie in fase di runtime. In questo modo puoi richiedere le librerie necessarie nel momento in cui ne hai bisogno, anziché tutte insieme al momento del caricamento. Inoltre, impedisce alla pagina di caricare l'API Maps JavaScript più volte.

Carica l'API Maps JavaScript aggiungendo il boot loader 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 boot loader direttamente al codice JavaScript.

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

async function init() {
    // Import the needed libraries.
    await google.maps.importLibrary('maps');

    // Access the map.
    const mapElement = document.querySelector('gmp-map');
    // Access the underlying map object.
    const innerMap = mapElement.innerMap;

    console.log({ mapElement, innerMap });
}

void init();
index.js

Quando la tua applicazione richiede più librerie contemporaneamente, utilizza Promise.all() per richiederle in parallelo:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

Evita di chiamare await google.maps.importLibrary() su righe separate in sequenza. Le istruzioni await sequenziali bloccano l'esecuzione finché ogni libreria non termina il download e l'inizializzazione prima di richiedere la successiva, creando una cascata di rete che aumenta il tempo di caricamento. Promise.all() avvia tutti i download delle librerie contemporaneamente e si risolve non appena sono tutti pronti.

La funzione può anche caricare librerie senza dichiarare una variabile per le classi necessarie, il che è particolarmente utile se hai aggiunto una mappa utilizzando l'elemento gmp-map. Senza la variabile, devi utilizzare percorsi completi, ad esempio google.maps.Map:

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await Promise.all([
    google.maps.importLibrary("maps"),
    google.maps.importLibrary("marker"),
  ]);

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

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. Se non specifichi esplicitamente un canale o una versione, riceverai il canale settimanale per impostazione predefinita. Se hai eseguito la migrazione dal piano Premium e non hai specificato esplicitamente un canale o una versione, riceverai il canale trimestrale per impostazione predefinita. Se specifichi una versione non valida, riceverai il canale predefinito. Scopri di più.

• libraries: un array di librerie aggiuntive dell'API Maps JavaScript per iniziare il precaricamento. In genere non è consigliabile specificare un insieme fisso di librerie, ma questa opzione è disponibile per gli sviluppatori che vogliono ottimizzare il comportamento di memorizzazione nella cache sul proprio sito web. È comunque importante chiamare google.maps.importLibrary() per ogni libreria selezionata prima dell'utilizzo.

• language: la lingua da utilizzare. Ciò influisce sui nomi dei controlli, sulle note 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 dell'API 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 autorizzati a utilizzare una determinata chiave API. Per impostazione predefinita, queste limitazioni possono essere configurate per consentire solo a determinati percorsi di utilizzare una chiave API. Se un 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 limitazioni dei referrer HTTP sono abilitate nella console Cloud, l'API Maps JavaScript potrà essere caricata solo se esiste una limitazione 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 per gli ID mappa specificati. La specifica degli ID mappa qui non è obbligatoria per l'utilizzo degli ID mappa, ma è disponibile per gli sviluppatori che vogliono ottimizzare le prestazioni della rete.

• channel: consulta Monitoraggio dell'utilizzo per canale.

Utilizza 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 le librerie in fase di runtime. Poiché il tag di caricamento diretto degli script carica tutte le librerie richieste contemporaneamente al caricamento dello script, le prestazioni potrebbero essere influenzate per alcune applicazioni. Includi il tag di caricamento diretto dello script una sola volta per caricamento pagina.

Nota: puoi chiamare importLibrary una volta completato il caricamento del tag di caricamento diretto dello script.

Aggiungi un tag di 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 di caricamento diretto dello script

Questa sezione illustra 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, altri facoltativi. Come di consueto negli URL, tutti i parametri sono separati dal carattere e commerciale (&).

L'URL di esempio seguente 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 (diretti)

I seguenti parametri sono obbligatori quando carichi l'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 il criterio 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. Ti consigliamo vivamente di impostare questo valore su async, se possibile, per migliorare le prestazioni. (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 che l'API Maps JavaScript viene caricata completamente.

• 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 utilizzare. Ciò influisce sui nomi dei controlli, sulle note 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 dell'API 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 autorizzati a utilizzare una determinata chiave API. Per impostazione predefinita, queste limitazioni possono essere configurate per consentire solo a determinati percorsi di utilizzare una chiave API. Se un 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 limitazioni dei referrer HTTP sono abilitate nella console Cloud, l'API Maps JavaScript potrà essere caricata solo se esiste una limitazione dei referrer HTTP che corrisponde al dominio del sito web corrente senza un percorso specificato.

• map_ids: un elenco separato da virgole di ID mappa. Consente di precaricare la configurazione per gli ID mappa specificati. La specifica degli ID mappa qui non è obbligatoria per l'utilizzo degli ID mappa, ma è disponibile per gli sviluppatori che vogliono ottimizzare le prestazioni della rete.

• channel: consulta Monitoraggio dell'utilizzo per canale.

Utilizza il pacchetto js-api-loader di NPM

Suggerimento: la release v2.0.0 è un refactoring importante che sostituisce la vecchia classe Loader con un'API composta da due funzioni, setOptions() e importLibrary(). Questo cambiamento ti consente di caricare dinamicamente on demand singole librerie dell'API Maps, posticipando i download delle funzionalità per migliorare le prestazioni iniziali della pagina.

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

npm install @googlemaps/js-api-loader

Importa il pacchetto come mostrato qui:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
index.js

Il loader utilizza le Promise per rendere disponibili le librerie. Carica le librerie utilizzando il metodo importLibrary(). L'esempio seguente mostra l'utilizzo del loader per caricare una mappa:

TypeScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init(): Promise<void> {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map')!, mapOptions);
}

void init();
index.ts

Nota: leggi la guida sull'utilizzo di TypeScript e Google Maps.

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';

const API_KEY = 'GOOGLE_MAPS_API_KEY';

async function init() {
    // Set loader options.
    setOptions({
        key: API_KEY,
    });

    // Load the Maps library.
    const { Map } = await importLibrary('maps');

    // Set map options.
    const mapOptions = {
        center: { lat: 48.8566, lng: 2.3522 },
        zoom: 3,
    };

    // Declare the map.
    new Map(document.getElementById('map'), mapOptions);
}

void init();
index.js

Visualizza il codice di esempio completo.

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 diretto dello script con il tag del boot loader incorporato.

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>

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

Carica più librerie

Per caricare più di una libreria, utilizza Promise.all() per richiedere le librerie in parallelo e destrutturare le classi restituite:

const [{ Place }, { AdvancedMarkerElement }] = await Promise.all([
  google.maps.importLibrary('places'),
  google.maps.importLibrary('marker'),
]);

Non caricare le librerie in serie concatenando istruzioni await separate:

// Avoid loading libraries serially:
const { Place } = await google.maps.importLibrary('places');
const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

Quando await ogni chiamata importLibrary() una dopo l'altra, la seconda richiesta della libreria non viene avviata finché la prima libreria non è stata completamente scaricata e inizializzata. L'utilizzo di Promise.all() avvia tutte le richieste della libreria contemporaneamente, riducendo la latenza di rete e migliorando la velocità di inizializzazione.