Criar um localizador de lojas interativo com o Kit de Interface do Places

Objetivo

Este documento descreve as principais etapas para desenvolver um aplicativo interativo de localizador de lojas usando a Plataforma Google Maps, especificamente a API JavaScript do Maps e o Kit de Interface do Places: Elemento de detalhes do lugar. Você vai aprender a criar um mapa que mostra os locais das lojas, atualizar dinamicamente uma lista de lojas visíveis e exibir informações detalhadas sobre cada loja.

Pré-requisitos

Recomendamos que você tenha familiaridade com o seguinte:

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 para Marcadores avançados e o kit de interface do Places antes de começar. Este documento também pressupõe um conhecimento prático de desenvolvimento da Web, incluindo HTML, CSS e JavaScript.

Configuração inicial

A primeira etapa é adicionar um mapa à página. Esse mapa será usado para mostrar marcadores relacionados aos locais das suas lojas.

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

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

Escolha o método mais adequado para seu caso de uso. As duas formas de implementar o mapa funcionam com este guia.

Demonstração

Esta demonstração mostra um exemplo do localizador de lojas em ação, exibindo os locais dos escritórios do Google na área da Baía. O elemento de detalhes do lugar é mostrado para cada local, junto com alguns exemplos de atributos.

Carregar e mostrar locais da loja

Nesta seção, vamos carregar e mostrar os dados da loja no mapa. Este guia pressupõe que você tenha um repositório de informações sobre suas lojas atuais para usar. Os dados da loja podem vir de várias fontes, como seu banco de dados. Neste exemplo, vamos usar um arquivo JSON local (stores.json) com uma matriz de objetos de loja, cada um representando um local. Cada objeto precisa conter pelo menos um name, um location (com lat e lng) e um place_id.

Há várias maneiras de recuperar os IDs de lugar dos locais da sua loja, caso você ainda não os tenha. Consulte a documentação do ID de lugar para mais informações.

Uma entrada de detalhes da loja de exemplo no arquivo stores.json pode ter esta aparência. Há campos para Nome, Local (lat/lng) e ID do lugar. Há um objeto para armazenar o horário de funcionamento da loja (truncado). Há também dois valores booleanos para ajudar a descrever recursos personalizados do local da loja.

{
  "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
}

No seu código JavaScript, busque os dados dos locais da loja e mostre um alfinete no mapa para cada um deles.

Confira um exemplo de como fazer isso. Essa função usa um objeto que contém os detalhes das lojas e cria um marcador com base na localização de cada uma delas.

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

Depois de carregar as lojas e mostrar alfinetes representando os locais delas no mapa, crie uma barra lateral usando HTML e CSS para exibir detalhes sobre cada loja.

Confira um exemplo de como o localizador de lojas pode ficar nesta etapa:

imagem

Detectar mudanças na janela de visualização do mapa

Para otimizar a performance e a experiência do usuário, atualize seu aplicativo para mostrar marcadores e detalhes na barra lateral somente quando os locais correspondentes estiverem na área visível do mapa (janela de visualização). Isso envolve detectar mudanças na janela de visualização do mapa, remover a repetição desses eventos e redesenhar apenas os marcadores necessários.

Anexe um listener de eventos ao evento de inatividade do mapa. Esse evento é disparado depois que todas as operações de panorâmica ou zoom são concluídas, fornecendo uma janela de visualização estável para seus cálculos.

map.addListener('idle', debounce(updateMarkersInView, 300));

O snippet de código acima detecta o evento idle e chama uma função debounce. Usar uma função de remoção de duplicação garante que a lógica de atualização do marcador só seja executada depois que o usuário para de interagir com o mapa por um curto período, melhorando o desempenho.

function debounce(func, delay) {
    let timeoutId;
    return function(...args) {
        const context = this;
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
            func.apply(context, args);
        }, delay);
    };
}

O código acima é um exemplo de função de debounce. Ele usa uma função e um argumento de atraso, que podem ser vistos transmitidos no listener ocioso. Um atraso de 300 ms é suficiente para esperar que o mapa pare de se mover, sem adicionar um atraso perceptível à interface. Quando esse tempo limite expira, a função transmitida é chamada, neste caso, updateMarkersInView.

A função updateMarkersInView precisa realizar as seguintes ações:

Limpar todos os marcadores atuais do mapa

Verifique se o local da loja está dentro dos limites atuais do mapa, por exemplo:

if (map.getBounds().contains(storeLatLng)) {
  // logic
}

Na instrução "if" acima, escreva um código para mostrar os marcadores e os detalhes da loja na barra lateral, se o local da loja estiver dentro da janela de visualização do mapa.

Mostrar detalhes avançados do lugar usando o elemento Place Details

Nesta etapa, o aplicativo mostra todos os locais da loja, e os usuários podem filtrá-los com base na janela de visualização do mapa. Para melhorar isso, detalhes avançados sobre cada loja, como fotos, avaliações e informações de acessibilidade, são adicionados usando o elemento de detalhes do lugar. Este exemplo usa especificamente o Elemento compacto de detalhes do lugar.

Cada local da loja na sua fonte de dados precisa ter um ID do lugar correspondente. Esse ID identifica de forma exclusiva o local no Google Maps e é essencial para buscar os detalhes dele. Normalmente, você adquire esses IDs de lugar com antecedência e os armazena em cada um dos registros da loja.

Integrar o elemento compacto de detalhes do lugar ao aplicativo

Quando uma loja está dentro da janela de visualização do mapa atual e é renderizada na barra lateral, é possível criar e inserir dinamicamente um elemento compacto de detalhes do lugar.

Para a loja atual em processamento, recupere o ID do lugar dos seus dados. O ID do lugar é usado para controlar qual lugar o elemento vai mostrar.

Em JavaScript, crie dinamicamente uma instância de PlaceDetailsCompactElement. Um novo PlaceDetailsPlaceRequestElement também é criado, o ID do lugar é transmitido para ele, e isso é anexado ao PlaceDetailsCompactElement. Por fim, use PlaceContentConfigElement para configurar o conteúdo que o elemento vai mostrar.

A função a seguir pressupõe que as bibliotecas necessárias do Place UI Kit foram importadas e estão disponíveis no escopo em que essa função é chamada, e storeData transmitido para a função contém place_id.

Essa função vai retornar o elemento, e o código de chamada será responsável por anexá-lo ao 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;
}

No exemplo de código acima, o elemento está configurado para mostrar as fotos do lugar, a classificação da avaliação e as informações de acessibilidade. É possível personalizar isso adicionando ou removendo outros elementos de conteúdo disponíveis. Consulte a documentação de PlaceContentConfigElement para todas as opções disponíveis.

O elemento compacto de detalhes do lugar é compatível com estilização usando propriedades personalizadas de CSS. Isso permite personalizar a aparência (cores, fontes etc.) para corresponder ao design do aplicativo. Aplique essas propriedades personalizadas no arquivo CSS. Consulte a documentação de referência de PlaceDetailsCompactElement para as propriedades CSS compatíveis.

Exemplo de como seu aplicativo pode ficar nesta etapa:

imagem

Melhorar o localizador de lojas

Você criou uma base sólida para seu aplicativo de pesquisa de lojas. Agora, considere várias maneiras de estender a funcionalidade e criar uma experiência ainda mais rica e centrada no usuário.

Adicionar preenchimento automático

Melhore a forma como os usuários encontram áreas para pesquisar lojas integrando uma entrada de pesquisa com o Place Autocomplete. Quando os usuários digitarem um endereço, bairro ou ponto de interesse e selecionarem uma sugestão, programe o mapa para centralizar automaticamente nesse local, acionando uma atualização das lojas próximas. Para isso, adicione um campo de entrada e anexe a funcionalidade do Place Autocomplete a ele. Ao selecionar uma sugestão, o mapa pode ser centralizado nesse ponto. Não se esqueça de configurar para direcionar ou restringir os resultados à sua área operacional.

Detectar local

Ofereça relevância imediata, principalmente para usuários de dispositivos móveis, implementando a funcionalidade para detectar a localização geográfica atual. Depois de receber a permissão do navegador para detectar a localização, centralize automaticamente o mapa na posição e mostre as lojas mais próximas. Os usuários valorizam muito o recurso Perto de mim ao procurar opções imediatas. Adicione um botão ou um comando inicial para solicitar acesso à localização.

Mostrar distância e rotas

Depois que um usuário identificar uma loja de interesse, melhore significativamente a jornada dele integrando a API Routes. Para cada loja listada, calcule e mostre a distância da localização atual do usuário ou do local pesquisado. Além disso, forneça um botão ou link que use a API Routes para gerar um trajeto da localização do usuário até a loja selecionada. Em seguida, você pode mostrar esse trajeto no mapa ou criar um link para o Google Maps para navegação, criando uma transição perfeita entre encontrar uma loja e chegar até ela.

Ao implementar essas extensões, você pode usar mais recursos da Plataforma Google Maps para criar um localizador de lojas mais abrangente e conveniente que atenda diretamente às necessidades comuns dos usuários.

Conclusão

Este guia mostrou as etapas principais para criar um localizador de lojas interativo. Você aprendeu a mostrar os locais das suas lojas em um mapa usando a API Maps JavaScript, atualizar dinamicamente as lojas visíveis com base nas mudanças da janela de visualização e, principalmente, mostrar os dados da sua loja de acordo com o kit de interface do Places. Ao usar as informações da loja, incluindo IDs de lugar, com o elemento Place Details, você pode apresentar detalhes padronizados e completos de cada um dos seus locais, criando uma base sólida para um localizador de lojas fácil de usar.

Experimente a API Maps JavaScript e o Places UI Kit para oferecer ferramentas eficientes baseadas em componentes e desenvolver rapidamente aplicativos sofisticados baseados em localização. Ao combinar esses recursos, você pode criar experiências envolventes e informativas para os usuários.

Colaboradores

Henrik Valve | Engenheiro de DevX