Adottare Places UI Kit per gli utenti esistenti dell'API Places

Obiettivo: sostituisci l'implementazione dell'API Places o della classe Place con il kit UI Places.

Destinatari della guida

Sviluppatori che:

• Esecuzione di richieste HTTP agli endpoint dell'API Places (nuova o legacy).
• Utilizzo della classe Place nell'API Maps JavaScript.
• Gestione della risposta dell'API per visualizzare le informazioni sul luogo nell'interfaccia utente dell'applicazione web.

Prerequisiti

Abilita il kit UI Places nel tuo progetto Google Cloud. Puoi continuare a utilizzare la chiave API esistente o generarne una nuova per Places UI Kit. Per ulteriori informazioni, consulta Utilizzare le chiavi API, inclusa la limitazione di una chiave.

Aggiornare il caricamento dell'API Maps JavaScript

Places UI Kit richiede il metodo di caricamento dell'API Maps JavaScript Dynamic Library Import. Se utilizzi il tag di caricamento diretto dello script, questo deve essere aggiornato.

Dopo aver aggiornato lo script di caricamento per l'API Maps JavaScript, importa le librerie richieste per utilizzare Places UI Kit.

Implementare l'elemento Place Details

L'elemento Dettagli luogo e l'elemento Dettagli luogo compatti sono elementi HTML che visualizzano i dettagli di un luogo.

Implementazione attuale

• Esegui una chiamata Place Details utilizzando una richiesta HTTP o la classe Place dell'API JavaScript.
• Analizzi la risposta dell'API e visualizzi i dettagli del luogo utilizzando HTML e CSS.

Migrazione all'elemento Dettagli luogo

Modifica della struttura HTML

Identifica il contenitore HTML in cui vengono visualizzati i dettagli del luogo. Sostituisci gli elementi HTML personalizzati (div, span per nome, indirizzo, foto e così via) con l'HTML dell'elemento Dettagli luogo.

Puoi scegliere tra due elementi:

• Elemento compatto Place Details
• Elemento Place Details

Per ulteriori informazioni su quale utilizzare, consulta Elemento Dettagli luogo.

Il codice HTML esistente potrebbe avere il seguente aspetto.

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

Esempio di nuovo HTML, che indica esplicitamente quali contenuti visualizzare:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

Adattare la logica JavaScript

Logica esistente

La logica esistente probabilmente prevede:

• Recupero di un ID luogo.
• Utilizzando PlacesService().getDetails() o effettuando una chiamata al servizio web.
• Specifica un array di campi (per l'API JS) o FieldMask (per il servizio web) per richiedere dati specifici.
• Nella risoluzione del callback, selezionando manualmente gli elementi HTML e inserendo i dati ricevuti.

Di seguito è riportato un esempio di come potresti aver implementato Place Details:

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}

Nota: la logica potrebbe essere diversa se utilizzi una chiamata API REST o la libreria JavaScript legacy.

Nuova logica

La nuova logica prevede:

• Recupera l'ID luogo o l'oggetto luogo.
• Ottieni un riferimento all'elemento <gmp-place-details-place-request>.
• Trasferisci l'ID luogo o l'oggetto luogo alla proprietà luogo dell'elemento <gmp-place-details-place-request>.

Di seguito è riportato un esempio di come puoi implementare il kit UI Place Details nella logica JavaScript. Ottieni un riferimento all'elemento Dettagli del luogo. Se questo esiste, ottieni un riferimento all'elemento Richiesta di luogo di Places Details e imposta la proprietà place utilizzando un ID luogo. Nel codice HTML di esempio riportato sopra, lo stile dell'elemento Dettagli luogo è impostato su display: none. Questo valore è stato aggiornato a display: block.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

Implementare l'elemento di ricerca di luoghi

L'elemento di ricerca di luoghi è un elemento HTML che esegue il rendering dei risultati di una ricerca di luoghi in un elenco.

Implementazione attuale

• Esegui una ricerca di testo o una ricerca nelle vicinanze utilizzando una richiesta HTTP oppure utilizza la classe Place dell'API JavaScript.
• Specifichi i parametri di query, le limitazioni o i bias di località, i tipi e i campi richiesti utilizzando FieldMask.
• Analizzi la risposta dell'API, scorri l'array di luoghi e crei manualmente gli elementi dell'elenco HTML.

Migrazione all'elemento di ricerca di luoghi

Modifica della struttura HTML

Identifica il contenitore HTML in cui visualizzi l'elenco dei luoghi. Sostituisci gli elementi HTML personalizzati (div, span per nome, indirizzo e così via) con l'elemento HTML dell'elemento di ricerca di luoghi.

Il codice HTML esistente potrebbe avere il seguente aspetto:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

L'elemento di ricerca di luoghi viene implementato utilizzando il componente <gmp-place-search>. Per configurare il tipo di ricerca, includi uno dei seguenti componenti di configurazione inseriti all'interno:

• <gmp-place-text-search-request> per una ricerca testuale.
• <gmp-place-nearby-search-request> per una ricerca nelle vicinanze.

Per definire la modalità di visualizzazione dei risultati, puoi utilizzare la scorciatoia <gmp-place-all-content> o fornire il tuo insieme di singoli componenti di presentazione. Gli attributi chiave come selectable (per consentire i clic sugli elementi dell'elenco) e orientation (per un layout orizzontale o verticale) possono essere impostati direttamente sul componente principale.

Esempio di ricerca nelle vicinanze

<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>

Esempio di ricerca testuale

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

Adattare la logica JavaScript

In JavaScript, ottieni un riferimento al componente del controller di ricerca utilizzando document.querySelector(). A seconda della configurazione, questo sarà l'elemento <gmp-place-text-search-request> o <gmp-place-nearby-search-request>.

Dopodiché, imposta le proprietà di questo controller per definire la ricerca. Le proprietà obbligatorie dipendono dal tipo di ricerca che stai eseguendo.

Per una ricerca di testo (<gmp-place-text-search-request>), la proprietà principale è textQuery:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

Per una ricerca nelle vicinanze (<gmp-place-nearby-search-request>), devi definire l'area di ricerca utilizzando un locationRestriction. Puoi quindi utilizzare includedTypes per filtrare in base a tipi specifici di luoghi all'interno di quell'area:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

Il componente <gmp-place-search> principale avvia automaticamente una nuova ricerca non appena vengono impostate le proprietà richieste del controller.

• Per una ricerca di testo, la ricerca viene eseguita nel momento in cui assegni un valore a textQuery.
• Per una ricerca nelle vicinanze, la ricerca viene eseguita dopo aver fornito un locationRestriction valido.

Implementare l'elemento di completamento automatico di base di Place

Per gli sviluppatori che richiedono un'esperienza di ricerca senza la UI fornita dell'elemento di ricerca di luoghi, è disponibile l'elemento Basic Place Autocomplete.

Questo elemento è ideale per creare un campo di input di ricerca mantenendo il controllo completo su come vengono visualizzati i risultati nell'interfaccia utente personalizzata. L'unico scopo dell'elemento di completamento automatico è fornire previsioni sui luoghi man mano che l'utente digita e mostrare in modo programmatico un ID luogo per il luogo selezionato.

Non mostra alcun dettaglio né fornisce altre informazioni accessibili a livello di programmazione.

Implementazione attuale

La logica esistente probabilmente prevede:

• Rendering di un campo di immissione di testo nella pagina che chiama Place Autocomplete mentre l'utente digita, visualizzando i risultati.
• Utilizzando l'ID luogo del luogo selezionato dall'utente per recuperare ulteriori dettagli, ad esempio utilizzando l'API Place Details.
• Visualizzazione dei dettagli del luogo selezionato.

Migrazione all'elemento Place Autocomplete

Modifica della struttura HTML

Identifica e rimuovi l'elemento HTML a cui colleghi il widget di completamento automatico. Probabilmente utilizza un campo di input HTML standard.

<input id="pac-input" type="text" placeholder="Search for a location" />

Esempio di nuovo HTML, che utilizza l'approccio dei componenti web per inizializzare un elemento di completamento automatico di base di Places nella pagina.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

Adattare la logica JavaScript

La logica JavaScript probabilmente prevede la creazione del widget Autocompletamento collegato a un elemento HTML input. Questo widget rimane in ascolto dell'evento place_changed e attiva un'azione con i dati restituiti.

Esempio di codice JavaScript esistente da rimuovere:

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

La nuova logica JavaScript otterrà un riferimento all'elemento di completamento automatico di base dei luoghi e ascolterà gli eventi gmp-select:

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

Quando selezioni un luogo nel menu a discesa Completamento automatico, viene attivato l'evento gmp-select. L'ID luogo del luogo selezionato può essere recuperato dall'oggetto event. L'ID luogo può essere utilizzato per inizializzare un'istanza dell'elemento Dettagli luogo, per visualizzare i dettagli del luogo selezionato.

Personalizzazione dell'handle

Suggerimento: per indicazioni dettagliate sulla personalizzazione dell'aspetto, incluso uno strumento di stile live e i requisiti di attribuzione, consulta la documentazione relativa alla personalizzazione dello stile del kit UI di Places.

Personalizzazione dell'elemento Place Details

Orientamento

L'elemento Dettagli del luogo può essere visualizzato sia in orientamento orizzontale che verticale. Utilizza l'attributo orientation su gmp-place-details-compact per scegliere tra verticale e orizzontale. Ad esempio:

<gmp-place-details-compact orientation="vertical">

Scegli i campi da visualizzare

Utilizza gli elementi di contenuti per specificare i contenuti da visualizzare all'interno dell'elemento Dettagli luogo. Ad esempio, l'esclusione dell'elemento di contenuti <gmp-place-type> impedirebbe all'elemento Dettagli del luogo di eseguire il rendering del tipo di luogo del luogo selezionato. Per un elenco completo degli elementi dei contenuti, consulta la documentazione di riferimento di PlaceContentConfigElement.

L'aggiunta o la rimozione di campi dall'elemento Dettagli luogo non modifica il costo del rendering dell'elemento sulla pagina.

Imposta stili CSS

Sono disponibili proprietà CSS personalizzate per configurare i colori e i caratteri dell'elemento. Ad esempio, per impostare lo sfondo dell'elemento su verde, imposta la seguente proprietà CSS:

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

Per ulteriori dettagli, consulta la documentazione di riferimento per PlaceDetailsCompactElement.

Personalizzazione dell'elemento Place Search

Orientamento

L'elemento di ricerca di luoghi può essere visualizzato sia in orientamento orizzontale che verticale. Utilizza l'attributo orientation su <gmp-place-search> per scegliere tra verticale e orizzontale. Ad esempio:

<gmp-place-search orientation="horizontal" selectable>

Scegli i campi da visualizzare

Utilizza gli elementi di contenuti per specificare i contenuti da visualizzare all'interno dell'elemento di ricerca di luoghi. L'elemento <gmp-place-all-content> può essere utilizzato per visualizzare tutti i contenuti oppure è possibile utilizzare una selezione di tag HTML per configurare i contenuti visualizzati.

L'inclusione di <gmp-place-address> all'interno di <gmp-place-content-config> visualizzerebbe solo l'indirizzo di ogni luogo, ad esempio:

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Personalizzazione di base dell'elemento Place Autocomplete

Imposta stili CSS

Sono disponibili proprietà CSS personalizzate per personalizzare l'aspetto dell'elemento Completamento automatico. Ad esempio, per impostare il colore di sfondo su viola chiaro, devi impostare la proprietà background-color sull'elemento.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

Per ulteriori dettagli, consulta la documentazione di riferimento di BasicPlaceAutocompleteElement.

Gestire eventi e dati

Gli elementi del kit UI Places sono componenti interattivi che ti consentono di ascoltare gli eventi e recuperare i dati in modo programmatico.

Ascolta gli eventi

Puoi aggiungere listener di eventi agli elementi per attivare azioni in base all'interazione dell'utente o allo stato dell'elemento.

Evento di selezione

• gmp-select: questo evento viene attivato quando un utente effettua una selezione.
  • Nell'elemento di ricerca di luoghi, si attiva quando un utente fa clic su un luogo nell'elenco dei risultati.
  • Nell'elemento di completamento automatico di base dei luoghi, si attiva quando un utente fa clic su una previsione nell'elenco a discesa.

Eventi comuni

Gli elementi Ricerca luogo, Places Details e Completamento automatico base di Places supportano tutti i seguenti eventi:

• gmp-load: attivato quando l'elemento e i relativi contenuti sono stati caricati e visualizzati.
• gmp-requesterror: attivato quando una richiesta al server non va a buon fine, ad esempio a causa di una chiave API non valida.

Accedere ai dati degli elementi in modo programmatico

Puoi recuperare in modo programmatico dati specifici dagli elementi dopo che sono stati interagiti o caricati.

• Per l'elemento Ricerca luoghi e l'elemento Dettagli luogo, puoi recuperare le seguenti informazioni:
  • ID luogo
  • Posizione (latitudine e longitudine)
  • Area visibile
• Per l'elemento di completamento automatico di base del luogo, puoi recuperare le seguenti informazioni:
  • ID luogo

Tutti gli altri dati contenuti negli elementi non sono accessibili a livello di programmazione.

Per esempi più dettagliati, consulta la documentazione individuale per l'elemento di ricerca di luoghi, l'elemento di dettagli del luogo e l'elemento di completamento automatico di base dei luoghi.

Test e perfezionamento

Una volta integrati gli elementi di Places UI Kit, i test sono fondamentali per una transizione senza problemi e un'esperienza utente positiva. I test devono coprire diverse aree chiave, affrontando tutti gli elementi che hai implementato: gli elementi Place Details, Place Search e Basic Place Autocomplete.

Elemento Dettagli del luogo

Per l'elemento Dettagli del luogo, inizia verificando che i dettagli vengano visualizzati correttamente per una vasta gamma di luoghi. Esegui il test passando vari ID luogo alla proprietà .place dell'elemento <gmp-place-details-place-request>. Utilizza ID che rappresentano diversi tipi di attività (attività con dati avanzati, punti di interesse, indirizzi di base) e luoghi in diverse regioni o lingue. Presta particolare attenzione alla formattazione, al layout e alla presenza dei contenuti.

Elemento di ricerca di luoghi

Se hai implementato l'elemento di ricerca di luoghi, verifica il rendering e il comportamento in diversi scenari di ricerca.

• Per una ricerca di testo, esegui il test impostando la proprietà textQuery sull'elemento <gmp-place-text-search-request> con vari input: query generiche, indirizzi specifici e query con distorsioni della località.
• Per una ricerca nelle vicinanze, esegui il test impostando le proprietà locationRestriction e includedTypes nell'elemento <gmp-place-nearby-search-request>. Utilizza dimensioni e tipi di filtri diversi per le località.

Verifica che l'elenco venga compilato con risultati pertinenti e che l'evento gmp-select venga attivato correttamente al momento della selezione.

Elemento di base di Place Autocomplete

Per l'elemento di completamento automatico di base del luogo, concentra i test sull'interazione dell'utente e sui dati trasmessi dall'evento di selezione. Verifica che l'evento gmp-select venga attivato in modo affidabile quando un utente fa clic su una previsione. Verifica che l'oggetto event.place nel gestore eventi contenga un ID luogo valido.

Ancora più importante, testa il flusso end-to-end: seleziona un luogo dal menu a discesa del completamento automatico e verifica che il relativo ID luogo possa essere utilizzato correttamente per compilare un altro elemento, ad esempio l'elemento Dettagli luogo.

Gestione degli errori

È essenziale eseguire test rigorosi della gestione degli errori in tutti i componenti. Simula il passaggio di ID luogo non validi o inesistenti all'elemento Dettagli luogo oppure l'utilizzo di parametri di ricerca non validi per l'elemento Ricerca luogo. Attiva l'evento gmp-requesterror simulando problemi di rete o utilizzando una chiave API non valida per assicurarti che la tua applicazione lo gestisca correttamente. Implementa messaggi di errore e logging facili da usare per evitare un'interfaccia utente danneggiata o confusa.