Adopta el kit de IU de Places para los usuarios existentes de la API de Places

Obtén información para migrar tu implementación existente de la API de Places o la clase Place a los componentes del kit de IU de Places.

¿A quién está dirigida esta guía?

Esta guía está dirigida a los desarrolladores que tienen una implementación existente con la API de Places y quieren actualizar su código para usar el kit de IU de Places. Será más útil si ya tienes los siguientes conocimientos:

  • Realizar solicitudes HTTP a los extremos de la API de Places (nueva o heredada)
  • Usa la clase Place en la API de Maps JavaScript.
  • Controlar la respuesta de la API para renderizar la información de lugares en la IU de tu aplicación web

Requisitos previos

Habilita el kit de IU de Places en tu proyecto de Google Cloud. Puedes seguir usando tu clave de API existente o generar una nueva para el kit de IU de Places. Consulta Cómo usar claves de API para obtener más información, incluida la restricción de una clave.

Actualiza la carga de la API de Maps JavaScript

El kit de IU de Places requiere el método de importación dinámica de bibliotecas para cargar la API de Maps JavaScript. Si usas la etiqueta de carga de la secuencia de comandos directa, debes actualizarla.

Una vez que hayas actualizado la secuencia de comandos de carga de la API de Maps JavaScript, importa las bibliotecas necesarias para usar el kit de IU de Places.

Implementa el elemento Place Details

Los elementos Place Details y Place Details Compact son elementos HTML que renderizan detalles de un lugar.

Implementación actual

  • Realizas una llamada a Place Details con una solicitud HTTP o usas la clase Place de la API de JavaScript.
  • Analizas la respuesta de la API y muestras los detalles del lugar con HTML y CSS.

Migración al elemento Place Details

Modifica la estructura HTML

Identifica el contenedor HTML en el que se renderizan los detalles del lugar. Reemplaza tus elementos HTML personalizados (divs, spans para el nombre, la dirección, las fotos, etc.) por el HTML del elemento Place Details.

Hay dos elementos para elegir:

  • Elemento Place Details Compact
  • Elemento Place Details

Para obtener más información sobre cuál usar, consulta Elemento Place Details.

Tu HTML existente puede verse de la siguiente manera.

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

Ejemplo de HTML nuevo, en el que se indica de forma explícita qué contenido se debe mostrar:

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

Adapta la lógica de JavaScript

Lógica existente

Es probable que tu lógica existente incluya lo siguiente:

  • Recupera un ID de lugar.
  • Usar PlacesService().getDetails() o realizar una llamada de servicio web
  • Especificar un array de campos (para la API de JS) o una FieldMask (para el servicio web) para solicitar datos específicos
  • En la resolución de devolución de llamada, selecciona manualmente tus elementos HTML y compleméntalos con los datos recibidos.

A continuación, se muestra un ejemplo de cómo puedes implementar 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);
}
Nueva lógica

Tu nueva lógica incluirá lo siguiente:

  • Recupera tu ID de lugar o el objeto Place.
  • Obtén una referencia al elemento <gmp-place-details-place-request>.
  • Pasa el ID de lugar o el objeto Place a la propiedad place en el elemento <gmp-place-details-place-request>.

A continuación, se muestra un ejemplo de cómo puedes implementar el kit de IU de Place Details en tu lógica de JavaScript. Obtén una referencia al elemento Place Details. Si existe, obtén una referencia al elemento Place Request de Place Details y establece la propiedad place con un ID de lugar. En el código HTML de ejemplo anterior, el estilo del elemento Place Details se establece en display: none. Se actualizó 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);

El elemento Place Search es un elemento HTML que renderiza los resultados de una búsqueda de lugares en una lista.

  • Realizas una Text Search o una Nearby Search con una solicitud HTTP, o bien usas la clase Place de la API de JavaScript.
  • Especifica los parámetros de consulta, las restricciones o preferencias de ubicación, los tipos y los campos solicitados con FieldMask.
  • Analizas la respuesta de la API, iteras el array de lugares y creas manualmente elementos de lista HTML.

Modifica la estructura HTML

Identifica el contenedor HTML en el que renderizas tu lista de lugares. Reemplaza tus elementos HTML personalizados (divs, spans para el nombre, la dirección, etc.) por el elemento HTML Place Search Element.

Tu HTML existente puede verse de la siguiente manera:

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

El elemento Place Search se implementa con el componente <gmp-place-search>. Para configurar el tipo de búsqueda, incluye uno de los siguientes componentes de configuración con ranuras:

  • <gmp-place-text-search-request> para una búsqueda de texto.
  • <gmp-place-nearby-search-request> para una búsqueda de Nearby Search

Para definir cómo se muestran los resultados, puedes usar el acceso directo <gmp-place-all-content> o proporcionar tu propio conjunto de componentes de presentación individuales. Los atributos clave, como selectable (para permitir clics en los elementos de la lista) y orientation (para un diseño horizontal o vertical), se pueden establecer directamente en el componente superior.

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

Adapta la lógica de JavaScript

En tu código JavaScript, obtén una referencia al componente del controlador de búsqueda con document.querySelector(). Según tu configuración, este será el elemento <gmp-place-text-search-request> o <gmp-place-nearby-search-request>.

Luego, establece las propiedades de este controlador para definir tu búsqueda. Las propiedades obligatorias dependen del tipo de búsqueda que realices.

Para una búsqueda de texto (<gmp-place-text-search-request>), la propiedad principal es textQuery:

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

Para una solicitud de Nearby Search (<gmp-place-nearby-search-request>), debes definir el área de búsqueda con un parámetro locationRestriction. Luego, puedes usar includedTypes para filtrar tipos específicos de lugares dentro de esa área:

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'];

El componente <gmp-place-search> superior inicia automáticamente una búsqueda nueva en cuanto se establecen las propiedades requeridas de su controlador.

  • En el caso de una búsqueda de texto, esta se ejecuta en el momento en que asignas un valor a textQuery.
  • En el caso de Nearby Search, la búsqueda se ejecuta después de que se proporciona un valor de locationRestriction válido.

Implementa el elemento básico de Place Autocomplete

Para los desarrolladores que requieren una experiencia de búsqueda sin la IU proporcionada del elemento Place Search, está disponible el elemento Basic Place Autocomplete.

Este elemento es ideal para crear un campo de entrada de búsqueda y, al mismo tiempo, mantener el control total sobre cómo se muestran los resultados en tu interfaz de usuario personalizada. La única responsabilidad del elemento Autocomplete es proporcionar predicciones de lugares a medida que el usuario escribe y exponer de forma programática un ID de lugar para el lugar seleccionado.

No muestra ningún detalle ni proporciona ninguna otra información accesible de manera programática.

Implementación actual

Es probable que tu lógica existente incluya lo siguiente:

  • Renderizar un campo de entrada de texto en tu página que llame a Place Autocomplete a medida que el usuario escribe y muestre los resultados
  • Usar el ID de lugar del lugar seleccionado por el usuario para recuperar más detalles, por ejemplo, con la API de Place Details
  • Se muestran los detalles del lugar seleccionado.

Migración al elemento Place Autocomplete

Modifica la estructura HTML

Identifica y quita el elemento HTML al que adjuntas el widget de Autocomplete. Es probable que use un campo de entrada HTML estándar.

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

Ejemplo de un nuevo código HTML que usa el enfoque de componente web para inicializar un elemento básico de Place Autocomplete en tu página.

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

Adapta la lógica de JavaScript

Es probable que tu lógica de JavaScript implique crear el widget de Autocomplete adjunto a un elemento HTML input. Luego, este widget escucha el evento place_changed, lo que activa una acción con los datos que se devuelven.

Ejemplo de JavaScript existente que se debe quitar:

// 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);
});

Tu nueva lógica de JavaScript obtendrá una referencia al elemento de Place Autocomplete básico y escuchará los eventos gmp-select:

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

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

Cuando se selecciona un lugar en el menú desplegable de Autocomplete, se activa el evento gmp-select. El ID de lugar del lugar seleccionado se puede recuperar del objeto event. Luego, el ID de lugar se puede usar para inicializar una instancia del elemento Place Details y mostrar los detalles del lugar seleccionado.

Personalización del controlador

Personalización del elemento Place Details

Orientación

El componente Place Details se puede renderizar con orientación horizontal y vertical. Usa el atributo orientation en gmp-place-details-compact para elegir entre vertical y horizontal. Por ejemplo:

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

Elige los campos que quieres renderizar

Usa elementos de contenido para especificar el contenido que se renderizará dentro del elemento Place Details. Por ejemplo, si excluyes el elemento de contenido <gmp-place-type>, se detendrá la renderización del tipo de lugar del lugar seleccionado en el componente Place Details. Para obtener una lista completa de los elementos de contenido, consulta la documentación de referencia de PlaceContentConfigElement.

Agregar o quitar campos del elemento Place Details no cambia el costo de renderizar el elemento en la página.

Establece estilos CSS

Las propiedades de CSS personalizadas están disponibles para configurar los colores y las fuentes del elemento. Por ejemplo, para establecer el fondo del elemento en verde, configura la siguiente propiedad de CSS:

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

Consulta la documentación de referencia de PlaceDetailsCompactElement para obtener más detalles.

Personalización del elemento Place Search

Orientación

El elemento Place Search se puede renderizar con orientación horizontal y vertical. Usa el atributo orientation en <gmp-place-search> para elegir entre vertical y horizontal. Por ejemplo:

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

Elige los campos que quieres renderizar

Usa elementos de contenido para especificar el contenido que se renderizará dentro del elemento de Place Search. El elemento <gmp-place-all-content> se puede usar para mostrar todo el contenido, o se puede usar una selección de etiquetas HTML para configurar el contenido renderizado.

Si incluyes <gmp-place-address> dentro de <gmp-place-content-config>, solo se renderizará la dirección de cada lugar, por ejemplo:

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

Personalización básica del elemento Place Autocomplete

Establece estilos CSS

Las propiedades de CSS personalizadas están disponibles para personalizar el aspecto del elemento Autocomplete. Por ejemplo, para establecer el color de fondo en morado claro, debes configurar la propiedad background-color en el elemento.

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

Consulta la documentación de referencia de BasicPlaceAutocompleteElement para obtener más detalles.

Cómo controlar eventos y datos

Los elementos del kit de IU de Places son componentes interactivos que te permiten escuchar eventos y recuperar datos de forma programática.

Detecta eventos

Puedes agregar objetos de escucha de eventos a los elementos para activar acciones según la interacción del usuario o el estado del elemento.

Evento de selección

  • gmp-select: Este evento se activa cuando un usuario realiza una selección.
    • En el elemento Place Search, se activa cuando un usuario hace clic en un lugar de la lista de resultados.
    • En el elemento Place Autocomplete básico, se activa cuando un usuario hace clic en una predicción de la lista desplegable.

Eventos comunes

Los elementos Place Search, Place Details y Basic Place Autocomplete admiten los siguientes eventos:

  • gmp-load: Se activa cuando el elemento y su contenido terminaron de cargarse y renderizarse.
  • gmp-requesterror: Se activa cuando falla una solicitud al servidor, por ejemplo, debido a una clave de API no válida.

Accede a los datos de los elementos de manera programática

Puedes recuperar de forma programática datos específicos de los elementos después de que se haya interactuado con ellos o se hayan cargado.

  • Para los elementos Place Search y Place Details, puedes recuperar la siguiente información:
    • ID de lugar
    • Ubicación (latitud y longitud)
    • Viewport
  • Para el elemento básico de Place Autocomplete, puedes recuperar la siguiente información:
    • ID de lugar

No se puede acceder de manera programática a ningún otro dato contenido en los elementos.

Para ver ejemplos más detallados, consulta la documentación individual del elemento Place Search, el elemento Place Details y el elemento Place Autocomplete básico.

Pruebas y perfeccionamiento

Una vez que hayas integrado los elementos del kit de IU de Places, es fundamental que realices pruebas para garantizar una transición fluida y una experiencia del usuario positiva. Tus pruebas deben abarcar varias áreas clave y abordar todos los elementos que hayas implementado: Place Details, Place Search y Basic Place Autocomplete.

Elemento Place Details

En el caso del componente Place Details, comienza por verificar que los detalles se muestren correctamente para una amplia variedad de lugares. Para realizar la prueba, pasa varios IDs de lugar a la propiedad .place del elemento <gmp-place-details-place-request>. Usa IDs que representen diferentes tipos de establecimientos (empresas con datos enriquecidos, puntos de interés, direcciones básicas) y lugares en diferentes regiones o idiomas. Presta mucha atención al formato, el diseño y la presencia del contenido.

Elemento Place Search

Si implementaste el elemento Place Search, verifica su renderización y comportamiento en diferentes situaciones de búsqueda.

  • Para una búsqueda de texto, realiza pruebas configurando la propiedad textQuery en el elemento <gmp-place-text-search-request> con varias entradas: búsquedas amplias, direcciones específicas y búsquedas con sesgos de ubicación.
  • Para una solicitud de Nearby Search, realiza una prueba configurando las propiedades locationRestriction y includedTypes en el elemento <gmp-place-nearby-search-request>. Usa diferentes tamaños de ubicación y filtros de tipo.

Confirma que la lista se complete con resultados pertinentes y que el evento gmp-select se active correctamente cuando se seleccione.

Elemento Basic Place Autocomplete

En el caso del elemento Basic Place Autocomplete, enfoca las pruebas en la interacción del usuario y los datos que se pasan por el evento de selección. Confirma que el evento gmp-select se active de forma confiable cuando un usuario haga clic en una predicción. Verifica que el objeto event.place en el controlador de eventos contenga un ID de lugar válido.

Lo más importante es que pruebes el flujo de extremo a extremo: selecciona un lugar del menú desplegable de Autocomplete y verifica que su ID de lugar se pueda usar correctamente para propagar otro elemento, como el elemento Place Details.

Manejo de errores

Es fundamental realizar pruebas rigurosas del manejo de errores en todos los componentes. Simula el paso de IDs de lugar no válidos o inexistentes al elemento Place Details, o bien usa parámetros de búsqueda no válidos para el elemento Place Search. Activa el evento gmp-requesterror simulando problemas de red o usando una clave de API no válida para asegurarte de que tu aplicación lo controle correctamente. Implementa mensajes de error y registros fáciles de usar para evitar una IU rota o confusa.