Carica l'API Maps JavaScript

Questa guida illustra come caricare l'API Maps JavaScript. Esistono tre modi per farlo:

Utilizzare 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 contemporaneamente al tempo di caricamento. Inoltre, protegge la pagina dal caricamento dell'API Maps JavaScript più volte.

Carica l'API Maps JavaScript aggiungendo il caricatore di 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 caricatore di bootstrap 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 evitare di utilizzare un percorso qualificato (ad es. google.maps.Map), come mostrato nell'esempio di codice seguente:

let map;
async function initMap() {
    const { Map, RenderingType } = (await google.maps.importLibrary('maps'));
    map = new Map(document.getElementById('map'), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
        renderingType: RenderingType.VECTOR,
    });
}
initMap();
index.js

La tua 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. Senza la variabile devi utilizzare percorsi qualificati, ad esempio google.maps.Map:

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

async function initMap() {
  await google.maps.importLibrary("maps");
  await 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 qui:

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

Scopri come eseguire la migrazione all'API di caricamento dinamico delle librerie.

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 array di librerie aggiuntive dell'API Maps JavaScript da iniziare a precaricare. 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. È comunque importante chiamare google.maps.importLibrary() per ogni libreria selezionata prima dell'uso.

  • language: la lingua da utilizzare. Questo 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 regione da utilizzare. Questo modifica il comportamento dell'API in base a un determinato paese o territorio.

  • authReferrerPolicy: i clienti di Maps JS possono configurare le restrizioni del referrer HTTP nella console Cloud per limitare gli URL autorizzati a utilizzare una determinata chiave API. Per impostazione predefinita, queste restrizioni possono essere configurate in modo da consentire solo a determinati percorsi di utilizzare una chiave API. Se qualsiasi URL sullo stesso dominio o 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 viene specificato e le restrizioni del referrer HTTP sono abilitate nella console Cloud, l'API Maps JavaScript potrà essere caricata solo se esiste una restrizione del referrer HTTP che corrisponde al dominio del sito web corrente senza un percorso specificato.

  • mapIds: un array di ID mappa. Fa sì che la configurazione degli ID mappa specificati venga precaricata. 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.

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 runtime. Poiché il tag di caricamento diretto dello 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 solo una volta per caricamento pagina.

Aggiungere 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 sono facoltativi. Come di consueto negli URL, tutti i parametri sono separati utilizzando il carattere di "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 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) {:.hide-from-toc}

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) {:.hide-from-toc}

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

  • loading: la strategia di caricamento del codice che l'API Maps JavaScript può utilizzare. Imposta 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. È vivamente consigliabile impostare questo valore su async ogni volta che è 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 completato il caricamento dell'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 utilizzare. Questo 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 regione da utilizzare. Questo modifica il comportamento dell'API in base a un determinato paese o territorio.

  • auth_referrer_policy: i clienti possono configurare le restrizioni del referrer HTTP nella console Cloud per limitare gli URL autorizzati a utilizzare una determinata chiave API. Per impostazione predefinita, queste restrizioni possono essere configurate in modo da consentire solo a determinati percorsi di utilizzare una chiave API. Se qualsiasi URL sullo stesso dominio o 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 opzione è disponibile a partire dalla versione 3.46. Quando questo parametro viene specificato e le restrizioni del referrer HTTP sono abilitate nella console Cloud, l'API Maps JavaScript potrà essere caricata solo se esiste una restrizione del referrer HTTP che corrisponde al dominio del sito web corrente senza un percorso specificato.

  • map_ids: un elenco separato da virgole di ID mappa. Fa sì che la configurazione degli ID mappa specificati venga precaricata. 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.

  • internal_usage_attribution_ids: un elenco separato da virgole di ID di attribuzione dell'utilizzo che aiutano Google a capire quali librerie ed esempi sono utili agli sviluppatori, ad esempio l'utilizzo di una libreria di clustering degli indicatori. Per disattivare l'invio dell'ID di attribuzione dell'utilizzo, puoi eliminare questa proprietà o sostituire il valore con una stringa vuota. Verranno inviati solo i valori univoci. Per ulteriori informazioni, consulta il parametro delle soluzioni di Google Maps Platform.

Utilizzare il pacchetto NPM js-api-loader

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:

import { setOptions, importLibrary } from "@googlemaps/js-api-loader"

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

TypeScript

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

const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';

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

    // 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.
    const map = new Map(
        document.getElementById('map') as HTMLElement,
        mapOptions
    );
}

initMap();
index.ts

JavaScript

// Import the needed libraries.
import { setOptions, importLibrary } from '@googlemaps/js-api-loader';
const API_KEY = 'AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8';
async function initMap() {
    // Set loader options.
    setOptions({
        key: API_KEY,
        v: 'weekly',
    });
    // 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.
    const map = new Map(document.getElementById('map'), mapOptions);
}
initMap();
index.js

Vedi il codice di esempio completo.

Eseguire la migrazione all'API di importazione dinamica delle librerie

Questa sezione illustra i passaggi necessari per eseguire la migrazione dell'integrazione in modo da utilizzare l'API di importazione dinamica delle librerie.

Passi per la migrazione

Innanzitutto, sostituisci il tag di caricamento diretto dello script con il tag del caricatore 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>

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