Questa pagina è stata tradotta dall'API Cloud Translation.

Che cos'è Places UI Kit e come puoi utilizzarlo per creare soluzioni coinvolgenti?

Introduzione

Per milioni di utenti in tutto il mondo, Google Maps è la fonte di riferimento per informazioni precise e aggiornate sui luoghi. Il ricco database di Google con oltre 250 milioni di luoghi in tutto il mondo, tra cui recensioni, foto e valutazioni degli utenti, offre un livello di dettaglio e affidabilità senza pari. Per fornire dati aggiornati e reali, apportiamo 100 milioni di aggiornamenti alla mappa ogni giorno.

Places UI Kit è una libreria di componenti pronta all'uso ed economica, basata sulle vaste informazioni sui luoghi di Google Maps. Ti consente di integrare l'esperienza Places affidabile e familiare di Google nei tuoi casi d'uso front-end su una mappa a tua scelta.

Componenti

Places UI Kit offre un insieme di singoli componenti UI che possono essere utilizzati in modo indipendente o insieme per creare un'esperienza Places senza interruzioni.

Dettagli del luogo: questo componente visualizza informazioni dettagliate su un luogo, come nome, indirizzo, numero di telefono, sito web, orari di apertura e recensioni degli utenti.
Ricerca di luoghi:questo componente mostra un elenco di luoghi nelle vicinanze per categoria o tramite ricerca di testo libero.
Basic Place Autocomplete:questo componente crea un campo di input di testo, presentando un elenco a discesa di luoghi previsti che corrispondono all'input.

Vantaggi principali di Places UI Kit

Facilità d'uso:incorpora l'esperienza utente affidabile di Google per Places nelle tue app con un codice minimo.
Utilizzo su qualsiasi mappa:per la prima volta, puoi utilizzare i contenuti di Places su una mappa non Google.
UI familiare: i componenti forniscono un'interfaccia utente coerente con l'esperienza di Google Maps, rendendola intuitiva per gli utenti.
Personalizzazione:Places UI Kit offre ampie opzioni di personalizzazione visiva senza costi aggiuntivi. Puoi utilizzare una serie di impostazioni e proprietà CSS personalizzate per configurare gli elementi di visualizzazione.
Conveniente:Places UI Kit può essere una soluzione più conveniente rispetto all'utilizzo diretto dell'API Places.

Casi d'uso reali

Places UI Kit può essere utilizzato in una serie di applicazioni per migliorare l'esperienza utente.

Applicazioni di scoperta locale:un'applicazione "Cose da fare" può utilizzare il componente Ricerca luoghi per mostrare un elenco di ristoranti, caffè o attrazioni nelle vicinanze. Quando un utente seleziona un luogo dall'elenco, il componente Dettagli luogo può essere utilizzato per visualizzare maggiori informazioni su quella località.
Applicazioni di pianificazione dei viaggi: un'applicazione di viaggi può utilizzare la ricerca di luoghi per consentire agli utenti di cercare hotel o punti di interesse in una città specifica. Il componente Dettagli luogo può quindi mostrare foto, valutazioni e recensioni per ogni località per facilitare la pianificazione.
Portali di ricerca di immobili e proprietà:un'applicazione immobiliare può utilizzare un componente di ricerca di luoghi per mostrare diverse categorie di luoghi nelle vicinanze per aiutare un potenziale acquirente o affittuario a capire lo stile di vita del quartiere prima di programmare una visita.
Applicazioni di messaggistica e social media: un'applicazione di messaggistica e social media può utilizzare la ricerca di luoghi per cercare e suggerire luoghi nelle vicinanze per aiutare gli utenti a trovare facilmente un luogo di incontro. Il componente Place Details può essere utilizzato per mostrare le informazioni dettagliate sui luoghi quando gli utenti li condividono. Utilizzando il pulsante Google Maps predefinito, gli utenti possono esplorare facilmente e con precisione altre località e informazioni di viaggio su Google Maps.

Personalizzazione

La ricchezza dei contenuti e gli stili dei componenti del kit UI Places possono essere personalizzati in base alle tue esigenze.

L'utilizzo di proprietà CSS personalizzate, ad esempio le proprietà CSS per il componente Dettagli luogo, ti consente di personalizzare l'aspetto dei componenti in modo che corrispondano al design della tua applicazione. Puoi personalizzare colori, caratteri e altri aspetti visivi. È importante rispettare i requisiti di attribuzione quando si apportano modifiche visive. Ad esempio, puoi modificare il colore principale utilizzato per i link e i conteggi delle recensioni con la proprietà CSS --gmp-mat-color-primary.

Puoi controllare i contenuti di un luogo specifico visualizzati utilizzando un elemento gmp-place-content-config nidificato per selezionare e configurare i contenuti oppure semplicemente utilizzando gmp-place-all-content per mostrare tutti i contenuti disponibili.

Nella documentazione è disponibile uno strumento di personalizzazione per visualizzare diverse configurazioni di stile.

Indicazioni per l'implementazione

Places UI Kit è disponibile tramite Maps JavaScript e Places SDK per Android e iOS.

Per iniziare

Per iniziare a utilizzare Places UI Kit, devi seguire questi passaggi:

Configura il tuo progetto Google Cloud: per utilizzare Places UI Kit, devi disporre di un progetto Cloud con un account di fatturazione.
Abilita Places UI Kit: devi abilitare Places UI Kit per il tuo progetto.
Ottieni una chiave API: è necessaria una chiave API per autenticare le tue richieste.

Per ulteriori dettagli specifici della piattaforma, consulta la guida introduttiva di Places UI Kit per JavaScript, Android e iOS.

Esempio di implementazione

Ecco un esempio di implementazione di una ricerca di luoghi e dei dettagli di un luogo con mappe JavaScript dinamiche. Un utente può cercare luoghi nelle vicinanze in base al testo libero. Quando fai clic su un luogo nell'elenco dei risultati di ricerca, il componente Dettagli del luogo viene visualizzato sulle mappe dinamiche.

Di seguito sono riportati gli snippet di codice. Puoi trovare la demo e il codice completo in questo repository GitHub.

Prima di iniziare, assicurati di aver completato i passaggi della sezione Introduzione riportata sopra relativi a JavaScript.

Carica le librerie richieste in HTML.

<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>

In HTML, aggiungi un contenitore della mappa, un campo di input di testo e un pulsante di ricerca. Questo contenitore conterrà le mappe dinamiche che verranno create in JavaScript. La casella di input consente agli utenti di digitare le query di ricerca.

<div id="map-container"></div>
<div class="controls">
    <input type="text" class="query-input" />
    <button class="search-button">Search</button>
</div>

Aggiungi il componente Place Search. Il componente Place Search fornisce layout orizzontali e verticali. In questo esempio utilizziamo il layout orizzontale. L'attributo "selectable" consente di fare clic sull'elemento dell'elenco dei risultati di ricerca (l'evento gmp-select viene attivato quando si fa clic).

All'interno dell'elemento gmp-place-search, aggiungiamo due elementi secondari:

gmp-place-all-content viene utilizzato per mostrare tutti i contenuti disponibili
gmp-place-text-search-request viene utilizzato per configurare l'elemento Place Search.

In questo esempio, imposteremo la configurazione in JavaScript

<div class="list-container">
    <gmp-place-search orientation="horizontal" selectable>
         <gmp-place-all-content></gmp-place-all-content>  
         <gmp-place-text-search-request></gmp-place-text-search-request>
    </gmp-place-search>
</div>

Successivamente, aggiungi il componente Dettagli luogo, disponibile nei layout compatti e completi, ciascuno dei quali supporta l'orientamento verticale e orizzontale. Questo esempio utilizza il layout orizzontale compatto. Come per il componente Place Search, aggiungiamo due elementi secondari:

gmp-place-all-content indica la visualizzazione di tutti i contenuti disponibili
gmp-place-details-place-request viene utilizzato per selezionare un luogo.

In questo esempio, imposteremo il luogo in JavaScript

<div id="details-container">
     <gmp-place-details-compact orientation="horizontal">
        <gmp-place-details-place-request></gmp-place-details-place-request> 
        <gmp-place-all-content></gmp-place-all-content>
    </gmp-place-details-compact> 
</div>

In JavaScript, importa le librerie necessarie per questo esempio. La libreria Places importa la libreria Places UI Kit per JavaScript.

const {Map} = await google.maps.importLibrary("maps");
await google.maps.importLibrary("places");
({AdvancedMarkerElement} = await google.maps.importLibrary("marker"));
({LatLngBounds, LatLng} = await google.maps.importLibrary("core"));

Crea mappe dinamiche.

const mapContainer = document.getElementById("map-container");
const mapOptions = {
    center: {lat: 37.422, lng: -122.085},
    zoom: 12 
};
const gMap = new Map(mapContainer, mapOptions);

Aggiungi un listener di clic al pulsante di ricerca per avviare una ricerca di luoghi. Quando vengono caricati i risultati di ricerca, crea indicatori per ogni luogo e aggiungi un listener di clic. Se fai clic su un indicatore, verranno richiesti e visualizzati i dettagli del luogo corrispondenti.

Quando vengono trovati dei luoghi e viene caricato l'elemento Ricerca luoghi, la proprietà places dell'elemento Ricerca luoghi viene compilata con un array di risultati. Ogni risultato è un oggetto luogo contenente il relativo ID luogo, le coordinate e l'area visibile. Per recuperare i dettagli, passa l'ID luogo o l'intero oggetto luogo all'elemento Dettagli luogo.

const queryInput = document.querySelector(".query-input");
const searchButton = document.querySelector(".search-button");
const placeSearch = document.querySelector("gmp-place-search");
const placeSearchQuery = document.querySelector("gmp-place-text-search-request");
const placeDetails = document.querySelector("gmp-place-details-compact");
const placeRequest = document.querySelector("gmp-place-details-place-request");

placeDetailsPopup = new AdvancedMarkerElement({
    map: null,
    content: placeDetails,
    zIndex: 1
});

searchButton.addEventListener("click", searchPlaces);

function searchPlaces(){    
    if (queryInput.value.trim()) {
        placeSearchQuery.textQuery = queryInput.value.trim();
        placeSearchQuery.locationBias = gMap.getBounds();
        placeSearch.addEventListener('gmp-load', addMarkers, { once: true });
    }
}

async function addMarkers(){
    const bounds = new LatLngBounds();
    placeSearch.places.forEach((place) => {
        let marker = new AdvancedMarkerElement({
            map: gMap,
            position: place.location
        });
        bounds.extend(place.location);
        marker.addListener('click',(event) => {
            placeRequest.place = place;
            placeDetails.style.display = 'block';
            placeDetailsPopup.position = place.location;
            placeDetailsPopup.map = gMap;
            gMap.fitBounds(place.viewport, {top: 200, left: 100});
        });
        gMap.setCenter(bounds.getCenter());
        gMap.fitBounds(bounds);
    });
}

Assicurati di consultare la demo e il codice completo in questo repository GitHub.

Fonti per aiutarti a creare

Collaboratori

Autori principali:

Teresa Qin | Google Maps Solutions Engineer della piattaforma

Che cos'è Places UI Kit e come puoi utilizzarlo per creare soluzioni coinvolgenti? Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.