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 di 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à:

  • Effettuato richieste HTTP agli endpoint dell'API Places (nuova o precedente).
  • Utilizzato la classe Place nell'API Maps JavaScript.
  • Gestito la risposta dell'API per eseguire il rendering delle 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 ulteriori informazioni, inclusa la limitazione di una chiave, consulta la sezione Utilizzare le chiavi API.

Aggiornare il caricamento dell'API Maps JavaScript

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

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 Place Details e l'elemento Place Details Compact sono elementi HTML che eseguono il rendering dei dettagli di un luogo.

Implementazione attuale

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

Eseguire la migrazione all'elemento Place Details

Modificare la struttura HTML

Identifica il container HTML in cui viene eseguito il rendering dei dettagli del luogo. Sostituisci gli elementi HTML personalizzati (div, span per nome, indirizzo, foto e così via) con l'elemento HTML Place Details.

Puoi scegliere tra due elementi:

  • Elemento Place Details Compact
  • Elemento Place Details

Per ulteriori informazioni su quale utilizzare, consulta la sezione Elemento Place Details.

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 codice 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.
  • Utilizzo di PlacesService().getDetails() o effettuazione di una chiamata al servizio web.
  • Specifica di un array di campi (per l'API JS) o di FieldMask (per il servizio web) per richiedere dati specifici.
  • Nella risoluzione del callback, selezione manuale degli elementi HTML e compilazione 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);
}
Nuova logica

La nuova logica prevede:

  • Recupero dell'ID luogo o dell'oggetto luogo.
  • Recupero di un riferimento all'elemento <gmp-place-details-place-request>.
  • Passaggio dell'ID luogo o dell'oggetto luogo alla proprietà place dell'elemento <gmp-place-details-place-request>.

Di seguito è riportato un esempio di come puoi implementare Place Details UI Kit nella logica JavaScript. Recupera un riferimento all'elemento Place Details. Se esiste, recupera 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);

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

  • Esegui una ricerca testuale o una Nearby Search utilizzando una richiesta HTTP o la classe Place dell'API JavaScript.
  • Specifica i parametri di query, le limitazioni o le distorsioni della località, i tipi e i campi richiesti utilizzando FieldMask.
  • Analizza la risposta dell'API, scorri l'array di luoghi e crea manualmente gli elementi dell'elenco HTML.

Modificare la struttura HTML

Identifica il container HTML in cui esegui il rendering dell'elenco dei luoghi. Sostituisci gli elementi HTML personalizzati (div, span per nome, indirizzo e così via) con l'elemento HTML Place Search.

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 Place Search viene implementato utilizzando il <gmp-place-search> componente. 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 Nearby Search.

Per definire la modalità di visualizzazione dei risultati, puoi utilizzare la <gmp-place-all-content> scorciatoia o fornire il tuo set 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 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, recupera 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>.

Poi, imposta le proprietà di questo controller per definire la ricerca. Le proprietà richieste 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 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 controller.

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

Implementare l'elemento Basic Place Autocomplete

Per gli sviluppatori che richiedono un'esperienza di ricerca senza l'interfaccia utente fornita dell'elemento Place Search, è disponibile l'elemento Basic Place Autocomplete.

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

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

Implementazione attuale

La logica esistente probabilmente prevede:

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

Eseguire la migrazione all'elemento Place Autocomplete

Modificare la struttura HTML

Identifica e rimuovi l'elemento HTML a cui colleghi il widget Autocomplete. Probabilmente utilizza un campo di immissione HTML standard.

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

Esempio di nuovo codice HTML, che utilizza l'approccio del componente web per inizializzare un elemento Basic Place Autocomplete nella pagina.

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

Adattare 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 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 recupererà un riferimento all'elemento Basic Place Autocomplete e rimarrà in ascolto degli 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ò essere utilizzato per inizializzare un'istanza dell'elemento Place Details, per visualizzare i dettagli del luogo selezionato.

Gestire la personalizzazione

Personalizzazione dell'elemento Place Details

Orientamento

L'elemento Place Details può essere sottoposto a rendering sia in orientamento orizzontale che verticale. Utilizza l'attributo orientation in gmp-place-details-compact per scegliere tra verticale e orizzontale. Ad esempio:

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

Scegliere i campi di cui eseguire il rendering

Utilizza gli elementi di contenuto per specificare i contenuti di cui eseguire il rendering all'interno dell'elemento Place Details. Ad esempio, se escludi l'elemento di contenuto <gmp-place-type> l'elemento Place Details non eseguirà il rendering del tipo di luogo del luogo selezionato. Per un elenco completo degli elementi di contenuto, consulta la PlaceContentConfigElement documentazione di riferimento.

L'aggiunta o la rimozione di campi dall'elemento Place Details non modifica il costo del rendering dell'elemento nella pagina.

Impostare gli 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 Place Search può essere sottoposto a rendering sia in orientamento orizzontale che verticale. Utilizza l'attributo orientation in <gmp-place-search> per scegliere tra verticale e orizzontale. Ad esempio:

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

Scegliere i campi di cui eseguire il rendering

Utilizza gli elementi di contenuto per specificare i contenuti di cui eseguire il rendering all'interno dell'elemento Place Search. L'elemento <gmp-place-all-content> può essere utilizzato per visualizzare tutti i contenuti oppure puoi utilizzare una selezione di tag HTML per configurare i contenuti di cui eseguire il rendering.

Se includi <gmp-place-address> all'interno di <gmp-place-content-config>, verrà eseguito il rendering solo dell'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 Basic Place Autocomplete

Impostare gli 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, imposta la proprietà background-color dell'elemento.

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

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

Gestire eventi e dati

Gli elementi di Places UI Kit sono componenti interattivi che ti consentono di rimanere in ascolto degli eventi e recuperare i dati in modo programmatico.

Rimanere in ascolto degli 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 Basic Place Autocomplete, 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 il caricamento e il rendering dell'elemento e dei relativi contenuti sono stati completati.
  • gmp-requesterror: viene 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 utilizzati o caricati.

  • Per l'elemento Place Search e l'elemento Place Details, puoi recuperare le seguenti informazioni:
    • ID luogo
    • Località (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 Basic Place Autocomplete.

Test e perfezionamento

Dopo aver integrato gli elementi di Places UI Kit, i test sono fondamentali per una transizione senza problemi e un'esperienza utente positiva. I test devono riguardare diverse aree chiave, interessando 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 a the .place property of the <gmp-place-details-place-request> element. Utilizza ID che rappresentano diversi tipi di attività (attività con informazioni aggiuntive, 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 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 il test impostando la proprietà textQuery dell'elemento <gmp-place-text-search-request> con vari input: query generiche , indirizzi specifici e query con distorsioni della località.
  • Per una Nearby Search, esegui il test impostando le locationRestriction e includedTypes proprietà dell'<gmp-place-nearby-search-request> elemento. Utilizza diverse dimensioni della località e filtri per tipo.

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 Basic Place Autocomplete, concentra i test sull'interazione dell'utente e sui dati passati 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.

Ancora più importante, 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

È essenziale eseguire test rigorosi della gestione degli errori in tutti i componenti. Simula il passaggio di ID luogo non validi o inesistenti all'elemento Place Details oppure 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 di facile utilizzo per evitare un'interfaccia utente danneggiata o confusa.