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

Scopri come eseguire la migrazione dell'implementazione esistente dell'API Places o della classe Place ai componenti del Places UI Kit.

Destinatari della guida

Questa guida è rivolta agli sviluppatori che hanno un'implementazione esistente che utilizza l'API Places e sono interessati ad aggiornare il codice per utilizzare Places UI Kit. Sarà più utile se hai già:

• Effettuare richieste HTTP agli endpoint dell'API Places (nuova o precedente).
• 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 Places UI Kit nel tuo progetto Google Cloud. Puoi continuare a utilizzare la chiave API esistente o generarne una nuova per Places UI Kit. Per saperne di più, consulta Utilizza le chiavi API, incluse le informazioni su come limitare una chiave.

Aggiorna il caricamento dell'API Maps JavaScript

Places UI Kit richiede il metodo di caricamento dell'API Maps JavaScript Importazione dinamica della libreria. Se utilizzi il tag di caricamento diretto dello script, devi aggiornarlo.

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

Implementa l'elemento Place Details

Place Details Element e Place Details Compact Element sono elementi HTML che mostrano 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 mostri i dettagli del luogo utilizzando HTML e CSS.

Migrazione all'elemento Place Details

Modifica la struttura HTML

Identifica il container HTML in cui vengono visualizzati i Place Details. Sostituisci gli elementi HTML personalizzati (div, span per nome, indirizzo, foto e così via) con l'HTML dell'elemento Place Details.

Puoi scegliere tra due elementi:

• Elemento Place Details Compact
• Elemento Place Details

Per saperne di più su quale utilizzare, consulta Elemento Place Details.

Il tuo 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 codice HTML che indica esplicitamente quali contenuti mostrare:

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

Adatta 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, seleziona manualmente gli elementi HTML e compilali con 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>.
• Passa l'ID luogo o l'oggetto Place alla proprietà place nell'elemento <gmp-place-details-place-request>.

Di seguito è riportato un esempio di come implementare il kit UI di Place Details nella logica JavaScript. Ottieni un riferimento all'elemento Place Details. Se esiste, ottieni un riferimento all'elemento Place Details Place Request e imposta la proprietà place utilizzando un ID luogo. Nel codice HTML di esempio riportato sopra, lo stile dell'elemento Place Details è impostato su display: none. Questo valore viene 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);

Implementa l'elemento Place Search

L'elemento Place Search è un elemento HTML che visualizza i risultati di una ricerca di luoghi in un elenco.

Implementazione attuale

• Esegui una ricerca testuale o una Nearby Search utilizzando una richiesta HTTP o la classe Place dell'API JavaScript.
• Puoi specificare i parametri di query, le limitazioni o le preferenze di località, i tipi e i campi richiesti utilizzando FieldMask.
• Analizzi la risposta dell'API, esegui l'iterazione dell'array di luoghi e crei manualmente gli elementi dell'elenco HTML.

Migrazione all'elemento Place Search

Modifica la 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 Place Search Element.

Il tuo 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 Place Search viene implementato utilizzando il componente <gmp-place-search>. Per configurare il tipo di ricerca, includi uno dei seguenti componenti di configurazione con slot all'interno:

• <gmp-place-text-search-request> per una ricerca testuale.
• <gmp-place-nearby-search-request> per una richiesta di Nearby Search.

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

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

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

Adatta la logica JavaScript

Nel codice JavaScript, ottieni un riferimento al componente del controller di ricerca utilizzando document.querySelector(). A seconda della configurazione, si tratta dell'elemento <gmp-place-text-search-request> o <gmp-place-nearby-search-request>.

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

Per una Ricerca testuale (<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 Nearby Search (<gmp-place-nearby-search-request>), devi definire l'area di ricerca utilizzando un locationRestriction. Puoi quindi utilizzare includedTypes per filtrare 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 principale <gmp-place-search> avvia automaticamente una nuova ricerca non appena vengono impostate le proprietà richieste del relativo controller.

• Per una Ricerca testuale, la ricerca viene eseguita nel momento in cui assegni un valore a textQuery.
• Per una ricerca Nearby Search, la ricerca viene eseguita dopo che è stato fornito un locationRestriction valido.

Implementa l'elemento Basic Place Autocomplete

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

Questo elemento è ideale per creare un campo di immissione di ricerca, mantenendo al contempo il controllo completo sulla modalità di visualizzazione dei risultati nell'interfaccia utente personalizzata. L'unica responsabilità dell'elemento Autocomplete è fornire previsioni dei luoghi man mano che l'utente digita ed esporre in modo programmatico un ID luogo per il luogo selezionato.

Non mostra alcun dettaglio né fornisce altre informazioni accessibili in modo programmatico.

Implementazione attuale

La logica esistente probabilmente prevede:

• Eseguire il rendering di un campo di immissione testo nella pagina che chiama Place Autocomplete mentre l'utente digita, visualizzando i risultati.
• Utilizzare 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 la struttura HTML

Identifica e rimuovi l'elemento HTML a cui colleghi il widget Autocomplete. È probabile che utilizzi un campo di immissione 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 Place Autocomplete di base nella pagina.

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

Adatta la logica JavaScript

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

Esempio di 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 Place Autocomplete di base 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 Autocomplete, viene attivato l'evento gmp-select. L'ID luogo del luogo selezionato può essere recuperato dall'oggetto event. L'ID luogo può quindi essere utilizzato per inizializzare un'istanza dell'elemento Place Details per visualizzare i dettagli del luogo selezionato.

Personalizzazione dell'handle

Suggerimento: per indicazioni dettagliate sulla personalizzazione dell'aspetto, tra cui uno strumento di stile in tempo reale e i requisiti di attribuzione, consulta la documentazione relativa allo stile personalizzato di Places UI Kit.

Personalizzazione dell'elemento Place Details

Orientamento

L'elemento Place Details può essere visualizzato sia in orizzontale che in 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 dei contenuti per specificare i contenuti da visualizzare all'interno dell'elemento Place Details. Ad esempio, l'esclusione dell'elemento dei contenuti <gmp-place-type> impedisce all'elemento Place Details di eseguire il rendering del tipo di 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 Place Details non modifica il costo di 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

Il rendering dell'elemento Place Search può essere eseguito 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 dei contenuti per specificare i contenuti da visualizzare all'interno dell'elemento Place Search. 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.

Se includi <gmp-place-address> all'interno di <gmp-place-content-config>, verrà visualizzato 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 dell'elemento Place Autocomplete di base

Imposta stili CSS

Sono disponibili proprietà CSS personalizzate per personalizzare l'aspetto dell'elemento Autocomplete. 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.

Gestisci eventi e dati

Gli elementi di Places UI Kit 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 Place Search, viene attivato quando un utente fa clic su un luogo nell'elenco dei risultati.
  • Nell'elemento Place Autocomplete di base, viene attivato quando un utente fa clic su una previsione nell'elenco a discesa.

Eventi comuni

Gli elementi Place Search, Place Details e Basic Place Autocomplete supportano tutti i seguenti eventi:

• gmp-load: viene attivato quando l'elemento e i relativi contenuti hanno terminato il caricamento e il rendering.
• gmp-requesterror: viene attivato quando una richiesta al server non va a buon fine, ad esempio a causa di una chiave API non valida.

Accedi ai dati degli elementi in modo programmatico

Puoi recuperare in modo programmatico dati specifici dagli elementi dopo che sono stati caricati o dopo che l'utente ha interagito con questi.

• Per l'elemento Place Search e l'elemento Place Details, puoi recuperare le seguenti informazioni:
  • ID luogo
  • Posizione (latitudine e longitudine)
  • Area visibile
• Per l'elemento Basic Place Autocomplete, puoi recuperare le seguenti informazioni:
  • ID luogo

Tutti gli altri dati contenuti negli elementi non sono accessibili in modo programmatico.

Per esempi più dettagliati, consulta la documentazione individuale per l'elemento Place Search, l'elemento Place Details e l'elemento Place Autocomplete di base.

Test e perfezionamento

Dopo aver integrato gli elementi di Places UI Kit, i test sono fondamentali per una transizione fluida e un'esperienza utente positiva. I test devono coprire diverse aree chiave, prendendo in considerazione tutti gli elementi che hai implementato: Place Details, Place Search e Basic Place Autocomplete.

Elemento Place Details

Per l'elemento Place Details, 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 informazioni aggiuntive, punti d'interesse, indirizzi di base) e luoghi in regioni o lingue diverse. Presta molta attenzione alla formattazione, al layout e alla presenza dei contenuti.

Elemento Place Search

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

• Per una Ricerca testuale, esegui un test impostando la proprietà textQuery sull'elemento <gmp-place-text-search-request> con vari input: query generiche, indirizzi specifici e query con bias di località.
• Per una ricerca Nearby Search, esegui un test impostando le proprietà locationRestriction e includedTypes sull'elemento <gmp-place-nearby-search-request>. Utilizza filtri per dimensioni e tipi di località diversi.

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

Elemento Basic Place Autocomplete

Per l'elemento Place Autocomplete di base, concentrati sui test dell'interazione dell'utente e dei 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 di eventi contenga un ID luogo valido.

Soprattutto, testa il flusso end-to-end: seleziona un luogo dal menu a discesa Autocomplete e verifica che il relativo ID luogo possa essere utilizzato correttamente per compilare un altro elemento, ad esempio l'elemento Place Details.

Gestione degli errori

I test rigorosi della gestione degli errori sono essenziali per tutti i componenti. Simula il passaggio di ID luogo non validi o inesistenti all'elemento Place Details o l'utilizzo di parametri di ricerca non validi per l'elemento Place Search. Attiva l'evento gmp-requesterror simulando problemi di rete o utilizzando una chiave API non valida per assicurarti che l'applicazione lo gestisca correttamente. Implementa messaggi di errore e logging facili da usare per evitare un'UI non funzionante o confusa.