Carica l'API Maps JavaScript

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

Utilizzare l'importazione della libreria dinamica

Carica l'API Maps JavaScript aggiungendo il bootloader incorporato al codice della tua applicazione, come illustrato nel seguente snippet:

<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 bootstrap loader direttamente al tuo codice JavaScript.

Per caricare le librerie in fase di runtime, usa l'operatore await per chiamare importLibrary() da una funzione async, 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

Parametri obbligatori

  • key: la 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. Specificare un insieme fisso di librerie non è in genere consigliato, ma è disponibile per gli sviluppatori che vogliono ottimizzare con precisione il comportamento della memorizzazione nella cache sul proprio sito web.

  • 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 di regione da utilizzare. Modifica il comportamento della mappa in base a un paese o territorio specifico.

  • authReferrerPolicy: i clienti di Maps JS possono configurare 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 l'utilizzo di una chiave API solo a determinati percorsi. Se qualsiasi URL sullo stesso dominio o origine può utilizzare la chiave API, puoi impostare authReferrerPolicy: "origin" in modo da 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 restrizione dei referrer HTTP che corrisponde al dominio del sito web corrente senza un percorso specificato.

  • mapIds: un array di ID mappa. Causa il precaricamento della configurazione per gli ID mappa specificati.

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

  • solutionChannel: Google Maps Platform fornisce molti tipi di codice campione per aiutarti a iniziare a utilizzarla 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 codice campione.

Utilizza il pacchetto js-api-loader di Gestione dei partner di rete

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

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 con js-api-loader.

Nell'esempio seguente viene illustrato l'uso 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
});

Utilizzare il tag di caricamento diretto dello script

Questa sezione mostra come utilizzare il tag di caricamento diretto dello script. Google incoraggia la migrazione all'API Dynamic Library Load.

Aggiungi un tag script

Per caricare l'API Maps JavaScript 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 la 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 di esempio script 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 chiave API. L'API Maps JavaScript non verrà caricata a meno che non venga specificata una chiave API valida.

  • callback: il nome di una funzione globale da chiamare una volta completata il caricamento dell'API Maps JavaScript.

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 può essere utilizzata dall'API Maps JavaScript. Impostalo su async per indicare che l'API Maps JavaScript non è stata caricata in modo sincrono e che nessun codice JavaScript è attivato dall'evento load dello script. Ti consigliamo vivamente di impostare async, quando possibile, per migliorare le prestazioni. Utilizza 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 completata 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. Sono interessati i nomi dei controlli, le note sul copyright, le indicazioni stradali e le etichette dei controlli, nonché le risposte alle richieste di servizio. Consulta l'elenco delle lingue supportate.

  • region: il codice di regione da utilizzare. Modifica il comportamento della mappa in base a un paese o territorio specifico.

  • 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 l'utilizzo di una chiave API solo a determinati percorsi. Se qualsiasi URL sullo stesso dominio o origine può utilizzare la chiave API, puoi impostare auth_referrer_policy=origin in modo da 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.

  • mapIds: un elenco separato da virgole di ID mappa. Causa il precaricamento della 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 campione per aiutarti a iniziare a utilizzarla 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 codice campione.

Esegui la migrazione all'API Dynamic Library Import

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

Passi per la migrazione

Per prima cosa, sostituisci il tag di caricamento diretto dello script con il tag bootstrap incorporato.

Prima

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&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 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();