1. Prima di iniziare
Questo codelab ha lo scopo di aiutarti a capire come creare la tua prima mappa 3D utilizzando le mappe 3D fotorealistiche in Maps JavaScript. Scoprirai le nozioni di base sul caricamento dei componenti giusti dell'API Maps JavaScript, sulla visualizzazione della tua prima mappa 3D e sul disegno di elementi al suo interno.
Cosa creerai.
In questo codelab, crei un'app web 3D che esegue le seguenti operazioni:
- Carica l'API Maps JavaScript in modo dinamico.
- Viene visualizzata una mappa 3D centrata sulla CN Tower di Toronto.
- Mostra un confine intorno a una località.
- Disattiva i punti di interesse sulla mappa 3D.
- Estrusione del confine per coprire la località.
Obiettivi didattici
- Inizia a utilizzare Google Maps Platform.
- Caricamento dell'API Maps JavaScript in modo dinamico dal codice JavaScript utilizzando l'importazione di librerie dinamiche.
- Carica una mappa 3D utilizzando la classe Map3DElement.
- Utilizzo di poligoni ed estrusione per disegnare sulla mappa.
2. Prerequisiti
Per completare questo codelab, devi acquisire familiarità con gli elementi riportati di seguito. Se hai già dimestichezza con Google Maps Platform, vai al Codelab.
Prodotti Google Maps Platform obbligatori
In questo Codelab utilizzerai i seguenti prodotti Google Maps Platform:
- API Maps JavaScript
Sì, è tutto ciò che ti serve per aggiungere le mappe 3D alla tua pagina, niente di più, molto semplice.
Altri requisiti per questo codelab
Per completare questo codelab, ti serviranno i seguenti account, servizi e strumenti:
- Un account Google Cloud con la fatturazione attivata
- Una chiave API Google Maps Platform con l'API Maps JavaScript attivata
- Conoscenza di base di JavaScript, HTML e CSS
- Un editor di testo o un IDE a tua scelta per salvare una modifica di un file da visualizzare
- Un browser web per visualizzare il file durante il lavoro
3. Configurazione
Configurare Google Maps Platform
Se non hai ancora un account Google Cloud e un progetto con la fatturazione abilitata, consulta la guida Introduzione a Google Maps Platform per creare un account di fatturazione e un progetto.
- Nella console Cloud, fai clic sul menu a discesa del progetto e seleziona il progetto che vuoi utilizzare per questo codelab.
- Abilita le API e gli SDK di Google Maps Platform richiesti per questo codelab nel Google Cloud Marketplace. Per farlo, segui i passaggi descritti in questo video o in questa documentazione.
- Genera una chiave API nella pagina Credenziali di Cloud Console. Puoi seguire la procedura descritta in questo video o in questa documentazione. Tutte le richieste a Google Maps Platform richiedono una chiave API.
4. Carica l'API Maps JavaScript
Dopo aver seguito tutti i passaggi nella sezione di configurazione, puoi iniziare a creare la tua prima mappa 3D.
Crea la pagina web più semplice che tu possa immaginare.
Per prima cosa creeremo una pagina web molto semplice per ospitare tutto il codice. Puoi farlo in qualsiasi editor o piattaforma a tua scelta.
<!DOCTYPE html>
<html>
<head>
<title>3D Maps Codelab</title>
<style>
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
</body>
</html>
Aggiungi il codice e salva il file in una posizione accessibile utilizzando un nome come 3dmap.html, quindi apri il file in un browser web per visualizzare lo stato corrente della pagina e verificare se sono presenti errori.
Come per le mappe 2D, la base di Maps 3D è l'API Maps JavaScript, quindi dovrai prima caricarla.
Questa operazione può essere eseguita in diversi modi, che puoi trovare nella sezione Caricare l'API Maps JavaScript della documentazione.
In questa dimostrazione utilizzeremo il metodo di importazione della libreria dinamica più moderno, in quanto ti consente di controllare solo gli elementi da caricare, risparmiando sui dati di download e sui tempi di avvio.
Aggiungi il caricatore dinamico
Per utilizzare il caricatore dinamico, assicurati di aggiungere il seguente tag script alla tua pagina web, inserendo la tua API KEY nel punto appropriato (che hai ottenuto nel passaggio 2). Inserisci questo tag script tra le sezioni body della pagina web di base.
<script async defer>
(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: "alpha",
});
</script>
Tieni presente che in questa fase di rilascio del prodotto utilizziamo il branch alpha dell'API per accedere a Maps 3D. Contiene le funzionalità più sperimentali dei prodotti e ti consente di testare il codice con accesso in anteprima durante lo sviluppo, in modo da poterlo utilizzare al momento del rilascio.
Ora dovresti avere una pagina web di base contenente il caricatore dinamico (se apri la pagina, la visualizzazione sarà vuota, ma non dovrebbero esserci errori). Ora siamo pronti per aggiungere la mappa 3D.
Se per qualche motivo il codice non funziona, puoi andare al passaggio 6 e confrontarlo con il risultato finale per capire cosa non va.
Per scoprire perché la pagina potrebbe non funzionare, dai un'occhiata alla console degli errori nel browser per eseguire il debug del motivo. La pagina di errore fornisce istruzioni su come eseguire questa operazione per diversi browser, nonché vari messaggi di errore e alcuni motivi comuni per cui l'API potrebbe non funzionare. Questa è una buona risorsa da utilizzare durante lo sviluppo per capire cosa potrebbe non andare in un'implementazione.
5. Visualizzare una mappa
Ora è tutto pronto per aggiungere la prima mappa 3D alla pagina.
Le mappe 3D vengono create utilizzando la classe google.maps.maps3d.Map3DElement, che ci consente di creare e utilizzare istanze di mappe 3D. In questo codelab lavoreremo direttamente con l'oggetto mappa 3D anziché tramite il tag HTML.
Creare la funzione di inizializzazione e caricare la libreria
Per prima cosa creeremo una funzione che carichi l'elemento nella pagina. Osserva il codice: prima creiamo una funzione asincrona, che ci consente di assicurarci che l'intero elemento venga caricato prima di procedere con il resto del codice. Eseguiamo quindi la funzione init al caricamento della pagina.
Aggiungi questo codice dopo lo script di caricamento all'interno della sezione body della pagina.
<script>
async function init() {
const { Map3DElement, MapMode } = await google.maps.importLibrary("maps3d");
}
init();
</script>
Tieni presente che utilizziamo l'espressione await per assicurarci che la libreria venga caricata prima di procedere.
Crea l'elemento mappa 3D e specifica la posizione
A questo punto dobbiamo specificare la posizione in cui vogliamo visualizzare la mappa. Per le mappe 3D sono disponibili diversi parametri che puoi utilizzare per impostare la visualizzazione. Si riferiscono ai parametri della videocamera virtuale che descrivono ciò che stai guardando all'interno della scena.
Creiamo una vista della CN Tower simile a questa.
Per prima cosa dobbiamo specificare le coordinate che vogliamo esaminare. Sono costituite da due viste diverse
- Il punto che vogliamo esaminare, inclusa la sua altitudine.
- La distanza e la direzione della videocamera virtuale che guarda il punto.
Se guardi l'immagine seguente, puoi farti un'idea di come funzionano queste impostazioni.
Il centro dell'elemento è il punto che stai guardando, mentre l'intervallo è la distanza che ti separa dall'oggetto e l'inclinazione è l'angolo con cui stai visualizzando l'immagine. Puoi anche impostare l'inclinazione e l'imbardata dell'oggetto se vuoi controllarli, ma non li utilizzeremo qui.
Ora creeremo la mappa 3D nella pagina, aggiungendo il seguente codice alla pagina nella sezione di inizializzazione dopo l'importazione della libreria.
const map3DElement = new Map3DElement({
center: { lat: 43.6425, lng: -79.3871, altitude: 400 },
range: 1000,
tilt: 60,
mode: MapMode.HYBRID,
});
document.body.append(map3DElement);
Innanzitutto creiamo l'elemento e impostiamo i parametri di posizione appropriati, quindi aggiungiamo il componente alla pagina (se volessimo, potremmo assegnarlo a un div esistente, se presente).
Il codice dovrebbe avere ora il seguente aspetto:
<!DOCTYPE html>
<html>
<head>
<title>3D Maps Codelab</title>
<style>
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<script async defer>
(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: "alpha",
});
</script>
<script>
async function init() {
const { Map3DElement, MapMode } = await google.maps.importLibrary("maps3d");
const map3DElement = new Map3DElement({
center: { lat: 43.6425, lng: -79.3871, altitude: 400 },
range: 1000,
tilt: 60,
mode: MapMode.HYBRID
});
document.body.append(map3DElement);
}
init();
</script>
</body>
</html>
Ora possiamo salvare il file e aprire la pagina in un browser per verificare che funzioni. Dovremmo vedere la videocamera che guarda verso il basso sulla torre, come mostrato nell'immagine. Prova a giocare prima di andare avanti e aggiungere una scatola sopra la torre.
6. Aggiungere e estrudere elementi
Ora che abbiamo una mappa 3D, evidenziamo un oggetto per indicare agli utenti che si tratta di un elemento di interesse. In questo caso utilizzeremo un poligono e la funzione di estrusione per creare una scatola intorno alla CN Tower, in modo che assomigli alla visualizzazione seguente.
Nascondere il disordine
La prima cosa che potresti notare è che abbiamo disattivato i punti di interesse. In questa mappa vogliamo che l'attenzione sia attirata dalla torre stessa, quindi dobbiamo eliminare gli altri elementi visivi.
Per farlo, dobbiamo modificare il codice per nascondere le etichette. Aggiorna la riga della modalità della mappa su SATELLITE per nascondere i punti.
mode: MapMode.SATELLITE,
L'impostazione di questa proprietà disattiva le etichette sulla mappa, inclusi non solo i punti di interesse, ma anche le strade e le linee di confine, e crea una visualizzazione "pulita" della posizione.
Aggiungi e applica uno stile al poligono
Il passaggio successivo consiste nell'aggiungere il poligono alla pagina. Questa operazione può essere eseguita in due passaggi. Innanzitutto dobbiamo caricare le funzioni che contengono le informazioni richieste e poi specificare i dettagli di stile del poligono, ad esempio il colore o se deve essere visualizzato dietro altre funzionalità.
Innanzitutto, aggiungiamo le classi richieste alla pagina utilizzando la seguente riga di codice.
const { Polygon3DElement, AltitudeMode } = await google.maps.importLibrary("maps3d");
In questo modo, nella pagina vengono caricati i classi Polygon3DElement e AltitudeMode, necessari per aggiungere un oggetto poligono alla visualizzazione.
Un poligono può avere una serie di impostazioni diverse che possono controllare la visualizzazione, dalla larghezza del tratto, al colore (per nome o valore esadecimale) e all'opacità delle impostazioni di confine e riempimento, per controllare se viene mostrato dietro altri elementi o edifici, ad esempio : disegno di segmenti omessi. Puoi trovare ulteriori dettagli nella documentazione della classe Polygon3DElement.
L'altra funzionalità che dobbiamo impostare è che il poligono venga disegnato in modo estruito. Ciò significa disegnare un poligono all'altitudine impostata e poi estenderlo fino al suolo. In questo modo, al poligono viene assegnata un'altezza simile a quella di un riquadro (come puoi vedere nell'immagine sopra). Questo richiede anche di impostare la modalità di altitudine sul poligono, motivo per cui abbiamo dovuto caricare le costanti AltitudeMode sopra. Per estrudere un poligono, questo valore deve essere impostato su ABSOLUTE o RELATIVE_TO_GROUND per ottenere la posizione corretta dalle altezze sui vertici del poligono.
Il codice crea un oggetto letterale contenente queste proprietà che possono essere utilizzate per creare l'oggetto Polygon3DElement come mostrato:
const polygonOptions = {
strokeColor: "#EA433580",
strokeWidth: 4,
fillColor: "#0000FF80",
altitudeMode: "ABSOLUTE",
extruded: true,
drawsOccludedSegments: true,
}
const towerPolygon = new google.maps.maps3d.Polygon3DElement(polygonOptions);
Ora abbiamo creato l'oggetto poligono e dobbiamo anche impostare le sue coordinate geografiche. I poligoni possono avere coordinate interne ed esterne a seconda di come vengono rappresentati. innerCoordinates indica la forma degli spazi vuoti all'interno del poligono e outerCoordinates definisce il confine esterno del poligono. Poiché si tratta di un poligono e non di una linea, le coordinate devono iniziare e terminare nello stesso punto per formare una forma completa.
Puoi specificare le coordinate utilizzando un array di oggetti o letterali LatLng o LatLngAltitude e possiamo vederlo per il nostro poligono di base.
towerPolygon.outerCoordinates = [
{ lat: 43.6427196, lng: -79.3876802, altitude: 600 },
{ lat: 43.6421742, lng: -79.3869184, altitude: 600 },
{ lat: 43.643001, lng: -79.3866475, altitude: 600 },
{ lat: 43.6427196, lng: -79.3876802, altitude: 600 }
];
Ora che abbiamo configurato lo stile e le coordinate del poligono, siamo pronti per aggiungerlo alla pagina. I poligoni sono elementi secondari dell'elemento mappa e devono essere aggiunti a un oggetto mappa esistente nella pagina. Aggiungi il seguente codice alla pagina.
map3DElement.append(towerPolygon);
Una volta ottenuta, dovresti avere la seguente implementazione completa, come mostrato qui (tranne che avrà la tua chiave API). Siamo pronti per eseguire la pagina e vedere il risultato.
<!DOCTYPE html>
<html>
<head>
<title>3D Maps Codelab</title>
<style>
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<script async defer>
(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: "alpha",
});
</script>
<script>
async function init() {
const { Map3DElement, MapMode } = await google.maps.importLibrary("maps3d");
const map3DElement = new Map3DElement({
center: { lat: 43.6425, lng: -79.3871, altitude: 400 },
range: 1000,
tilt: 60,
mode: MapMode.SATELLITE,
});
const { Polygon3DElement, AltitudeMode } = await google.maps.importLibrary("maps3d");
const polygonOptions = {
strokeColor: "#EA433580",
strokeWidth: 4,
fillColor: "#0000FF80",
fillOpacity: 0.2,
altitudeMode: "ABSOLUTE",
extruded: true,
drawsOccludedSegments: true,
}
const towerPolygon = new google.maps.maps3d.Polygon3DElement(polygonOptions);
towerPolygon.outerCoordinates = [
{ lat: 43.6427196, lng: -79.3876802, altitude: 600 },
{ lat: 43.6421742, lng: -79.3869184, altitude: 600 },
{ lat: 43.643001, lng: -79.3866475, altitude: 600 },
{ lat: 43.6427196, lng: -79.3876802, altitude: 600 }
];
map3DElement.append(towerPolygon);
document.body.append(map3DElement);
}
init();
</script>
</body>
</html>
Se il codice è corretto, dovresti vedere una pagina con la seguente mappa e il seguente poligono 3D.
Hai creato correttamente la tua prima mappa 3D utilizzando Google Maps Platform, incluso il caricamento dell'API Maps JavaScript, la creazione di una mappa 3D e l'aggiunta di un poligono estruso.
7. Passaggi successivi
In questo codelab hai appreso le nozioni di base su cosa puoi fare con l'API Maps JavaScript. A questo punto, prova ad aggiungere alcune di queste funzionalità alla mappa:
- Aggiungi un pulsante per attivare e disattivare i punti d'interesse.
- Aggiungi alcune linee che mostrano un percorso da e verso luoghi diversi.
- Imposta alcune limitazioni di confine per controllare dove l'utente può spostare la visualizzazione.
- Consulta le librerie aggiuntive disponibili per l'API Maps JavaScript che attivano servizi aggiuntivi, come Places o Directions.
Per scoprire di più su come utilizzare Google Maps Platform e 3D sul web, consulta questi link: