Questa guida mostra come caricare l'API Maps JavaScript. Là puoi farlo in tre modi:
- Utilizzare l'importazione dinamica della libreria
- Utilizza il tag di caricamento diretto dello script
- Utilizzare il pacchetto js-api-loader di Gestione dei partner di rete
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 ti servono, anziché rispetto a tutte contemporaneamente al momento di caricamento. Inoltre, protegge la pagina dal caricamento l'API Maps JavaScript più volte.
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, usa l'operatore await
per chiamare importLibrary()
da una funzione async
. Dichiarare le variabili per le classi necessarie consente
salti utilizzando un percorso qualificato (ad es. google.maps.Map
), come mostrato
nell'esempio di codice riportato di seguito:
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();
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();
La funzione può anche caricare librerie senza dichiarare una variabile
per le classi necessarie, il che è particolarmente utile se hai aggiunto una mappa utilizzando
gmp-map
elemento:
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 verrà caricato se non viene specificata una chiave API valida.
Parametri facoltativi
v
: la versione di API Maps JavaScript da caricare.libraries
: un elenco separato da virgole di API Maps JavaScript aggiuntive librerie da caricare. Specificare un un insieme fisso di librerie non è generalmente consigliato, ma è disponibile per sviluppatori che vogliono ottimizzare con precisione il comportamento di memorizzazione nella cache sul proprio sito web.language
: la lingua da utilizzare per gli utilizzi odierni. Riguarda nomi dei controlli, note sul copyright, indicazioni stradali, etichette di controllo e controllo, nonché le risposte alle richieste di servizio. Consulta le elenco delle lingue supportate.region
: la regione il codice da utilizzare. Modifica il comportamento della mappa in base a un determinato paese o territorio.authReferrerPolicy
: i clienti di Maps JS possono configurare il referrer HTTP Restrizioni nella console Cloud per limitare gli URL autorizzati a utilizzare un chiave API specifica. Per impostazione predefinita, queste restrizioni possono essere configurate solo alcuni percorsi per usare una chiave API. Se esiste un URL sullo stesso dominio o sulla stessa origine può usare la chiave API, puoi impostareauthReferrerPolicy: "origin"
per limitare quantità di dati inviati durante l'autorizzazione delle richieste dall'API Maps JavaScript. Quando questo parametro è specificato e le restrizioni dei referrer HTTP sono attivate su Cloud Console, l'API Maps JavaScript potrà essere caricata solo se è presente una restrizione dei referrer HTTP che corrisponda 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 a utilizzarla rapidamente. Per monitorare l'adozione delle nostre best practice di esempi di codice e migliorare la qualità delle soluzioni, Google include Parametro di querysolutionChannel
nelle chiamate API del nostro codice campione.
Utilizzare il tag di caricamento diretto dello script
Questa sezione mostra come utilizzare il tag di caricamento diretto dello script. Poiché l'implementazione diretta
lo script 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 all'indirizzo
runtime. Poiché il tag di caricamento diretto dello script carica tutte le librerie richieste
una volta caricato lo script, le prestazioni potrebbero risentirne per alcune
diverse applicazioni. Includi il tag di caricamento diretto dello script solo una volta per caricamento pagina.
Aggiungere un tag script
Per caricare l'API Maps JavaScript in linea in un file HTML, aggiungi un elemento
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 query
stringa dell'URL di caricamento dello script durante il caricamento dell'API Maps JavaScript.
Alcuni parametri sono obbligatori, mentre altri sono facoltativi. Come standard in
Negli URL, tutti i parametri sono separati dal 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"
®ion="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. La L'API Maps JavaScript non viene caricata se non è presente una chiave API valida specificato.
Parametri facoltativi (diretto)
Utilizza questi parametri per richiedere una versione specifica dell'API Maps JavaScript, caricare librerie aggiuntive, localizzare la mappa o specificare il controllo dei referrer HTTP norme
loading
: la strategia di caricamento del codice che l'API Maps JavaScript può utilizzare. Imposta il valore suasync
per indicare che l'API Maps JavaScript non è stata caricata in modo sincrono e che nessun codice JavaScript è stato attivato dall'eventoload
dello script. Ti consigliamo vivamente di impostare questo valore suasync
quando possibile per migliorare le prestazioni. Utilizza il parametrocallback
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 una volta l'API Maps JavaScript viene caricato completamente.v
: la versione dell'API Maps JavaScript per l'utilizzo.libraries
: un elenco separato da virgole di API Maps JavaScript aggiuntive librerie da caricare.language
: la lingua da utilizzare per gli utilizzi odierni. Riguarda nomi dei controlli, note sul copyright, indicazioni stradali, etichette di controllo e controllo, nonché le risposte alle richieste di servizio. Consulta le elenco delle lingue supportate.region
: la regione il codice da utilizzare. Modifica il comportamento della mappa in base a un determinato paese o territorio.auth_referrer_policy
: i clienti possono configurare il referrer HTTP Restrizioni nella console Cloud per limitare gli URL autorizzati a utilizzare un chiave API specifica. Per impostazione predefinita, queste restrizioni possono essere configurate solo alcuni percorsi per usare una chiave API. Se esiste un URL sullo stesso dominio o sulla stessa origine può usare la chiave API, puoi impostareauth_referrer_policy=origin
per limitare 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 dei referrer HTTP sono attivate su Cloud Console, l'API Maps JavaScript potrà essere caricata solo se esiste una restrizione dei referrer HTTP che corrisponde al dominio del sito web corrente senza specificare un percorso.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 a utilizzarla rapidamente. Per monitorare l'adozione delle nostre best practice di esempi di codice e migliorare la qualità delle soluzioni, Google include Parametro di querysolution_channel
nelle chiamate API del nostro codice campione.
Utilizzo del pacchetto js-api-loader di Gestione dei partner di rete
L'elemento @googlemaps/js-api-loader per il caricamento tramite il gestore di pacchetti della Gestione pacchetti di Gestione dei partner di rete. Installalo utilizzando 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. Quanto segue dimostra
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, }); });
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, }); });
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 al fine di utilizzare l'API Dynamic Library Import.
Passi per la migrazione
Innanzitutto, sostituisci il tag di caricamento dello script diretto con il bootstrap loader in linea. del tag.
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();