Creare uno Store Locator interattivo con Places UI Kit

Obiettivo

Questo documento descrive i passaggi chiave per sviluppare un'applicazione interattiva di ricerca di negozi utilizzando Google Maps Platform, in particolare l'API Maps JavaScript e Places UI Kit: elemento Dettagli luogo. Scoprirai come creare una mappa che mostri le sedi dei negozi, aggiornare dinamicamente un elenco di negozi visibili e visualizzare informazioni dettagliate su ogni negozio.

Prerequisiti

Si consiglia di avere familiarità con quanto segue:

• API Maps JavaScript: utilizzata per mostrare una mappa sulla tua pagina e per importare Places UI Kit.
• Indicatori avanzati - Utilizzati per visualizzare gli indicatori sulla mappa.
• Places UI Kit - Utilizzato per visualizzare informazioni sui tuoi negozi nell'interfaccia utente.

Attiva l'API Maps JavaScript e Places UI Kit sul tuo progetto.

Prima di iniziare, verifica di aver caricato l'API Maps JavaScript e importato le librerie richieste per Advanced Markers 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 visualizzare i segnaposto relativi alle sedi del tuo negozio.

Esistono due modi per aggiungere una mappa a una pagina:

1. Utilizzare un componente web HTML gmp-map
2. Utilizzo di JavaScript

Scegli il metodo più adatto al tuo caso d'uso. Entrambi i metodi di implementazione della mappa funzionano con questa guida.

Demo

Questa demo mostra un esempio del funzionamento dello strumento di ricerca dei negozi, che visualizza 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 le sedi dei negozi

In questa sezione, caricheremo e visualizzeremo i dati del negozio sulla mappa. Questa guida presuppone che tu disponga di un repository di informazioni sui tuoi negozi esistenti da cui estrarre i dati. I dati del negozio possono provenire da varie fonti, ad esempio dal tuo database. Per questo esempio, supponiamo 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 un name, un location (con lat e lng) e un place_id.

Esistono diversi modi per recuperare gli ID luogo per le sedi del tuo negozio se non li hai già. Per ulteriori informazioni, consulta la documentazione sull'ID luogo.

Una voce di esempio dei dettagli del negozio nel file stores.json potrebbe avere questo aspetto. Sono presenti campi per nome, posizione (latitudine/longitudine) e ID luogo. Esiste un oggetto per contenere l'orario di apertura del negozio (troncato). Sono presenti anche due valori booleani per descrivere le caratteristiche personalizzate della posizione 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 negozi e mostra un segnaposto sulla mappa per ciascuna.

Ecco un esempio di come farlo. 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 visualizzato i segnaposto che ne rappresentano le sedi sulla mappa, 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 dell'area visibile della mappa

Per ottimizzare il rendimento e l'esperienza utente, aggiorna l'applicazione in modo che mostri i marcatori e i dettagli nella barra laterale solo quando le posizioni corrispondenti si trovano all'interno dell'area visibile della mappa (viewport). Ciò comporta l'ascolto delle modifiche della finestra di visualizzazione della mappa, il debouncing di questi eventi e il ridisegno solo degli indicatori necessari.

Collega un listener di eventi all'evento di inattività della mappa. Questo evento viene attivato al termine di qualsiasi operazione di panoramica o zoom, fornendo un viewport stabile per i tuoi calcoli.

map.addListener('idle', debounce(updateMarkersInView, 300));

Lo snippet di codice riportato sopra è in ascolto dell'evento idle e chiama una funzione debounce. L'utilizzo di una funzione di debounce assicura che la logica di aggiornamento dei marcatori 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 una funzione e un argomento di ritardo, che possono essere passati nel listener di inattività. Un ritardo di 300 ms è sufficiente per attendere che la mappa smetta di muoversi, senza aggiungere un ritardo notevole 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:

Cancella tutti i marcatori esistenti dalla mappa

Controlla se la posizione del negozio rientra nei limiti della mappa attuale, ad esempio:

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

All'interno dell'istruzione if riportata sopra, scrivi il codice per visualizzare i marker e i dettagli del negozio nella barra laterale, se la posizione del negozio rientra nella visualizzazione della mappa.

Visualizzare i dettagli avanzati dei luoghi utilizzando l'elemento Dettagli del luogo

In questa fase, l'applicazione mostra tutte le sedi dei negozi e gli utenti possono filtrarle in base alla visualizzazione della mappa. Per migliorare questo aspetto, vengono aggiunti dettagli avanzati su ogni negozio, come foto, recensioni e informazioni sull'accessibilità, utilizzando l'elemento Dettagli del luogo. Questo esempio utilizza in modo specifico l'elemento compatto Dettagli luogo.

Ogni sede del negozio nell'origine dati deve avere un ID luogo corrispondente. Questo ID identifica in modo univoco la posizione su Google Maps ed è essenziale per recuperarne i dettagli. In genere, acquisisci questi ID luogo in anticipo e li memorizzi in ogni record del negozio.

Integra l'elemento compatto Place Details nell'applicazione

Quando viene stabilito che un negozio si trova all'interno della finestra di visualizzazione della mappa corrente e viene visualizzato nella barra laterale, puoi creare e inserire dinamicamente un elemento compatto con i dettagli del luogo.

Per il negozio 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 creato anche un nuovo PlaceDetailsPlaceRequestElement, a cui viene passato l'ID luogo e che viene aggiunto a PlaceDetailsCompactElement. Infine, utilizza PlaceContentConfigElement per configurare i contenuti che l'elemento visualizzerà.

La seguente funzione presuppone che le librerie necessarie di Place UI Kit siano importate e disponibili nell'ambito in cui viene chiamata questa funzione e storeData passato alla funzione contenga place_id.

Questa funzione restituirà l'elemento e il codice chiamante 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 visualizzare le foto del luogo, la valutazione delle recensioni e le informazioni sull'accessibilità. Può essere personalizzato aggiungendo o rimuovendo altri elementi di contenuti disponibili. Per tutte le opzioni disponibili, consulta la documentazione relativa a PlaceContentConfigElement.

L'elemento compatto Dettagli del luogo supporta lo stile tramite proprietà personalizzate CSS. In questo modo puoi personalizzare il suo 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.

Un esempio di come potrebbe apparire la tua applicazione in questa fase:

Migliorare il localizzatore di negozi

Hai creato una base solida per l'applicazione di ricerca dei negozi. Ora, considera 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 d'interesse e selezionano un suggerimento, programma la mappa in modo che si centri automaticamente su quella posizione, attivando un aggiornamento dei negozi nelle vicinanze. Per farlo, aggiungi un campo di input e collegalo alla funzionalità di completamento automatico dei luoghi. Quando selezioni un suggerimento, la mappa può essere centrata su quel punto. Ricordati di configurarlo in modo da favorire o limitare i risultati alla tua area operativa.

Rileva posizione

Offri pertinenza immediata, soprattutto 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 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.

Mostrare distanza e indicazioni stradali

Una volta che un utente ha identificato un negozio di interesse, migliora notevolmente il suo percorso integrando l'API Routes. Per ogni negozio che elenci, calcola e mostra la distanza dalla posizione attuale dell'utente o dalla posizione 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 fluida dalla ricerca di un negozio al suo raggiungimento.

Implementando queste estensioni, puoi utilizzare più funzionalità di Google Maps Platform per creare un localizzatore di negozi più completo e pratico che risponda direttamente alle esigenze comuni degli utenti.

Conclusione

Questa guida ha illustrato i passaggi principali per creare un localizzatore di negozi interattivo. Hai imparato a visualizzare le sedi del tuo negozio su una mappa utilizzando l'API Maps JavaScript, ad aggiornare dinamicamente i negozi visibili in base alle modifiche del riquadro visibile e, soprattutto, a visualizzare i dati del tuo negozio in linea con il Places UI Kit. Utilizzando le informazioni esistenti sul negozio, inclusi gli ID luogo, con l'elemento Dettagli luogo, puoi presentare dettagli ricchi e standardizzati per ciascuna delle tue sedi, creando una base solida per un localizzatore di negozi intuitivo.

Prova l'API Maps JavaScript e Places UI Kit per offrire strumenti potenti basati su componenti per sviluppare rapidamente applicazioni sofisticate basate sulla posizione. Combinando queste funzionalità, puoi creare esperienze coinvolgenti e informative per i tuoi utenti.

Collaboratori

Henrik Valve | DevX Engineer