Obiettivo
Questo documento illustra i passaggi chiave per sviluppare un'applicazione interattiva di ricerca di negozi utilizzando Google Maps Platform, in particolare l'API Maps JavaScript e l'UI Kit di Places: Elemento dettagli sul luogo. Imparerai a creare una mappa che mostri le sedi dei negozi, aggiornare dinamicamente un elenco di negozi visibili e visualizzare informazioni dettagliate sui luoghi per ogni negozio.
Prerequisiti
È consigliata familiarità con quanto segue:
- API Maps JavaScript: utilizzata per mostrare una mappa sulla tua pagina e per importare l'UI Kit di Places.
- Indicatori avanzati: utilizzati per visualizzare gli indicatori sulla mappa.
- Places UI Kit: viene utilizzato per visualizzare informazioni sui tuoi negozi nell'interfaccia utente.
Attiva l'API Maps JavaScript e il kit UI di Places nel tuo progetto.
Prima di iniziare, verifica di aver caricato l'API Maps JavaScript e di aver importato le librerie necessarie per gli indicatori avanzati e il kit UI di Places. 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 visualizzare i segnaposto relativi alle sedi dei tuoi negozi.
Esistono due modi per aggiungere una mappa a una pagina:
- Utilizzare un componente web HTML gmp-map
- Utilizzo di JavaScript
Scegli il metodo più adatto al tuo caso d'uso. Entrambi i modi per implementare la mappa funzioneranno con questa guida.
Demo
Questa demo mostra un esempio del Ricerca negozi in azione, che mostra le sedi degli uffici di Google nella Bay Area. L'elemento Dettagli luogo viene mostrato per ogni posizione, insieme ad alcuni attributi di esempio.
Caricare e visualizzare i punti vendita
In questa sezione, caricheremo e visualizzeremo i dati del tuo negozio sulla mappa. Questa guida assume che tu abbia un repository di informazioni sui tuoi negozi esistenti da cui estrarre i dati. I dati del tuo negozio possono provenire da varie fonti, ad esempio dal tuo database.
Per questo esempio, assumiamo un file JSON locale (stores.json) con un array di oggetti store, ciascuno dei quali rappresenta una sede del negozio. Ogni oggetto deve contenere almeno un name, un location (con lat e lng) e un place_id.
Esistono diversi modi per recuperare gli ID luogo per le sedi dei tuoi negozi se non li hai già. Per ulteriori informazioni, consulta la documentazione sull'ID luogo.
Un esempio di voce dei dettagli del negozio nel file stores.json potrebbe essere il seguente.
Sono presenti campi per Nome, Posizione (lat/lng) e ID luogo. Esiste un oggetto per memorizzare l'orario di apertura del negozio (troncato). Sono presenti anche due valori booleani per
descrivere le funzionalità 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 relativi alle sedi dei tuoi negozi e mostra un segnaposto sulla mappa per ognuna.
Di seguito è riportato un esempio di come eseguire questa operazione. Questa funzione riceve 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 relativi segnaposto che ne rappresentano le sedi, crea una barra laterale utilizzando HTML e CSS per mostrare i dettagli dei singoli negozi.
Ecco un esempio di come potrebbe apparire il tuo Store Locator in questa fase:
Ascoltare le modifiche dell'area visibile della mappa
Per ottimizzare il rendimento e l'esperienza utente, aggiorna l'applicazione in modo da visualizzare i segnaposto e i dettagli nella barra laterale solo quando le relative posizioni si trovano all'interno dell'area della mappa visibile (viewport). Ciò comporta l'ascolto delle modifiche al viewport della mappa, il debouncing di questi eventi e il ricalcolo solo degli indicatori necessari.
Collega un gestore di eventi all'evento di inattività della mappa. Questo evento viene attivato al termine di eventuali operazioni di panoramica o zoom, fornendo un viewport stabile per i calcoli.
map.addListener('idle', debounce(updateMarkersInView, 300));
Lo snippet di codice riportato sopra ascolta l'evento idle e chiama una funzione debounce. L'utilizzo di una funzione di soppressione degli impulsi 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 soppressione degli impulsi. Richiede un argomento funzione e ritardo, che può essere visto come passato nell'ascoltatore inattivo. Un ritardo di 300 ms è sufficiente per attendere che la mappa smetta di muoversi, senza aggiungere un ritardo significativo all'interfaccia utente.
Una volta scaduto questo timeout, viene chiamata la funzione passata, in questo caso updateMarkersInView.
La funzione updateMarkersInView deve eseguire le seguenti azioni:
Cancellare tutti gli indicatori esistenti dalla mappa
Controlla se la sede del negozio rientra nei confini attuali della mappa, ad esempio:
if (map.getBounds().contains(storeLatLng)) {
// logic
}
All'interno dell'istruzione if riportata sopra, scrivi il codice per mostrare i segnaposto e i dettagli del negozio nella barra laterale, se la posizione del negozio rientra nell'area visibile della mappa.
Mostrare dettagli completi dei luoghi utilizzando l'elemento Place Details
In questa fase, l'applicazione mostra tutte le sedi dei negozi e gli utenti possonofiltrarle in base all'area visibile della mappa. Per migliorare questa funzionalità, vengono aggiunti dettagli completi su ogni negozio, come foto, recensioni e informazioni sull'accessibilità, utilizzando l'elemento Dettagli sul luogo. Questo esempio utilizza in modo specifico l'elemento composito Dettagli luogo.
Ogni sede del negozio nell'origine dati deve avere un ID luogo corrispondente. Questo ID identifica in modo univoco la stazione di ricarica su Google Maps ed è essenziale per recuperarne i dettagli. In genere, acquisisci questi ID luogo in anticipo e li memorizzi per ogni record del tuo negozio.
Integrare l'elemento Dettagli luogo compatto nell'applicazione
Quando un negozio è all'interno dell'area visibile della mappa corrente e viene visualizzato nella barra laterale, puoi creare e inserire dinamicamente un elemento compatto dei dettagli del luogo.
Per il negozio corrente in fase di elaborazione, recupera l'ID luogo dai tuoi dati. L'ID luogo viene utilizzato per controllare in quale luogo verrà visualizzato l'elemento.
In JavaScript, crea dinamicamente un'istanza di PlaceDetailsCompactElement. Viene inoltre creato un nuovo PlaceDetailsPlaceRequestElement, a cui viene passato l'ID posizione, 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 di chiamata sarà responsabile dell'aggiunta 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 mostrare le foto del luogo, la valutazione delle recensioni e le informazioni sull'accessibilità. Questo può essere personalizzato aggiungendo o rimuovendo altri elementi di contenuti disponibili. Consulta la documentazione di PlaceContentConfigElement per tutte le opzioni disponibili.
L'elemento Place Details Compact supporta lo stile tramite le proprietà personalizzate CSS. In questo modo puoi personalizzare l'aspetto (colori, caratteri e così via) in base al design della tua applicazione. Applica queste proprietà personalizzate nel file CSS. Consulta la documentazione di riferimento di PlaceDetailsCompactElement per conoscere le proprietà CSS supportate.
Un esempio di come potrebbe apparire la tua applicazione in questa fase:
Migliorare la ricerca dei negozi
Hai creato una base solida per la tua applicazione di ricerca di negozi. Ora, prendi in considerazione diversi modi per estenderne la 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 negozi integrando un input di ricerca con Place Autocomplete. Quando gli utenti digitano un indirizzo, un quartiere o un punto di interesse e selezionano un suggerimento, programma la mappa in modo che sia centrata automaticamente su quella posizione, attivando un aggiornamento dei negozi nelle vicinanze. Aggiungi un campo di immissione e associalo alla funzionalità di completamento automatico dei luoghi. Se selezioni un suggerimento, la mappa può essere centrata su quel punto. Ricorda di configurarlo in modo da orientare o limitare i risultati alla tua area operativa.
Rileva posizione
Offrire pertinenza immediata, in particolare per gli utenti di dispositivi mobili, 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 sua posizione 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 suo interesse, migliora notevolmente il suo percorso integrando l'API Routes. Per ogni negozio elencato, calcola e mostra la distanza dalla posizione corrente dell'utente o dalla località cercata. Inoltre, fornisci un pulsante o un link che utilizzi l'API Routes per generare un itinerario 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 senza interruzioni dalla ricerca di un negozio al suo raggiungimento.
Implementando queste estensioni, puoi utilizzare altre funzionalità della piattaforma Google Maps per creare un localizzatore dei negozi più completo e pratico che risponde direttamente alle esigenze comuni degli utenti.
Conclusione
Questa guida ha illustrato i passaggi principali per creare un ricercastore interattivo. 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 del viewport e, soprattutto, a visualizzare i dati dei tuoi negozi in linea con il kit UI di Places. Utilizzando le informazioni esistenti sui tuoi negozi, inclusi gli ID luogo, con l'elemento dettagli del luogo, puoi presentare dettagli completi e standardizzati per ciascuna delle tue sedi, creando una base solida per un comodo localizzatore dei negozi.
Prova l'API Maps JavaScript e il kit UI di Places per offrire strumenti potenti e 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