Objetivo
Aprende a integrar el PlaceSearchElement con Google Maps para ayudar a los usuarios a encontrar lugares con Nearby Search o Text Search, lo que mejora su capacidad para explorar lugares de interés. Usa el elemento compacto de Place Details para proporcionar más detalles sobre los lugares que se muestran en tu aplicación.
¿Qué es el objeto PlaceSearchElement?
El PlaceSearchElement forma parte del kit de IU de Places en la API de Maps JavaScript. Es un elemento HTML que renderiza los resultados de una búsqueda de lugares directamente en un formato de lista dentro de tu aplicación. Este elemento simplifica el proceso de mostrar los lugares encontrados con una búsqueda de Nearby Search o Text Search, lo que proporciona una experiencia del usuario fluida para el descubrimiento de lugares. Cuando un usuario selecciona un lugar de
la lista, puedes mostrar sus detalles en el mapa, a menudo con una ventana de información y
el elemento Place Details.
Visualiza el descubrimiento de lugares
En la siguiente imagen, se muestra un ejemplo de la PlaceSearchElement en acción. A la izquierda, se muestra una lista de restaurantes (el PlaceSearchElement). Cuando se selecciona un restaurante, sus detalles aparecen en una ventana de información en el mapa, y este se centra en su ubicación.
Casos de uso para el descubrimiento de lugares
La integración de la PlaceSearchElement puede mejorar varias aplicaciones en
diferentes industrias:
- Viajes y turismo: Permite que los turistas busquen atracciones, hoteles o tipos específicos de cocina en un área.
- Bienes raíces: Permite que los posibles compradores o arrendatarios encuentren escuelas, supermercados o opciones de transporte público cercanos.
- Logística y servicios: Ayuda a los conductores a encontrar estaciones de carga de VE, gasolineras o centros de servicio específicos.
Flujo de trabajo de la solución: Implementa el descubrimiento de lugares
En esta sección, se explica cómo integrar el PlaceSearchElement para descubrir lugares en un mapa y se incluyen fragmentos de código para interactuar con el kit de IU de Places. Aprende a inicializar el mapa y a implementar las funciones de Nearby Search y Text Search. Por último, usa el elemento Place Details para mostrar más detalles sobre un lugar cuando un usuario haga clic en su pin en el mapa.
Requisitos previos
Se recomienda que te familiarices con la siguiente documentación:
PlaceSearchElement- Se usa para exponer lugares con Nearby Search o Text Search.- Elemento Place Details: Se usa para mostrar detalles de un lugar individual.
- API de Maps JavaScript: Se usa para mostrar un mapa en tu página y para importar el kit de IU de Places.
Habilita la API de Maps JavaScript y el kit de IU de Places en tu proyecto.
Antes de comenzar, verifica que hayas cargado la API de Maps JavaScript y que hayas importado las bibliotecas necesarias. En este documento, también se supone que tienes conocimientos prácticos de desarrollo web, incluidos HTML, CSS y JavaScript.
Agrega un mapa a la página
El primer paso es agregar un mapa a tu página. Este mapa se usará para mostrar los resultados de PlaceSearchElement como pines seleccionables.
Existen dos maneras de agregar un mapa a una página:
- Usa un componente web HTML de
gmp-map. - Usa JavaScript.
Los fragmentos de código de esta página se generaron con un mapa de JavaScript.
El mapa se puede centrar en una ubicación en torno a la cual deseas que el usuario realice la búsqueda, como un hotel, o se puede inicializar para solicitar la ubicación actual del usuario y centrar el mapa en ella. Para los fines de este documento, usaremos una ubicación fija para fijar la búsqueda.
Si visualizas lugares cercanos a una ubicación fija, como un hotel, coloca un marcador en el mapa para representar este lugar. Por ejemplo:
El mapa se centra en San Francisco, con un pin azul que representa el lugar que
estamos buscando cerca. El color del pin se personalizó con PinElement.
El control de tipo de mapa se ocultó de la IU.
Configurar PlaceSearchElement
Ahora, configura el HTML y el CSS para mostrar el PlaceSearchElement. En este ejemplo, el elemento flota sobre el lado izquierdo del mapa, pero puedes probar diferentes diseños para adaptarlos a tu aplicación.
PlaceSearchElement usa un enfoque declarativo. En lugar de configurarlo
por completo en JavaScript, define el tipo de búsqueda directamente en tu HTML anidando
un elemento de solicitud, como <gmp-place-nearby-search-request>, dentro
del componente <gmp-place-search> principal.
En tu código HTML, inicializa un elemento <gmp-place-search>. Usa el atributo selectable para habilitar los eventos de clic en los resultados. Dentro de él, agrega un elemento <gmp-place-nearby-search-request> para especificar que se usará para Nearby Search.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
Para realizar una búsqueda inicial y mostrar los resultados, usaremos JavaScript para obtener una
referencia al elemento de solicitud anidado y establecer sus propiedades. Inicializa un objeto Circle para usarlo como locationRestriction, con la posición del marcador del paso anterior como punto central. Luego, establece las propiedades locationRestriction y
includedPrimaryTypes en el elemento de solicitud para activar la búsqueda.
El fragmento de código para esto es el siguiente:
// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");
// Define the location restriction for the search
const circleRestriction = new Circle({
center: marker.position,
radius: 500
});
// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];
A continuación, se muestra un ejemplo de cómo podría verse la aplicación en esta etapa:
Permitir que el usuario realice búsquedas
PlaceSearchElement permite dos opciones de búsqueda:
<gmp-place-nearby-search-request>: Renderiza los resultados de la búsqueda de una Nearby Search de Places con tipos de lugares.<gmp-place-text-search-request>: Renderiza los resultados de la búsqueda de una búsqueda de texto de Places con una entrada de texto libre, como "Sushi en San Francisco".
Estos son elementos anidados dentro de <gmp-place-search>. Luego, activas las búsquedas
estableciendo propiedades en ese elemento de solicitud anidado con JavaScript.
En esta sección, se describe cómo implementar ambos métodos.
Búsqueda cercana
Para permitir que los usuarios realicen una búsqueda de lugares cercanos, primero necesitas un elemento de la IU que les permita seleccionar un tipo de lugar. Elige el método de selección que mejor se adapte a tu aplicación, por ejemplo, una lista desplegable con una selección de tipos de lugares.
Se recomienda elegir un subconjunto de tipos que sean relevantes para tu caso de uso.
Por ejemplo, si estás desarrollando una aplicación para mostrarles a los turistas qué hay cerca
de un hotel, puedes elegir: bakery, coffee_shop, museum, restaurant y
tourist_attraction.
Tu código HTML debe contener el elemento <gmp-place-search> con un elemento <gmp-place-nearby-search-request> anidado.
<gmp-place-search selectable>
<gmp-place-nearby-search-request>
</gmp-place-nearby-search-request>
</gmp-place-search>
A continuación, crea un objeto de escucha de JavaScript para el evento change en tu selector de tipo de lugar. Este objeto de escucha llamará a una función que actualiza las propiedades del elemento <gmp-place-nearby-search-request>, lo que activa automáticamente una búsqueda nueva y actualiza la lista.
// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');
// Function to update the place search based on the selected type
function updatePlaceList() {
const selectedType = placeTypeSelect.value;
if (!selectedType) {
// If no type is selected, don't perform a search.
// You could optionally hide the list or clear previous results here.
placeSearchElement.style.display = 'none';
return;
}
placeSearchElement.style.display = 'block';
// Set properties on the request element to trigger a new search
placeSearchRequestElement.locationRestriction = searchCircle;
placeSearchRequestElement.maxResultCount = 8;
placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}
Se usa el mismo searchCircle del paso de configuración para el
locationRestriction. La propiedad includedPrimaryTypes se establece en el valor
de la selección del usuario. También se establece un maxResultCount opcional para limitar la
cantidad de resultados.
Text Search
Para habilitar la búsqueda de texto, debes cambiar tu configuración de HTML. En lugar de la solicitud de Nearby Search, anidas un elemento <gmp-place-text-search-request>.
<gmp-place-search selectable>
<gmp-place-text-search-request>
</gmp-place-text-search-request>
</gmp-place-search>
Agrega una entrada de texto y un botón de búsqueda a tu IU. Crea un objeto de escucha de JavaScript para el evento click del botón. El controlador de eventos tomará la entrada del usuario y
actualizará las propiedades del elemento <gmp-place-text-search-request> para
realizar la búsqueda.
// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');
textSearchButton.addEventListener('click', performTextSearch);
function performTextSearch() {
const query = textSearchInput.value.trim();
if (!query) {
console.log("Search query is empty.");
return;
}
// Set properties on the request element to trigger a new search
placeTextSearchRequestElement.textQuery = query;
placeTextSearchRequestElement.locationBias = map.getBounds();
placeTextSearchRequestElement.maxResultCount = 8;
}
Aquí, establecemos la propiedad textQuery con la entrada del usuario. También proporcionamos un objeto locationBias con los límites actuales del mapa, que le indica a la API que prefiera los resultados dentro de esa área sin limitarlos estrictamente. Un maxResultCount opcional limita la cantidad de resultados que se muestran.
Muestra pines y detalles de lugares
Ahora, la aplicación puede realizar una búsqueda de lugares y propagar el elemento. En el siguiente paso, mejoraremos su funcionalidad de la siguiente manera:
- Mostrar pines en el mapa para cada lugar que se propaga en el
PlaceSearchElement - Permitir que un usuario haga clic en un pin o en el lugar dentro de la
PlaceSearchElementpara mostrar más detalles sobre ese lugar en particular
El principio de este paso es el mismo, ya sea que la aplicación use una búsqueda de lugares cercanos o una búsqueda de texto.
Primero, agrega una variable global a tu código JavaScript para almacenar los marcadores de lugares. Esto te permitirá quitarlos cuando cambie la búsqueda y controlar los eventos de clic.
let markers = {};
Crea una función para agregar marcadores al mapa. Se llamará a esta función cada vez que se carguen nuevos resultados de la búsqueda. Esto hará lo siguiente:
- Quita los marcadores de lugar existentes del mapa.
- Recorre los resultados de
PlaceSearchElementy agrega un marcador para cada uno. - Ajusta los límites del mapa para que se vean todos los marcadores nuevos.
Para escuchar cuando los resultados de la búsqueda estén disponibles, agrega un objeto de escucha de eventos gmp-load al elemento <gmp-place-search>. Este evento se activa después de que se completa una búsqueda y se renderizan los resultados.
Agregaremos el objeto de escucha dentro de nuestra función de búsqueda (p.ej., updatePlaceList) y
usaremos la opción { once: true } para asegurarnos de que solo se active para los resultados de
la búsqueda actual.
// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });
La función addMarkers se ve de la siguiente manera:
async function addMarkers() {
const { LatLngBounds } = await google.maps.importLibrary("core");
const bounds = new LatLngBounds();
if (placeSearchElement.places.length > 0) {
// Remove existing markers
for (const m in markers) {
markers[m].map = null;
}
markers = {};
// Loop through each place from the search results
// and add a marker for each one.
for (const place of placeSearchElement.places) {
const marker = new google.maps.marker.AdvancedMarkerElement({
map: map,
position: place.location,
});
markers[place.id] = marker;
bounds.extend(place.location);
marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;
// Add a click listener for each marker.
marker.addListener('gmp-click', (event) => {
// The main logic for showing details will go here.
});
}
// Position the map to display all markers.
map.setCenter(bounds.getCenter());
map.fitBounds(bounds);
}
}
Una vez que se complete este paso, la aplicación se verá de la siguiente manera, con la capacidad de mostrar marcadores para cada lugar que devuelva el PlaceSearchElement:
Ahora que tenemos marcadores en el mapa, el último paso es controlar los eventos de clic en los marcadores y los elementos para mostrar una ventana de información con los detalles del lugar, que proporciona el elemento Place Details. Para este ejemplo, usaremos el elemento compacto de Place Details.
Agrega el código HTML del elemento Place Details Compact a tu código, por ejemplo:
<gmp-place-details-compact orientation="vertical" style="display: none;">
<gmp-place-all-content></gmp-place-all-content>
<gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>
El style se establece en display: none; no será visible hasta que sea necesario.
Se pasa gmp-place-all-content para renderizar todo el contenido del elemento. Para elegir qué contenido renderizar, consulta la documentación del elemento compacto de Place Details.
Crea una variable global en JavaScript para mantener una referencia al elemento compacto de Place Details y propaga esta variable en tu código de inicialización, por ejemplo:
let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');
Dentro de la función addMarkers, agrega un objeto de escucha de eventos gmp-click a cada marcador y configura el elemento compacto de Place Details para que muestre los detalles del lugar pasando el ID de lugar del marcador actual.
Una vez que se completa este proceso, se abre una ventana de información para mostrar el elemento compacto de Place Details, anclado en el marcador.
Por último, el mapa se posiciona en el viewport del lugar seleccionado, lo que lo hace visible.
async function addMarkers() {
...
marker.addListener('gmp-click', (event) => {
//Set up Place Details Compact Widget
placeDetailsElement.style.display = "block";
// Remove any existing place request element
const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
if (existingPlaceRequest) {
existingPlaceRequest.remove();
}
// Create and configure the new place request element
const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
// Prepend the new place request element to the main widget
placeDetailsElement.prepend(placeRequestElement);
if (infoWindow.isOpen) {
infoWindow.close();
}
infoWindow.setOptions({
content: placeDetailsElement
});
infoWindow.open({
anchor: marker,
map: map
});
// Position the map to show the selected place
placeDetailsElement.addEventListener('gmp-load', () => {
map.fitBounds(place.viewport, { top: 500, left: 400 });
});
});
...
});
}
}
Para permitir que el usuario haga clic en un lugar del elemento de lista de lugares y se muestre el elemento compacto de Place Details, agrega lo siguiente al código de JavaScript después de la llamada a configureFromSearchNearbyRequest.
placeSearchElement.addEventListener("gmp-select", ({ place }) => {
if (markers[place.id]) {
markers[place.id].click();
}
});
Después de completar este paso, la aplicación podrá usar una búsqueda de Nearby Search o Text Search para propagar el elemento de lista de lugares. Los resultados de esta acción mostrarán marcadores en el mapa. Cuando hagas clic en un marcador o en un lugar del elemento Place List, se mostrará una ventana de información con los detalles del lugar, proporcionados por el elemento Place Details Compact.
La aplicación se verá de la siguiente manera:
Conclusión
El PlaceSearchElement combinado con el elemento Place Details Compact
proporciona una forma optimizada de agregar funciones enriquecidas de descubrimiento de lugares a tus aplicaciones de Google
Maps Platform.
Prueba el kit de IU de Places hoy mismo para permitir que tus usuarios encuentren y exploren lugares con búsquedas de texto y de lugares cercanos, y muestren detalles enriquecidos de los lugares, lo que mejorará su interacción con tus casos de uso de descubrimiento de lugares.
Colaboradores
Henrik Valve | Ingeniero de DevX