Objetivo
En este documento, se describen los pasos clave para desarrollar una aplicación interactiva de búsqueda de tiendas con Google Maps Platform, específicamente la API de Maps JavaScript y el kit de IU de Places: Elemento de detalles de lugares. Aprenderás a crear un mapa que muestre las ubicaciones de las tiendas, actualizar de forma dinámica una lista de tiendas visibles y mostrar información enriquecida de lugares para cada tienda.
Requisitos previos
Se recomienda que conozcas lo siguiente:
- API de Maps JavaScript: Se usa para mostrar un mapa en tu página y para importar el kit de IU de Places.
- Marcadores avanzados: Se usan para mostrar marcadores en el mapa.
- Kit de IU de Places: Se usa para mostrar información sobre tus tiendas en la IU.
Habilita la API de Maps JavaScript y el kit de IU de Places en tu proyecto.
Verifica que hayas cargado la API de Maps JavaScript y que hayas importado las bibliotecas necesarias para los marcadores avanzados y el kit de IU de Places antes de comenzar. En este documento, también se supone que tienes conocimientos prácticos de desarrollo web, incluidos HTML, CSS y JavaScript.
Configuración inicial
El primer paso es agregar un mapa a la página. Este mapa se usará para mostrar pines relacionados con las ubicaciones de tus tiendas.
Existen dos formas de agregar un mapa a una página:
- Cómo usar un componente web HTML gmp-map
- Con JavaScript
Elige el método que mejor se adapte a tu caso de uso. Ambas formas de implementar el mapa funcionarán con esta guía.
Demostración
En esta demostración, se muestra un ejemplo del buscador de tiendas en acción, que muestra las ubicaciones de las oficinas de Google en el Área de la Bahía. El elemento Place Details se muestra para cada ubicación, junto con algunos atributos de ejemplo.
Carga y muestra ubicaciones de tiendas
En esta sección, cargaremos y mostraremos los datos de tus tiendas en el mapa. En esta guía, se da por sentado que tienes un repositorio de información sobre tus tiendas existentes del que puedes extraer datos. Los datos de tu tienda pueden provenir de varias fuentes, como tu base de datos.
Para este ejemplo, suponemos un archivo JSON local (stores.json) con un array de objetos de tienda, cada uno de los cuales representa una ubicación de tienda. Cada objeto debe contener al menos un name, un location (con lat y lng) y un place_id.
Existen varias formas de recuperar los IDs de Place para las ubicaciones de tus tiendas si aún no los tienes. Consulta la documentación del ID de lugar para obtener más información.
Un ejemplo de una entrada de detalles de la tienda en tu archivo stores.json podría verse de la siguiente manera:
Hay campos para Nombre, Ubicación (lat/lng) y ID de Place. Hay un objeto para contener el horario de atención de la tienda (truncado). También hay dos valores booleanos para ayudar a describir las funciones personalizadas de la ubicación de la tienda.
{
"name": "Example Store Alpha",
"location": { "lat": 51.51, "lng": -0.12 },
"place_id": "YOUR_STORE_PLACE_ID",
"opening_hours": { "Monday": "09:00 - 17:00", "...": "..." },
"new_store_design": true,
"indoor_seating": false
}
En tu código JavaScript, recupera los datos de las ubicaciones de tus tiendas y muestra un pin en el mapa para cada una.
A continuación, se muestra un ejemplo de cómo hacerlo. Esta función toma un objeto que contiene los detalles de las tiendas y crea un marcador según la ubicación de cada una.
function displayInitialMarkers(storeLocations) {
if (!AdvancedMarkerElement || !LatLng || !mapElement) return;
storeLocations.forEach(store => {
if (store.location) {
const marker = new AdvancedMarkerElement({
position: new LatLng(store.location.lat, store.location.lng),
title: store.name
});
mapElement.appendChild(marker);
}
});
}
Una vez que hayas cargado tus tiendas y tengas los pines que representan sus ubicaciones en el mapa, crea una barra lateral con HTML y CSS para mostrar detalles sobre tus tiendas individuales.
A continuación, se muestra un ejemplo de cómo podría verse tu localizador de tiendas en esta etapa:
Cómo detectar cambios en el viewport del mapa
Para optimizar el rendimiento y la experiencia del usuario, actualiza tu aplicación para que muestre marcadores y detalles en la barra lateral solo cuando sus ubicaciones correspondientes estén dentro del área visible del mapa (viewport). Esto implica detectar cambios en la vista del mapa, anular el rebote de estos eventos y, luego, volver a dibujar solo los marcadores necesarios.
Adjunta un objeto de escucha de eventos al evento inactivo del mapa. Este evento se activa después de que se completan las operaciones de desplazamiento o zoom, lo que proporciona un viewport estable para tus cálculos.
map.addListener('idle', debounce(updateMarkersInView, 300));
El fragmento de código anterior escucha el evento idle y llama a una función debounce. El uso de una función de eliminación de rebote garantiza que la lógica de actualización de marcadores solo se ejecute después de que el usuario deje de interactuar con el mapa durante un período breve, lo que mejora el rendimiento.
function debounce(func, delay) {
let timeoutId;
return function(...args) {
const context = this;
clearTimeout(timeoutId);
timeoutId = setTimeout(() => {
func.apply(context, args);
}, delay);
};
}
El código anterior es un ejemplo de función de eliminación de rebote. Toma una función y un argumento de retraso, que se puede ver pasado en el objeto de escucha inactivo. Una demora de 300 ms es suficiente para esperar a que el mapa deje de moverse, sin agregar una demora notable a la IU.
Una vez que venza este tiempo de espera, se llamará a la función pasada, en este caso, updateMarkersInView.
La función updateMarkersInView debe realizar las siguientes acciones:
Borra todos los marcadores existentes del mapa
Comprueba si la ubicación de la tienda se encuentra dentro de los límites actuales del mapa, por ejemplo:
if (map.getBounds().contains(storeLatLng)) {
// logic
}
Dentro de la sentencia if anterior, escribe código para mostrar los marcadores y almacenar los detalles en la barra lateral, si la ubicación de la tienda se encuentra dentro del viewport del mapa.
Cómo mostrar detalles enriquecidos de un lugar con el elemento Place Details
En esta etapa, la aplicación muestra todas las ubicaciones de las tiendas, y los usuarios pueden filtrarlas según la vista del mapa. Para mejorar esto, se agregan detalles enriquecidos sobre cada tienda, como fotos, opiniones y datos de accesibilidad, con el elemento Place Details. En este ejemplo, se usa específicamente el elemento compacto de Place Details.
Cada ubicación de tienda en tu fuente de datos debe tener un ID de Place correspondiente. Este ID identifica de forma única la ubicación en Google Maps y es esencial para recuperar sus detalles. Por lo general, debes adquirir estos IDs de Place con anticipación y almacenarlos en cada uno de tus registros de tienda.
Integra el elemento compacto de Place Details en la aplicación
Cuando se determina que una tienda se encuentra dentro del viewport del mapa actual y se renderiza en la barra lateral, puedes crear e insertar de forma dinámica un elemento compacto de detalles del lugar para ella.
Para la tienda actual que se está procesando, recupera el ID de lugar de tus datos. El ID de lugar se usa para controlar en qué lugar se mostrará el elemento.
En JavaScript, crea una instancia de PlaceDetailsCompactElement de forma dinámica. También se crea un PlaceDetailsPlaceRequestElement nuevo, se le pasa el ID de Place y se agrega a PlaceDetailsCompactElement. Por último, usa PlaceContentConfigElement para configurar el contenido que mostrará el elemento.
En la siguiente función, se supone que las bibliotecas necesarias de Place UI Kit están importadas y disponibles en el alcance al que se llama a esta función, y que el storeData que se pasa a la función contiene place_id.
Esta función mostrará el elemento, y el código de llamada será responsable de agregarlo al DOM.
function createPlaceDetailsCompactElement(storeData) {
// Create the main details component
const detailsCompact = new PlaceDetailsCompactElement();
detailsCompact.setAttribute('orientation', 'vertical'); // Or 'horizontal'
// Specify the Place ID
const placeRequest = new PlaceDetailsPlaceRequestElement();
placeRequest.place = storeData.place_id;
detailsCompact.appendChild(placeRequest);
// Configure which content elements to display
const contentConfig = new PlaceContentConfigElement();
// For this example, we'll render media, rating, accessibility, and attribution:
contentConfig.appendChild(new PlaceMediaElement({ lightboxPreferred: true }));
contentConfig.appendChild(new PlaceRatingElement());
contentConfig.appendChild(new PlaceAccessibleEntranceIconElement());
// Configure attribution
const placeAttribution = new PlaceAttributionElement();
placeAttribution.setAttribute('light-scheme-color', 'gray');
placeAttribution.setAttribute('dark-scheme-color', 'gray');
contentConfig.appendChild(placeAttribution);
detailsCompact.appendChild(contentConfig);
// Return the element
return detailsCompact;
}
En el código de ejemplo anterior, el elemento está configurado para mostrar las fotos del lugar, la calificación de opiniones y la información de accesibilidad. Para personalizarlo, agrega o quita otros elementos de contenido disponibles. Consulta la documentación de PlaceContentConfigElement para ver todas las opciones disponibles.
El elemento compacto de Place Details admite la aplicación de diseño a través de propiedades personalizadas de CSS. Esto te permite adaptar su apariencia (colores, fuentes, etc.) para que coincida con el diseño de tu aplicación. Aplica estas propiedades personalizadas en tu archivo CSS. Consulta la
documentación de referencia de
PlaceDetailsCompactElement
para conocer las propiedades CSS compatibles.
Este es un ejemplo de cómo podría verse tu aplicación en esta etapa:
Mejora el buscador de tiendas
Creaste una base sólida para tu aplicación de búsqueda de tiendas. Ahora, considera varios modos de extender su funcionalidad y crear una experiencia aún más enriquecedora y centrada en el usuario.
Agrega autocompletar
Integra una entrada de búsqueda con Place Autocomplete para mejorar la forma en que los usuarios encuentran áreas para buscar tiendas. Cuando los usuarios escriban una dirección, un vecindario o un lugar de interés y seleccionen una sugerencia, programa el mapa para que se centre automáticamente en esa ubicación y active una actualización de las tiendas cercanas. Para ello, agrega un campo de entrada y adjúntalo a la funcionalidad de Place Autocomplete. Cuando se selecciona una sugerencia, el mapa se puede centrar en ese punto. Recuerda configurarlo para sesgar o restringir los resultados a tu área operativa.
Cómo detectar la ubicación
Ofrece relevancia inmediata, especialmente para los usuarios de dispositivos móviles, implementando la funcionalidad para detectar su ubicación geográfica actual. Después de obtener el permiso del navegador para detectar su ubicación, centra automáticamente el mapa en su posición y muestra las tiendas más cercanas. Los usuarios valoran mucho esta función Cerca de mí cuando buscan opciones inmediatas. Agrega un botón o una instrucción inicial para solicitar acceso a la ubicación.
Mostrar la distancia y las instrucciones sobre cómo llegar
Una vez que un usuario identifica una tienda de interés, mejora significativamente su recorrido integrando la API de Routes. Para cada tienda que enumeres, calcula y muestra la distancia desde la ubicación actual del usuario o desde la ubicación buscada. Además, proporciona un botón o vínculo que use la API de Routes para generar una ruta desde la ubicación del usuario hasta la tienda seleccionada. Luego, puedes mostrar esta ruta en tu mapa o vincularla a Google Maps para navegar, lo que crea una transición fluida desde encontrar una tienda hasta llegar a ella.
Si implementas estas extensiones, podrás usar más funciones de la plataforma de Google Maps para crear un localizador de tiendas más completo y conveniente que aborde directamente las necesidades comunes de los usuarios.
Conclusión
En esta guía, se mostraron los pasos principales para crear un buscador de tiendas interactivo. Aprendiste a mostrar las ubicaciones de tus propias tiendas en un mapa con la API de Maps JavaScript, a actualizar de forma dinámica las tiendas visibles en función de los cambios del viewport y, lo más importante, a mostrar tus propios datos de tiendas de acuerdo con el kit de la IU de Places. Si usas la información de tu tienda existente, incluidos los IDs de Place, con el elemento Place Details, puedes presentar detalles enriquecidos y estandarizados para cada una de tus ubicaciones, lo que crea una base sólida para un localizador de tiendas fácil de usar.
Prueba la API de Maps JavaScript y el kit de IU de Places para ofrecer herramientas potentes basadas en componentes para desarrollar rápidamente aplicaciones sofisticadas basadas en la ubicación. Si combinas estas funciones, puedes crear experiencias atractivas y informativas para tus usuarios.
Colaboradores
Henrik Valve | Ingeniero de DevX