Obiettivo
Questo documento illustra i passaggi chiave per sviluppare un'applicazione interattiva per la ricerca di negozi utilizzando Google Maps Platform, in particolare l'API Maps JavaScript e Places UI Kit: Place Details Element. Imparerai a creare una mappa che mostra le sedi dei negozi, ad aggiornare dinamicamente un elenco di negozi visibili e a visualizzare informazioni dettagliate sui luoghi per ogni negozio.
Prerequisiti
Si consiglia di avere familiarità con quanto segue:
- API Maps JavaScript: utilizzata per mostrare una mappa sulla pagina e per importare Places UI Kit.
- Indicatori avanzati: utilizzati per visualizzare gli indicatori sulla mappa.
- Places UI Kit: utilizzato per visualizzare le informazioni sui tuoi negozi nell'interfaccia utente.
Abilita l'API Maps JavaScript e Places UI Kit nel tuo progetto.
Prima di iniziare, verifica di aver caricato l'API Maps JavaScript e importato le librerie richieste per i segnaposto avanzati e Places UI Kit. Questo documento presuppone inoltre una conoscenza pratica dello sviluppo web, inclusi HTML, CSS e JavaScript.
Configurazione iniziale
Il primo passaggio consiste nell'aggiungere una mappa alla pagina. Questa mappa verrà utilizzata per mostrare i segnaposto relativi alle sedi dei tuoi negozi.
Esistono due modi per aggiungere una mappa a una pagina:
- Utilizzando un componente web HTML gmp-map
- Utilizzo di JavaScript
Scegli il metodo più adatto al tuo caso d'uso. Entrambi i modi di implementare la mappa funzioneranno con questa guida.
Carica e visualizza le sedi dei negozi
In questa sezione caricheremo e visualizzeremo i dati del tuo negozio sulla mappa. Questa guida presuppone che tu abbia un repository di informazioni sui tuoi negozi esistenti da cui attingere. I dati del negozio possono provenire da varie fonti, ad esempio dal tuo database.
Per questo esempio, supponiamo di avere un file JSON locale (stores.json) con un array di oggetti negozio, ognuno dei quali rappresenta una sede del negozio. Ogni oggetto deve contenere almeno name, location (con lat e lng) e place_id.
Esistono diversi modi per recuperare gli ID luogo delle sedi dei tuoi negozi, se non li hai già. Per saperne di più, consulta la documentazione relativa agli ID luogo.
Ecco un esempio di voce dei dettagli del negozio nel file stores.json.
Sono presenti campi per Nome, Località (lat/lng) e ID luogo. C'è un oggetto per contenere l'orario di apertura del negozio (troncato). Sono presenti anche due valori booleani per descrivere le caratteristiche personalizzate della sede del negozio.
{
"name": "Example Store Alpha",
"location": { "lat": 51.51, "lng": -0.12 },
"place_id": "YOUR_STORE_PLACE_ID",
"opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
"new_store_design": true,
"indoor_seating": false
}
Nel codice JavaScript, recupera i dati delle sedi dei tuoi negozi e visualizza un segnaposto sulla mappa per ognuna.
Di seguito è riportato un esempio di come eseguire questa operazione. Questa funzione accetta un oggetto contenente i dettagli dei negozi e crea un indicatore in base alla posizione di ciascuno.
function displayInitialMarkers(storeLocations) {
if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
storeLocations.forEach(store => {
if (store.location) {
const marker = new AdvancedMarkerElement({
position: new LatLng(store.location.lat, store.location.lng),
title: store.name
});
mapElement.appendChild(marker);
}
});
}
Dopo aver caricato i tuoi negozi e aver visualizzato sulla mappa i segnaposto che ne rappresentano le posizioni, crea una barra laterale utilizzando HTML e CSS per visualizzare i dettagli dei singoli negozi.
Ecco un esempio di come potrebbe apparire lo Store locator in questa fase:
Ascolta le modifiche all'area visibile della mappa
Per ottimizzare le prestazioni e l'esperienza utente, aggiorna l'applicazione in modo che mostri indicatori e dettagli nella barra laterale solo quando le località corrispondenti si trovano all'interno dell'area della mappa visibile (area visibile). Ciò comporta l'ascolto delle modifiche alla visualizzazione della mappa, l'eliminazione dei rimbalzi di questi eventi e il ridisegno solo degli indicatori necessari.
Collega un listener di eventi all'evento idle della mappa. Questo evento viene attivato al termine di qualsiasi operazione di panning o zoom, fornendo un viewport stabile per i calcoli.
map.addListener('idle', debounce(updateMarkersInView, 300));
Lo snippet di codice riportato sopra rimane in ascolto dell'evento idle e chiama una funzione debounce. L'utilizzo di una funzione di debounce garantisce che la logica di aggiornamento degli indicatori venga eseguita solo dopo che l'utente ha smesso di interagire con la mappa per un breve periodo, migliorando le prestazioni.
function debounce(func, delay) {
let timeoutId;
return function(...args) {
const context = this;
clearTimeout(timeoutId);
timeoutId = setTimeout(() => {
func.apply(context, args);
}, delay);
};
}
Il codice riportato sopra è un esempio di funzione di debounce. Accetta un argomento di funzione e di ritardo, che può essere visualizzato nel listener inattivo. Un ritardo di 300 ms è sufficiente per attendere che la mappa smetta di muoversi, senza aggiungere un ritardo evidente alla UI.
Una volta scaduto questo timeout, viene chiamata la funzione passata, in questo caso updateMarkersInView.
La funzione updateMarkersInView deve eseguire le seguenti azioni:
Cancella tutti gli indicatori esistenti dalla mappa
Controlla se la posizione del negozio rientra nei limiti della mappa corrente, ad esempio:
if (map.getBounds().contains(storeLatLng)) {
// logic
}
All'interno dell'istruzione if riportata sopra, scrivi il codice per visualizzare gli indicatori e i dettagli del negozio nella barra laterale, se la posizione del negozio rientra nell'area visibile della mappa.
Visualizza dettagli completi dei luoghi utilizzando l'elemento Place Details
In questa fase, l'applicazione mostra tutte le posizioni dei negozi e gli utenti possono filtrarle in base all'area visibile della mappa. Per migliorare questa esperienza, vengono aggiunti dettagli completi su ogni negozio, come foto, recensioni e informazioni sull'accessibilità, utilizzando l'elemento Place Details. Questo esempio utilizza in particolare l'elemento Place Details Compact.
Ogni sede del negozio nell'origine dati deve avere un ID luogo corrispondente. Questo ID identifica in modo univoco la località su Google Maps ed è essenziale per recuperarne i dettagli. In genere, questi ID luogo vengono acquisiti in anticipo e memorizzati per ogni record del negozio.
Integra l'elemento Place Details Compact nell'applicazione
Quando un negozio viene identificato all'interno dell'area visibile della mappa corrente e viene visualizzato nella barra laterale, puoi creare e inserire dinamicamente un elemento Place Details Compact.
Per il negozio attualmente in fase di elaborazione, recupera l'ID luogo dai tuoi dati. L'ID luogo viene utilizzato per controllare quale luogo verrà visualizzato dall'elemento.
In JavaScript, crea dinamicamente un'istanza di PlaceDetailsCompactElement. Viene inoltre creato un nuovo PlaceDetailsPlaceRequestElement, a cui viene passato l'ID luogo, che viene aggiunto a PlaceDetailsCompactElement. Infine, utilizza PlaceContentConfigElement per configurare i contenuti che verranno visualizzati dall'elemento.
La seguente funzione presuppone che le librerie Place UI Kit necessarie siano importate e disponibili nell'ambito in cui viene chiamata questa funzione e che storeData passato alla funzione contenga place_id.
Questa funzione restituirà l'elemento e il codice chiamante sarà responsabile di aggiungerlo al DOM.
function createPlaceDetailsCompactElement(storeData) {
// Create the main details component
const detailsCompact = new PlaceDetailsCompactElement();
detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'
// Specify the Place ID
const placeRequest = new PlaceDetailsPlaceRequestElement();
placeRequest.place = storeData.place_id;
detailsCompact.appendChild(placeRequest);
// Configure which content elements to display
const contentConfig = new PlaceContentConfigElement();
// For this example, we'll render media, rating, accessibility, and attribution:
contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
contentConfig.appendChild(new PlaceRatingElement());
contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
// Configure attribution
const placeAttribution = new PlaceAttributionElement();
placeAttribution.setAttribute('light-scheme-color', 'gray');
placeAttribution.setAttribute('dark-scheme-color', 'gray');
contentConfig.appendChild(placeAttribution);
detailsCompact.appendChild(contentConfig);
// Return the element
return detailsCompact;
}
Nel codice di esempio riportato sopra, l'elemento è configurato per visualizzare le foto del luogo, la valutazione delle recensioni e le informazioni sull'accessibilità. Puoi personalizzarlo aggiungendo o rimuovendo altri elementi dei contenuti disponibili. Per tutte le opzioni disponibili, consulta la documentazione di PlaceContentConfigElement.
L'elemento Place Details Compact supporta lo stile tramite proprietà personalizzate CSS. In questo modo puoi personalizzarne l'aspetto (colori, caratteri e così via) in modo che corrisponda al design della tua applicazione. Applica queste proprietà personalizzate nel file CSS. Consulta la documentazione di riferimento per PlaceDetailsCompactElement per le proprietà CSS supportate.
Ecco un esempio di come potrebbe apparire la tua richiesta in questa fase:
Migliora lo Store Finder
Hai creato una base solida per la tua applicazione di ricerca di negozi. Ora, prendi in considerazione diversi modi per estendere la sua funzionalità e creare un'esperienza ancora più ricca e incentrata sull'utente.
Aggiungi il completamento automatico
Migliora il modo in cui gli utenti trovano le aree in cui cercare i negozi integrando un input di ricerca con Place Autocomplete. Quando gli utenti digitano un indirizzo, un quartiere o un punto d'interesse e selezionano un suggerimento, programma la mappa in modo che si centri automaticamente su quella posizione, attivando un aggiornamento dei negozi vicini. Per farlo, aggiungi un campo di immissione e associa la funzionalità Place Autocomplete. Quando viene selezionato un suggerimento, la mappa può essere centrata su quel punto. Ricordati di configurarlo in modo da influenzare o limitare i risultati alla tua area operativa.
Rileva posizione
Offri una pertinenza immediata, soprattutto per gli utenti mobile, implementando la funzionalità per rilevare la loro posizione geografica attuale. Dopo aver ottenuto l'autorizzazione del browser per rilevare la posizione, centra automaticamente la mappa sulla posizione dell'utente e mostra i negozi più vicini. Gli utenti apprezzano molto questa funzionalità Nelle vicinanze quando cercano opzioni immediate. Aggiungi un pulsante o un prompt iniziale per richiedere l'accesso alla posizione.
Mostra distanza e indicazioni stradali
Una volta che un utente identifica un negozio di interesse, migliora notevolmente il suo percorso integrando l'API Routes. Per ogni negozio elencato, calcola e visualizza la distanza dalla posizione attuale dell'utente o dalla località cercata. Inoltre, fornisci un pulsante o un link che utilizzi l'API Routes per generare un percorso dalla posizione dell'utente al negozio selezionato. Puoi quindi visualizzare questo percorso sulla mappa o collegarti a Google Maps per la navigazione, creando una transizione fluida dalla ricerca di un negozio all'arrivo effettivo.
Implementando queste estensioni, puoi utilizzare più funzionalità di Google Maps Platform per creare uno Store locator più completo e pratico che risponda direttamente alle esigenze comuni degli utenti.
Conclusione
Questa guida ha illustrato i passaggi principali per creare uno strumento interattivo per trovare i negozi. Hai imparato a visualizzare le sedi dei tuoi negozi su una mappa utilizzando l'API Maps JavaScript, ad aggiornare dinamicamente i negozi visibili in base alle modifiche dell'area visibile e, soprattutto, a visualizzare i dati dei tuoi negozi in linea con il kit dell'interfaccia utente di Places. Utilizzando le informazioni esistenti sul negozio, inclusi gli ID luogo, con l'elemento Place Details, puoi presentare dettagli completi e standardizzati per ciascuna delle tue sedi, creando una base solida per uno Store locator facile da usare.
Prova l'API Maps JavaScript e Places UI Kit per offrire strumenti efficaci basati su componenti per lo sviluppo rapido di applicazioni sofisticate basate sulla posizione. Combinando queste funzionalità, puoi creare esperienze coinvolgenti e informative per i tuoi utenti.
Collaboratori
Henrik Valve | DevX Engineer