Se usó la API de Cloud Translation para traducir esta página.

¿Qué es el kit de IU de Places y cómo puedes usarlo para crear soluciones atractivas?

Introducción

Para millones de usuarios en todo el mundo, Google Maps es la fuente de información de lugares precisa y actualizada. La extensa base de datos de Google, que incluye más de 250 millones de lugares en todo el mundo, así como opiniones, fotos y calificaciones de los usuarios, proporciona un nivel de detalle y confianza sin igual. Para proporcionar datos actualizados y fácticos, realizamos 100 millones de actualizaciones en el mapa todos los días.

El kit de IU de Places es una biblioteca de componentes rentable y lista para usar, y está potenciado por la extensa información de Google Maps sobre lugares. Te permite integrar la experiencia de Places confiable y familiar de Google en tus casos de uso de frontend en el mapa que elijas.

Componentes

El kit de IU de Places ofrece un conjunto de componentes de IU individuales que se pueden usar de forma independiente o en conjunto para crear una experiencia de Places sin inconvenientes.

Place Details: Este componente renderiza información detallada sobre un lugar, como su nombre, dirección, número de teléfono, sitio web, horario de atención y opiniones de los usuarios.
Place Search: Este componente muestra una lista de lugares cercanos por categoría o a través de una búsqueda de texto libre.
Autocompletado de lugares básico: Este componente crea un campo de entrada de texto y presenta una lista desplegable de lugares predichos que coinciden con la entrada.

Beneficios clave del kit de IU de Places

Facilidad de uso: Incorpora la experiencia del usuario de confianza de Google Places en tus apps con un mínimo de código.
Uso en cualquier mapa: Por primera vez, puedes usar contenido de Lugares en un mapa que no sea de Google.
IU familiar: Los componentes proporcionan una interfaz de usuario coherente con la experiencia de Google Maps, lo que la hace intuitiva para los usuarios.
Personalización: El kit de IU de Places ofrece amplias opciones de personalización visual sin cargo adicional. Puedes usar una variedad de parámetros de configuración y propiedades de CSS personalizadas para configurar los elementos de visualización.
Rentable: El kit de IU de Places puede ser una solución más rentable en comparación con el uso directo de la API de Places.

Casos de uso reales

El kit de IU de Places se puede usar en una variedad de aplicaciones para mejorar la experiencia del usuario.

Aplicaciones de descubrimiento local: Una aplicación de "actividades" puede usar el componente de Place Search para mostrar una lista de restaurantes, cafés o atracciones cercanos. Cuando un usuario selecciona un lugar de la lista, se puede usar el componente Place Details para mostrar más información sobre esa ubicación.
Aplicaciones de planificación de viajes: Una aplicación de viajes puede usar la Búsqueda de lugares para permitir que los usuarios busquen hoteles o lugares de interés en una ciudad específica. Luego, el componente Place Details puede mostrar fotos, calificaciones y opiniones de cada ubicación para ayudar con la planificación.
Portales de búsqueda de bienes raíces y propiedades: Una aplicación de bienes raíces puede usar un componente de Place Search para mostrar diferentes categorías de lugares cercanos y ayudar a un posible comprador o inquilino de una casa a comprender el estilo de vida del vecindario antes de programar una visita.
Aplicaciones de mensajería y redes sociales: Una aplicación de mensajería y redes sociales puede usar la Búsqueda de lugares para buscar y sugerir lugares cercanos que ayuden a los usuarios a encontrar fácilmente un lugar de reunión. El componente Place Details se puede usar para mostrar la información enriquecida de los lugares cuando los usuarios los comparten. Con el botón integrado de Google Maps, los usuarios pueden explorar de forma fácil y precisa más ubicaciones e información de viajes en Google Maps.

Personalización

La riqueza del contenido y los estilos de los componentes del kit de IU de Places se pueden personalizar para satisfacer tus necesidades.

El uso de propiedades de CSS personalizadas, por ejemplo, las propiedades de CSS para el componente Place Details, te permite adaptar la apariencia de los componentes para que coincidan con el diseño de tu aplicación. Puedes personalizar los colores, las fuentes y otros aspectos visuales. Es importante cumplir con los requisitos de atribución cuando se realizan modificaciones visuales. Por ejemplo, puedes cambiar el color principal que se usa para los vínculos y los recuentos de opiniones con la propiedad --gmp-mat-color-primary de CSS.

Puedes controlar el contenido específico del lugar que se muestra con un elemento gmp-place-content-config anidado para seleccionar y configurar el contenido, o simplemente usar gmp-place-all-content para mostrar todo el contenido disponible.

En la documentación, se encuentra disponible una herramienta de personalización para ayudarte a visualizar diferentes configuraciones de estilo.

Orientación para la implementación

El kit de IU de Places está disponible a través de Maps JavaScript y el SDK de Places para Android y iOS.

Comenzar

Para comenzar a usar el kit de IU de Places, debes seguir estos pasos:

Configura tu proyecto de Google Cloud: Necesitas un proyecto de Cloud con una cuenta de facturación para usar el kit de IU de Places.
Habilita el kit de IU de Places: Debes habilitar el kit de IU de Places para tu proyecto.
Obtén una clave de API: Se requiere una clave de API para autenticar tus solicitudes.

Si quieres obtener más detalles específicos de la plataforma, consulta la guía de introducción al kit de IU de Places para JavaScript, Android y iOS.

Ejemplo de implementación

A continuación, se muestra un ejemplo de implementación de Place Search y Place Details con mapas dinámicos de JavaScript. Un usuario puede buscar lugares cercanos en función de texto libre. Cuando se hace clic en un lugar de la lista de resultados de la búsqueda, el componente Place Details se mostrará en los mapas dinámicos.

A continuación, se incluyen los fragmentos de código. Puedes encontrar la demostración y el código completo en este repositorio de GitHub.

Antes de comenzar, asegúrate de haber completado los pasos anteriores de Introducción relevantes para JavaScript.

Carga las bibliotecas requeridas en HTML.

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

En HTML, agrega un contenedor de mapa, un campo de entrada de texto y un botón de búsqueda. Este contenedor del mapa contendrá los mapas dinámicos que se crearán en JavaScript. El cuadro de entrada permite a los usuarios escribir consultas de búsqueda.

<div id="map-container"></div>
<div class="controls">
    <input type="text" class="query-input" />
    <button class="search-button">Search</button>
</div>

Agrega el componente Place Search. El componente Place Search proporciona diseños horizontales y verticales. En este ejemplo, usamos el diseño horizontal. El atributo "selectable" permite que se pueda hacer clic en el elemento de la lista de resultados de la búsqueda (se activará el evento gmp-select cuando se haga clic).

Dentro del elemento gmp-place-search, agregamos dos elementos secundarios:

gmp-place-all-content se usa para mostrar todo el contenido disponible
gmp-place-text-search-request se usa para configurar el elemento Place Search.

En este ejemplo, estableceremos la configuración en JavaScript.

<div class="list-container">
    <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>
</div>

A continuación, agrega el componente Place Details, que está disponible en diseños compactos y completos, y admite orientaciones verticales y horizontales. En este ejemplo, se usa el diseño horizontal compacto. Al igual que con el componente Place Search, agregamos dos elementos secundarios:

gmp-place-all-content indica que se muestra todo el contenido disponible
gmp-place-details-place-request se usa para seleccionar un lugar.

En este ejemplo, estableceremos el lugar en JavaScript.

<div id="details-container">
     <gmp-place-details-compact orientation="horizontal">
        <gmp-place-details-place-request></gmp-place-details-place-request> 
        <gmp-place-all-content></gmp-place-all-content>
    </gmp-place-details-compact> 
</div>

En JavaScript, importa las bibliotecas que necesitamos para este ejemplo. La biblioteca de Places importa la biblioteca del kit de IU de Places para JavaScript.

const {Map} = await google.maps.importLibrary("maps");
await google.maps.importLibrary("places");
({AdvancedMarkerElement} = await google.maps.importLibrary("marker"));
({LatLngBounds, LatLng} = await google.maps.importLibrary("core"));

Crear mapas dinámicos

const mapContainer = document.getElementById("map-container");
const mapOptions = {
    center: {lat: 37.422, lng: -122.085},
    zoom: 12 
};
const gMap = new Map(mapContainer, mapOptions);

Agrega un objeto de escucha de clics al botón de búsqueda para iniciar una búsqueda de lugares. Cuando se carguen los resultados de la búsqueda, crea marcadores para cada lugar y agrégales un objeto de escucha de clics. Si haces clic en un marcador, se solicitarán y mostrarán los detalles del lugar correspondientes.

Cuando se encuentran lugares y se carga el elemento Place Search, la propiedad places del elemento Place Search se completa con un array de resultados. Cada resultado es un objeto de lugar que contiene su ID de lugar, sus coordenadas y su viewport. Para recuperar los detalles, pasa el ID de lugar o el objeto de lugar completo al elemento Place Details.

const queryInput = document.querySelector(".query-input");
const searchButton = document.querySelector(".search-button");
const placeSearch = document.querySelector("gmp-place-search");
const placeSearchQuery = document.querySelector("gmp-place-text-search-request");
const placeDetails = document.querySelector("gmp-place-details-compact");
const placeRequest = document.querySelector("gmp-place-details-place-request");

placeDetailsPopup = new AdvancedMarkerElement({
    map: null,
    content: placeDetails,
    zIndex: 1
});

searchButton.addEventListener("click", searchPlaces);

function searchPlaces(){    
    if (queryInput.value.trim()) {
        placeSearchQuery.textQuery = queryInput.value.trim();
        placeSearchQuery.locationBias = gMap.getBounds();
        placeSearch.addEventListener('gmp-load', addMarkers, { once: true });
    }
}

async function addMarkers(){
    const bounds = new LatLngBounds();
    placeSearch.places.forEach((place) => {
        let marker = new AdvancedMarkerElement({
            map: gMap,
            position: place.location
        });
        bounds.extend(place.location);
        marker.addListener('click',(event) => {
            placeRequest.place = place;
            placeDetails.style.display = 'block';
            placeDetailsPopup.position = place.location;
            placeDetailsPopup.map = gMap;
            gMap.fitBounds(place.viewport, {top: 200, left: 100});
        });
        gMap.setCenter(bounds.getCenter());
        gMap.fitBounds(bounds);
    });
}

Asegúrate de consultar la demostración y el código completo en este repo de GitHub.

Recursos para ayudarte a crear

Colaboradores

Autores principales:

Teresa Qin | Ingeniera de soluciones de Google Maps Platform

¿Qué es el kit de IU de Places y cómo puedes usarlo para crear soluciones atractivas? Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.