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 Place Details. Aprenderás a crear un mapa que muestre las ubicaciones de las tiendas, actualizar de forma dinámica una lista de las tiendas visibles y mostrar información enriquecida sobre cada tienda.
Requisitos previos
Se recomienda tener conocimientos sobre 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.
Antes de comenzar, verifica que cargaste la API de Maps JavaScript y que importaste las bibliotecas necesarias para Marcadores avanzados y el Kit de IU de Places. En este documento, también se supone que tienes conocimientos prácticos sobre el 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 marcadores relacionados con las ubicaciones de tu tienda.
Existen dos formas de agregar un mapa a una página:
- Cómo usar un componente web HTML gmp-map
- Uso de 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, en el que se muestran 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.
Cómo cargar y mostrar ubicaciones de la tienda
En esta sección, cargaremos y mostraremos los datos de tu tienda en el mapa. En esta guía, se supone 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 que hay un archivo JSON local (stores.json) con un array de objetos de la tienda, cada uno de los cuales representa una ubicación de la 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 lugar de las ubicaciones de tu tienda si aún no los tienes. Consulta la documentación del ID de lugar para obtener más información.
Una entrada de ejemplo de los detalles de la tienda en tu archivo stores.json podría verse de la siguiente manera.
Hay campos para el nombre, la ubicación (latitud y longitud) y el ID de lugar. Hay un objeto para almacenar el horario de atención de la tienda (truncado). También hay dos valores booleanos que ayudan a describir las características 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 tu tienda y muestra un pin en el mapa para cada una.
A continuación, se incluye un ejemplo de cómo hacerlo. Esta función toma un objeto que contiene los detalles de las tiendas y crea un marcador basado en 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 se muestren en el mapa los marcadores que representan sus ubicaciones, crea una barra lateral con HTML y CSS para mostrar detalles sobre cada una de tus tiendas.
A continuación, se muestra un ejemplo de cómo podría verse tu localizador de tiendas en esta etapa:
Cómo detectar los 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 escuchar los cambios en la ventana gráfica del mapa, eliminar los rebotes de estos eventos y, luego, volver a dibujar solo los marcadores necesarios.
Adjunta un objeto de escucha de eventos al evento idle del mapa. Este evento se activa después de que se completan las operaciones de desplazamiento o zoom, lo que proporciona una ventana gráfica 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 rebotes 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 breve período, 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 una función de eliminación de rebotes. Toma una función y un argumento de demora, que se pueden ver en el objeto de escucha de inactividad. 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 vence este tiempo de espera, se llama 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 instrucción if anterior, escribe código para mostrar los marcadores y los detalles de la tienda en la barra lateral si la ubicación de la tienda se encuentra dentro del viewport del mapa.
Cómo mostrar detalles enriquecidos del lugar con el elemento Place Details
En esta etapa, la aplicación muestra todas las ubicaciones de la tienda, y los usuarios pueden filtrarlas según la ventana gráfica del mapa. Para mejorar esta experiencia, se agregan detalles enriquecidos sobre cada tienda, como fotos, opiniones y datos de accesibilidad, a través del elemento Place Details. En este ejemplo, se utiliza específicamente el elemento compacto de Place Details.
Cada ubicación de la tienda en tu fuente de datos debe tener un ID de lugar correspondiente. Este ID identifica de forma única la ubicación en Google Maps y es esencial para recuperar sus detalles. Por lo general, obtendrías estos IDs de lugar con anticipación y los almacenarías en cada uno de tus registros de tienda.
Integra el elemento compacto de Place Details en la aplicación
Cuando se determina que un comercio 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 él.
Para la tienda actual que se está procesando, recupera el ID de lugar de tus datos. El ID de lugar se usa para controlar qué lugar mostrará el elemento.
En JavaScript, crea de forma dinámica una instancia de PlaceDetailsCompactElement. También se crea un nuevo PlaceDetailsPlaceRequestElement, se le pasa el ID de lugar y se agrega al PlaceDetailsCompactElement. Por último, usa PlaceContentConfigElement para configurar el contenido que mostrará el elemento.
La siguiente función supone que las bibliotecas necesarias de Place UI Kit se importaron y están disponibles en el alcance en el que se llama a esta función, y que storeData que se pasa a la función contiene place_id.
Esta función devolverá 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. Puedes personalizarlo agregando o quitando otros elementos de contenido disponibles. Consulta la documentación de PlaceContentConfigElement para ver todas las opciones disponibles.
El elemento compacto de Place Details admite el 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 de CSS admitidas.
Este es un ejemplo de cómo podría verse tu aplicación en esta etapa:
Mejora del buscador de tiendas
Creaste una base sólida para tu aplicación de buscador de tiendas. Ahora, considera varias formas de extender su funcionalidad y crear una experiencia aún más enriquecida y centrada en el usuario.
Agrega autocompletar
Mejora la forma en que los usuarios encuentran áreas para buscar tiendas integrando una entrada de búsqueda con Place Autocomplete. Cuando los usuarios escriban una dirección, un barrio o un lugar de interés, y seleccionen una sugerencia, programa el mapa para que se centre automáticamente en esa ubicación, lo que activará una actualización de las tiendas cercanas. Para ello, agrega un campo de entrada y adjunta 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 función 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 la 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 el usuario identifica una tienda de interés, integra la API de Routes para mejorar significativamente su recorrido. Para cada tienda que incluyas en la lista, calcula y muestra la distancia desde la ubicación actual del usuario o desde la ubicación de la búsqueda. Además, proporciona un botón o un 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 crear un vínculo a Google Maps para obtener indicaciones sobre cómo llegar, lo que crea una transición fluida desde la búsqueda de una tienda hasta el momento en que llegas a ella.
Si implementas estas extensiones, podrás usar más funciones de Google Maps Platform 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 demostraron los pasos principales para crear un buscador de tiendas interactivo. Aprendiste a mostrar las ubicaciones de tus tiendas en un mapa con la API de Maps JavaScript, a actualizar de forma dinámica las tiendas visibles según los cambios en la ventana gráfica y, lo que es más importante, a mostrar los datos de tus tiendas en línea con el kit de IU de Places. Si utilizas la información existente de tu tienda, incluidos los IDs de lugar, 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 que te permitan desarrollar rápidamente aplicaciones sofisticadas basadas en la ubicación. Si combinas estas funciones, puedes crear experiencias atractivas e informativas para tus usuarios.
Colaboradores
Henrik Valve | Ingeniero de DevX