Esta página foi traduzida pela API Cloud Translation.

O que é o Kit de Interface do Places e como usá-lo para criar soluções envolventes?

Introdução

Para milhões de usuários no mundo todo, o Google Maps é a fonte de informações precisas e atualizadas sobre lugares. O banco de dados do Google, com mais de 250 milhões de lugares no mundo todo, incluindo avaliações, fotos e classificações de usuários, oferece um nível de detalhe e confiança incomparável. Para oferecer dados atualizados e precisos, fazemos 100 milhões de atualizações no mapa todos os dias.

O Kit de Interface do Places é uma biblioteca de componentes pronta para uso e econômica, com a tecnologia das informações abrangentes do Google Maps sobre lugares. Ele permite integrar a experiência confiável e conhecida do Google Places aos seus casos de uso de front-end em um mapa de sua escolha.

Componentes

O Kit de Interface do Places oferece um conjunto de componentes de interface individuais que podem ser usados de forma independente ou em conjunto para criar uma experiência integrada do Places.

Place Details:esse componente renderiza informações detalhadas sobre um lugar, como nome, endereço, número de telefone, site, horário de funcionamento e avaliações dos usuários.
Pesquisa de lugar:esse componente mostra uma lista de lugares por perto categorizados ou por pesquisa de texto livre.
Preenchimento automático básico de lugares:esse componente cria um campo de entrada de texto, apresentando uma lista suspensa de lugares previstos que correspondem à entrada.

Componentes do kit de interface do Places

Principais benefícios do Kit de Interface do Places

Facilidade de uso:incorpore a experiência do usuário confiável do Google para o Places nos seus apps com o mínimo de código.
Uso em qualquer mapa:pela primeira vez, você pode usar o conteúdo do Places em um mapa que não seja do Google.
Interface familiar:os componentes oferecem uma interface do usuário consistente com a experiência do Google Maps, o que a torna intuitiva para os usuários.
Personalização:o kit de interface do Places oferece várias opções de personalização visual sem custo extra. Você pode usar várias configurações e propriedades CSS personalizadas para configurar os elementos de exibição.
Econômico:o Kit de Interface do Places pode ser uma solução mais econômica em comparação com o uso direto da API Places.

Casos de uso reais

O Kit de Interface do Places pode ser usado em vários aplicativos para melhorar a experiência do usuário.

Aplicativos de descoberta local:um aplicativo de "coisas para fazer" pode usar o componente Pesquisa de lugar para mostrar uma lista de restaurantes, cafés ou atrações nas proximidades. Quando um usuário seleciona um lugar na lista, o componente Place Details pode ser usado para mostrar mais informações sobre ele.
Aplicativos de planejamento de viagens:um aplicativo de viagens pode usar a pesquisa de lugar para permitir que os usuários pesquisem hotéis ou pontos de interesse em uma cidade específica. O componente Detalhes do lugar pode mostrar fotos, notas e avaliações de cada local para ajudar no planejamento.
Portais de pesquisa de imóveis e propriedades:um aplicativo imobiliário pode usar um componente de pesquisa de lugar para mostrar diferentes categorias de lugares próximos e ajudar um possível comprador ou locatário a entender o estilo de vida do bairro antes de agendar uma visita.
Aplicativos de mensagens e mídias sociais:um aplicativo de mensagens e mídias sociais pode usar a Pesquisa de lugares para pesquisar e sugerir lugares próximos e ajudar os usuários a encontrar um local de encontro com facilidade. O componente Place Details pode ser usado para mostrar informações detalhadas sobre lugares quando os usuários compartilham locais. Com o botão pré-criado do Google Maps, os usuários podem explorar facilmente e com precisão mais locais e informações de viagem no Google Maps.

Personalização

A riqueza do conteúdo e os estilos dos componentes do Places UI Kit podem ser personalizados para atender às suas necessidades.

Usar propriedades CSS personalizadas, por exemplo, as propriedades CSS do componente de detalhes do lugar, permite adaptar a aparência dos componentes para corresponder ao design do seu aplicativo. É possível personalizar cores, fontes e outros aspectos visuais. É importante obedecer aos requisitos de atribuição ao fazer modificações visuais. Por exemplo, é possível mudar a cor principal usada para links e contagens de avaliações com a propriedade CSS --gmp-mat-color-primary.

Você pode controlar o conteúdo específico do lugar exibido usando um elemento gmp-place-content-config aninhado para selecionar e configurar o conteúdo ou simplesmente usar gmp-place-all-content para mostrar todo o conteúdo disponível.

Uma ferramenta de personalização está disponível na documentação para ajudar você a visualizar diferentes configurações de estilo.

Diretrizes para implementação

O Kit de Interface do Places está disponível no JavaScript do Maps e no SDK do Places para Android e iOS.

Primeiros passos

Para começar a usar o Kit de Interface do Places, siga estas etapas:

Configure seu projeto do Google Cloud: você precisa de um projeto do Cloud com uma conta de faturamento para usar o kit de interface do Places.
Ative o Kit de Interface do Places: é necessário ativar o Kit de Interface do Places para seu projeto.
Receba uma chave de API: uma chave de API é necessária para autenticar suas solicitações.

Para mais detalhes específicos da plataforma, confira as orientações para iniciantes do kit de interface do Places para JavaScript, Android e iOS.

Exemplo de implementação

Confira um exemplo de implementação de uma pesquisa de lugar e detalhes do lugar com mapas dinâmicos em JavaScript. Um usuário pode pesquisar lugares próximos com base em texto livre. Ao clicar em um lugar na lista de resultados da pesquisa, o componente "Detalhes do lugar" vai aparecer nos mapas dinâmicos.

Confira abaixo os snippets de código. Confira a demonstração e o código completo neste repositório do GitHub.

Antes de começar, confira se você concluiu as etapas acima em "Como começar" relevantes para JavaScript.

Carregue as bibliotecas necessárias em 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>

Em HTML, adicione um contêiner de mapa, um campo de entrada de texto e um botão de pesquisa. Esse contêiner de mapa vai conter os mapas dinâmicos que serão criados em JavaScript. A caixa de entrada permite que os usuários digitem consultas de pesquisa.

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

Adicione o componente Place Search. O componente Place Search oferece layouts horizontais e verticais. Neste exemplo, usamos o layout horizontal. O atributo "selectable" permite que o item da lista de resultados da pesquisa seja clicável (o evento gmp-select será acionado quando clicado).

Dentro do elemento gmp-place-search, adicionamos dois elementos filhos:

O gmp-place-all-content é usado para mostrar todo o conteúdo disponível
gmp-place-text-search-request é usado para configurar o elemento de pesquisa de lugar.

Vamos definir a configuração em JavaScript neste exemplo

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

Em seguida, adicione o componente "Detalhes do lugar", que está disponível em layouts compactos e completos, cada um com suporte a orientações verticais e horizontais. Este exemplo usa o layout horizontal compacto. Assim como no componente Place Search, adicionamos dois elementos filhos:

gmp-place-all-content indica que todo o conteúdo disponível está sendo mostrado
gmp-place-details-place-request é usado para selecionar um lugar.

Neste exemplo, vamos definir o lugar em 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>

Em JavaScript, importe as bibliotecas necessárias para este exemplo. A biblioteca Places importa a biblioteca do Kit de Interface do 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"));

Crie 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);

Adicione um listener de clique ao botão de pesquisa para iniciar uma pesquisa de lugar. Quando os resultados da pesquisa forem carregados, crie marcadores para cada lugar e adicione um listener de clique a eles. Clicar em um marcador vai solicitar e mostrar os detalhes do lugar correspondente.

Quando os lugares são encontrados e o elemento Place Search é carregado, a propriedade "places" do elemento é preenchida com uma matriz de resultados. Cada resultado é um objeto de lugar que contém o ID, as coordenadas e a janela de visualização dele. Para buscar detalhes, transmita o ID do lugar ou o objeto de lugar inteiro para o 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);
    });
}

Confira a demonstração e o código completo neste repositório do GitHub.

Fontes para ajudar você a criar

Colaboradores

Principais autores:

Teresa Qin | Engenheira de soluções da Plataforma Google Maps

O que é o Kit de Interface do Places e como usá-lo para criar soluções envolventes? Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.