Descoberta de lugares com PlaceSearchElement

Objetivo

Aprenda a integrar o PlaceSearchElement ao Google Maps para ajudar os usuários a encontrar lugares usando a pesquisa por perto ou de texto, melhorando a capacidade de explorar pontos de interesse. Use o elemento compacto de Place Details para fornecer mais detalhes sobre os Places que aparecem no seu aplicativo.

Observação: este guia explica os conceitos básicos. Para colocá-los em prática com uma implementação completa e guiada, faça o codelab Criar um app de pesquisa local com o Kit de Interface do Places.

O que é o PlaceSearchElement?

O PlaceSearchElement faz parte do Kit de Interface do Places na API Maps JavaScript. É um elemento HTML que renderiza os resultados de uma pesquisa de lugar diretamente em um formato de lista no seu aplicativo. Esse elemento simplifica o processo de exibição de Places encontrados usando um Nearby Search ou um Text Search, oferecendo uma experiência do usuário perfeita para a descoberta de Places. Quando um usuário seleciona um lugar na lista, você pode mostrar os detalhes dele no mapa, geralmente usando uma janela de informações e o elemento de detalhes do lugar.

Visualizar a descoberta de lugares

A imagem a seguir mostra um exemplo do PlaceSearchElement em ação. À esquerda, uma lista de restaurantes é mostrada (o PlaceSearchElement). Quando um restaurante é selecionado, os detalhes dele aparecem em uma janela de informações no mapa, e o mapa é centralizado na localização.

Casos de uso para descoberta de lugares

A integração do PlaceSearchElement pode melhorar vários aplicativos em diferentes setores:

• Viagens e turismo:permita que os turistas pesquisem atrações, hotéis ou tipos específicos de culinária em uma área.
• Imóveis:permita que compradores ou locatários em potencial encontrem escolas, supermercados ou opções de transporte público nas proximidades.
• Logística e serviços:ajude os motoristas a encontrar eletropostos, postos de gasolina ou centros de serviços específicos.

Fluxo de trabalho da solução: implementação da descoberta de lugares

Esta seção explica como integrar o PlaceSearchElement para descobrir lugares em um mapa e inclui snippets de código para interagir com o Kit de Interface do Places. Aprenda a inicializar o mapa e implementar o Nearby Search e o Text Search. Por fim, use o elemento de detalhes do lugar para mostrar mais informações sobre um lugar quando um usuário clicar no marcador dele no mapa.

Pré-requisitos

Recomendamos que você esteja familiarizado com a seguinte documentação:

• PlaceSearchElement : usado para expor lugares usando o Nearby Search ou o Text Search.
• Elemento Place Details : usado para mostrar detalhes de um lugar individual.
• API Maps JavaScript: usada para mostrar um mapa na sua página e importar o Kit de Interface do Places.

Ative a API Maps JavaScript e o Kit de Interface do Places no seu projeto.

Verifique se você carregou a API Maps JavaScript e importou as bibliotecas necessárias antes de começar. Este documento também pressupõe um conhecimento prático de desenvolvimento da Web, incluindo HTML, CSS e JavaScript.

Adicionar um mapa à página

A primeira etapa é adicionar um mapa à sua página. Esse mapa será usado para mostrar os resultados do PlaceSearchElement como marcadores selecionáveis.

Há duas maneiras de adicionar um mapa a uma página:

1. Usando um gmp-map componente da Web HTML.
2. Usando JavaScript.

Os snippets de código nesta página foram gerados usando um mapa JavaScript.

Dica: para um exemplo de como usar PlaceSearchElement com um mapa de componente da Web HTML, consulte a PlaceSearchElement documentação.

O mapa pode ser centralizado em um local em que você quer que o usuário pesquise, como um hotel, ou inicializado para pedir a localização atual do usuário para centralizar o mapa. Para fins deste documento, vamos usar um local fixo para ancorar a pesquisa.

Se você estiver visualizando lugares próximos a um local fixo, como um hotel, coloque um marcador no mapa para representar esse lugar. Por exemplo:

O mapa está centralizado em São Francisco, com um marcador azul para representar o lugar que estamos pesquisando nas proximidades. A cor do marcador foi personalizada usando PinElement. O controle de tipo de mapa foi ocultado da interface.

Configurar PlaceSearchElement

Agora, configure o HTML e o CSS para mostrar o PlaceSearchElement. Este exemplo flutua o elemento no lado esquerdo do mapa, mas você pode tentar layouts diferentes para se adequar ao seu aplicativo.

O PlaceSearchElement usa uma abordagem declarativa. Em vez de configurá-lo totalmente em JavaScript, você define o tipo de pesquisa diretamente no HTML aninhando um elemento de solicitação, como <gmp-place-nearby-search-request>, dentro do componente principal <gmp-place-search> component.

No código HTML, inicialize um elemento <gmp-place-search>. Use o atributo selectable para ativar eventos de clique nos resultados. Dentro dele, adicione um <gmp-place-nearby-search-request> para especificar que esse elemento será usado para pesquisa por perto.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Para realizar uma pesquisa inicial e mostrar os resultados, vamos usar JavaScript para receber uma referência ao elemento de solicitação aninhado e definir as propriedades dele. Inicialize um círculo para usar como locationRestriction, usando a posição do marcador da etapa anterior como o ponto central. Em seguida, defina as propriedades locationRestriction e includedPrimaryTypes no elemento de solicitação para acionar a pesquisa.

O snippet de código para isso é o seguinte:

// 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'];

Confira um exemplo de como o aplicativo pode ficar nessa fase:

Permitir que o usuário pesquise

O PlaceSearchElement permite duas opções de pesquisa:

• <gmp-place-nearby-search-request> - renderiza os resultados da pesquisa de um Places Nearby Search, usando Place Types.
• <gmp-place-text-search-request> - renderiza os resultados da pesquisa de texto de Lugaresusando uma entrada de texto livre como "Sushi em São Francisco".

Esses são elementos aninhados dentro de <gmp-place-search>. Em seguida, você aciona as pesquisas definindo propriedades nesse elemento de solicitação aninhado usando JavaScript.

Esta seção descreve a implementação dos dois métodos.

Pesquisa por perto

Para permitir que os usuários façam uma pesquisa por perto, primeiro você precisa de um elemento da interface para que eles selecionem um tipo de lugar. Escolha o método de seleção que funciona melhor para seu aplicativo, por exemplo, uma lista suspensa preenchida com uma seleção de tipos de lugares.

Recomendamos escolher um subconjunto de tipos relevantes para seu caso de uso. Por exemplo, se você estiver desenvolvendo um aplicativo para mostrar aos turistas o que está perto de um hotel, poderá escolher: bakery, coffee_shop, museum, restaurant e tourist_attraction.

O HTML precisa conter o elemento <gmp-place-search> com um <gmp-place-nearby-search-request> aninhado dentro.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

Em seguida, crie um listener JavaScript para o evento change no seletor de tipo de lugar. Esse listener vai chamar uma função que atualiza as propriedades do <gmp-place-nearby-search-request> elemento, que aciona automaticamente uma nova pesquisa e atualiza a 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];
}

O mesmo searchCircle da etapa de configuração é usado para locationRestriction. A propriedade includedPrimaryTypes é definida como o valor da seleção do usuário. Um maxResultCount opcional também é definido para limitar o número de resultados.

Pesquisa de texto

Para ativar a pesquisa de texto, a configuração HTML precisa ser alterada. Em vez da solicitação de pesquisa por perto, você aninha um <gmp-place-text-search-request> elemento.

<gmp-place-search selectable>
  <gmp-place-text-search-request>
  </gmp-place-text-search-request>
</gmp-place-search>

Adicione uma entrada de texto e um botão de pesquisa à interface. Crie um listener JavaScript para o evento click do botão. O manipulador de eventos vai receber a entrada do usuário e atualizar as propriedades do <gmp-place-text-search-request> elemento para realizar a pesquisa.

// 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;
}

Aqui, definimos a propriedade textQuery com a entrada do usuário. Também fornecemos um locationBias usando os limites atuais do mapa, que informa à API para preferir resultados nessa área sem restringi-los. Um maxResultCount opcional limita o número de resultados retornados.

Mostrar marcadores e detalhes do lugar

Agora, o aplicativo pode realizar uma pesquisa de lugar e preencher o elemento. Na próxima etapa, vamos melhorar a funcionalidade dele:

• Mostrar marcadores no mapa para cada lugar preenchido no PlaceSearchElement.
• Permitir que um usuário clique em um marcador ou no lugar dentro do PlaceSearchElement para mostrar mais detalhes sobre esse lugar específico.

O princípio dessa etapa é o mesmo, seja o aplicativo usando uma pesquisa por perto ou de texto.

Primeiro, adicione uma variável global ao código JavaScript para armazenar os marcadores de lugar. Isso permite removê-los quando a pesquisa muda e processar eventos de clique.

let markers = {};

Crie uma função para adicionar marcadores ao mapa. Essa função será chamada sempre que novos resultados de pesquisa forem carregados. Ela vai:

• Remover todos os marcadores de lugar do mapa.
• Fazer um loop nos resultados do PlaceSearchElement e adicionar um marcador para cada um.
• Ajustar os limites do mapa para que todos os novos marcadores fiquem visíveis.

Para detectar quando os resultados da pesquisa estão disponíveis, adicione um gmp-load listener de eventos ao elemento <gmp-place-search>. Esse evento é acionado depois que uma pesquisa é concluída e os resultados são renderizados.

Vamos adicionar o listener dentro da nossa função de pesquisa (por exemplo, updatePlaceList) e usar a opção { once: true } para garantir que ele seja acionado apenas para os resultados da pesquisa atual.

// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });

A função addMarkers é assim:

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

Depois que essa etapa for concluída, o aplicativo vai ficar assim, com a capacidade de mostrar marcadores para cada lugar retornado pelo PlaceSearchElement:

Agora que temos marcadores no mapa, a última etapa é processar eventos de clique de marcador e elemento para mostrar uma janela de informações com detalhes do lugar, fornecidos pelo elemento de detalhes do lugar. Para este exemplo, vamos usar o elemento compacto de Place Details.

Adicione o HTML do elemento compacto de Place Details ao seu código, por exemplo:

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

O style está definido como display: none; ele não ficará visível até ser necessário. gmp-place-all-content é transmitido para renderizar todo o conteúdo do elemento. Para escolher qual conteúdo renderizar, consulte a documentação do elemento compacto de detalhes do lugar.

Crie uma variável global em JavaScript para manter uma referência ao elemento compacto de Place Details e preencha isso no código de inicialização, por exemplo:

let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');

Na função addMarkers, adicione um listener de eventos gmp-click a cada marcador e configure o elemento compacto de detalhes do lugar para mostrar os detalhes do lugar transmitindo o ID do lugar do marcador atual.

Depois disso, uma janela de informações é aberta para mostrar o elemento compacto de Place Details, ancorado no marcador.

Por fim, o mapa é posicionado na janela de visualização do lugar selecionado, tornando-o visível.

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 o usuário clique em um lugar no elemento da lista de lugares para mostrar o elemento compacto de detalhes do lugar, adicione o seguinte ao código JavaScript após a chamada para configureFromSearchNearbyRequest.

placeSearchElement.addEventListener("gmp-select", ({ place }) => {
    if (markers[place.id]) {
        markers[place.id].click();
    }
});

Depois que essa etapa for concluída, o aplicativo poderá usar uma Nearby Search ou Text Search para preencher o elemento da lista de lugares. Os resultados vão mostrar marcadores no mapa, e clicar em um marcador ou em um lugar no elemento da lista de lugares vai mostrar uma janela de informações com detalhes do lugar, fornecidos pelo elemento compacto de detalhes do lugar.

O aplicativo vai ficar assim:

Conclusão

O PlaceSearchElement combinado com o elemento compacto de Place Details oferece uma maneira simplificada de adicionar recursos avançados de descoberta de lugares aos aplicativos da Plataforma Google Maps.

Teste o Kit de Interface do Places hoje mesmo para permitir que os usuários encontrem e explorem lugares usando pesquisas por perto e de texto e mostrem detalhes avançados do lugar, melhorando a interação com os casos de uso de descoberta de lugares.

Colaboradores

Henrik Valve | Engenheiro de DevX