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

Objetivo: Reemplaza tu implementación de la API de Places o la clase Place por el kit de IU de Places.

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

Desarrolladores que cumplan con los siguientes requisitos:

  • Realizar solicitudes HTTP a los extremos de la API de Places (nueva o heredada)
  • Cómo usar la clase Place en la API de Maps JavaScript
  • Manejar la respuesta de la API para renderizar la información del lugar en la IU de su 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 Places UI Kit. Consulta Cómo usar claves de API para obtener más información, incluida la restricción de una clave.

Actualización de 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 secuencia de comandos directa, esta debe actualizarse.

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

El elemento Place Details y el elemento 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 Places 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 nombre, dirección, fotos, etc.) por el código HTML del elemento Place Details.

Puedes elegir entre dos elementos:

  • Elemento compacto de Place Details
  • Elemento Place Details

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

Tu código HTML existente podría verse así.

<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 que indica explícitamente qué contenido 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 hacer una llamada de servicio web
  • Especificar un array de campos (para la API de JS) o un FieldMask (para el servicio web) para solicitar datos específicos
  • En la resolución de devolución de llamada, seleccionar manualmente tus elementos HTML y completarlos 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 tu objeto Place.
  • Obtén una referencia al elemento <gmp-place-details-place-request>.
  • Pasa el ID de lugar o el objeto de lugar 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 configura 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.

  • Puedes realizar una búsqueda de texto o una búsqueda cercana con una solicitud HTTP, o bien usar la clase Place de la API de Places de JavaScript.
  • Especificas los parámetros de búsqueda, las restricciones o las tendencias 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 nombre, dirección, etc.) por el elemento HTML de Place Search Element.

Tu código HTML existente podría 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 ranurados dentro de:

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

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 elementos de la lista) y orientation (para un diseño horizontal o vertical), se pueden establecer directamente en el componente principal.

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

A continuación, configura las propiedades de este controlador para definir tu búsqueda. Las propiedades requeridas dependen del tipo de búsqueda que realices.

En el caso de 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';

En el caso de una búsqueda en los alrededores (<gmp-place-nearby-search-request>), debes definir el área de búsqueda con un 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> principal inicia automáticamente una nueva búsqueda en cuanto se establecen las propiedades obligatorias de su controlador.

  • En el caso de una búsqueda de texto, la búsqueda se ejecuta en el momento en que asignas un valor a textQuery.
  • En el caso de una Búsqueda cercana, la búsqueda se ejecuta después de que se proporciona un 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 por sí mismo ni proporciona ninguna otra información accesible de forma 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 de Place Autocomplete

Modifica la estructura HTML

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

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

Ejemplo de HTML nuevo, que usa el enfoque de componentes web para inicializar un elemento de Autocomplete básico de lugares 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 la creación del widget de Autocomplete adjunto a un elemento input de HTML. Luego, este widget escucha el evento place_changed y activa una acción con los datos devueltos.

Ejemplo de código 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 Basic Place Autocomplete y detectará 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 autocompletado, se activa el evento gmp-select. El ID de lugar del lugar seleccionado se puede recuperar del objeto event. Luego, se puede usar el ID de lugar para inicializar una instancia del elemento Place Details y mostrar los detalles del lugar seleccionado.

Personalización de la manija

Personalización del elemento Place Details

Orientación

El elemento Place Details se puede renderizar en 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 se renderizarán

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>, el elemento Place Details dejará de renderizar el tipo de lugar del lugar seleccionado. 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.

Cómo establecer estilos CSS

Hay propiedades de CSS personalizadas disponibles para configurar los colores y las fuentes del elemento. Por ejemplo, para establecer el fondo del elemento en verde, configura la siguiente propiedad 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 en 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 se renderizarán

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 bien se puede usar una selección de etiquetas HTML para configurar el contenido renderizado.

Incluir <gmp-place-address> dentro de <gmp-place-content-config> solo renderizaría 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 de Place Autocomplete

Cómo establecer estilos CSS

Hay propiedades de CSS personalizadas disponibles para personalizar la apariencia 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 de Places UI Kit 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 Basic Place Autocomplete, 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 elementos de forma programática

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

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

No se puede acceder de forma programática a todos los demás datos contenidos 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 Basic Place Autocomplete.

Pruebas y ajustes

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

Elemento Place Details

En el caso del elemento 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>. Usar 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 de 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, prueba 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 búsqueda cercana, 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 relevantes y que el evento gmp-select se active correctamente cuando se realice la selección.

Elemento básico de 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 en el evento de selección. Confirma que el evento gmp-select se activa de manera confiable cuando un usuario hace 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 probar el flujo de extremo a extremo: selecciona un lugar en el menú desplegable de Autocomplete y verifica que su ID de lugar se pueda usar correctamente para completar otro elemento, como el elemento Place Details.

Manejo de errores

Es fundamental realizar pruebas rigurosas del control de errores en todos los componentes. Simula el paso de IDs de lugar no válidos o inexistentes al elemento Place Details, o el uso de 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 de forma adecuada. Implementa mensajes de error y registros fáciles de usar para evitar una IU dañada o confusa.