Adotar o Kit de Interface do Places para usuários da API Places

Objetivo: substitua sua implementação da API Places ou da classe Place pelo Places UI Kit.

Público-alvo deste guia

Desenvolvedores que:

  • Fazer solicitações HTTP para endpoints da API Places (nova ou legada).
  • Usando a classe Place na API Maps JavaScript.
  • Processamento da resposta da API para renderizar informações de lugar na interface do aplicativo da Web.

Pré-requisitos

Ative o Kit de interface do usuário do Places no seu projeto do Google Cloud. Você pode continuar usando sua chave de API atual ou gerar uma nova para o kit de interface do Places. Consulte Usar chaves de API para mais informações, incluindo como restringir uma chave.

Atualizar o carregamento da API Maps JavaScript

O Kit de Interface do Places exige o método Dynamic Library Import para carregar a API Maps JavaScript. Se você estiver usando a tag de carregamento direto de script, ela precisará ser atualizada.

Depois de atualizar o script de carregamento da API Maps JavaScript, importe as bibliotecas necessárias para usar o Kit de Interface do Places.

Implementar o elemento Place Details

O elemento Place Details Element e o elemento Place Details Compact Element são elementos HTML que renderizam detalhes de um lugar.

Implementação atual

  • Você faz uma chamada de detalhes do lugar usando uma solicitação HTTP ou usa a classe Place da API JavaScript.
  • Você analisa a resposta da API e mostra os detalhes do lugar usando HTML e CSS.

Migração para o elemento de detalhes do lugar

Modificar a estrutura HTML

Identifique o contêiner HTML em que os detalhes do lugar são renderizados. Substitua seus elementos HTML personalizados (divs, spans para nome, endereço, fotos etc.) pelo HTML do elemento de detalhes do lugar.

Há dois elementos para escolher:

  • Elemento compacto de Place Details
  • Elemento Place Details

Para mais informações sobre qual usar, consulte Elemento de detalhes do lugar.

Seu HTML atual pode ser parecido com este.

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

Exemplo de novo HTML, declarando explicitamente qual conteúdo será exibido:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

Adaptar a lógica do JavaScript

Lógica atual

Sua lógica atual provavelmente envolve:

  • Recuperar um ID de lugar.
  • Usando PlacesService().getDetails() ou fazendo uma chamada de serviço da Web.
  • Especificar uma matriz de campos (para a API JS) ou um FieldMask (para o serviço Web) para solicitar dados específicos.
  • Na resolução de callback, selecione manualmente os elementos HTML e preencha-os com os dados recebidos.

Confira um exemplo de como você pode ter implementado os detalhes do lugar:

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}
Nova lógica

Sua nova lógica vai envolver:

  • Recupere seu ID de lugar ou objeto de lugar.
  • Receba uma referência ao elemento <gmp-place-details-place-request>.
  • Transmita o ID ou o objeto de lugar para a propriedade de lugar no elemento <gmp-place-details-place-request>.

Confira a seguir um exemplo de como implementar o kit de interface de detalhes do lugar na lógica JavaScript. Receba uma referência ao elemento de detalhes do lugar. Se ele existir, receba uma referência ao elemento de solicitação de lugar do Place Details e defina a propriedade "place" usando um ID de lugar. No exemplo de código HTML acima, o estilo do elemento de detalhes do lugar está definido como display: none. Atualizado para display: block.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

O elemento de pesquisa de lugar é um elemento HTML que renderiza os resultados de uma pesquisa de lugar em uma lista.

  • Você faz uma pesquisa de texto ou uma pesquisa nas proximidades usando uma solicitação HTTP ou a classe Place da API JavaScript.
  • Você especifica parâmetros de consulta, restrições ou tendências de local, tipos e campos solicitados usando FieldMask.
  • Você analisa a resposta da API, itera pela matriz de lugares e cria manualmente itens de lista HTML.

Modificar a estrutura HTML

Identifique o contêiner HTML em que você renderiza sua lista de lugares. Substitua seus elementos HTML personalizados (divs, spans para nome, endereço etc.) pelo elemento HTML de pesquisa de lugar.

Seu HTML atual pode ser parecido com isto:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

O elemento Place Search é implementado usando o componente <gmp-place-search>. Para configurar o tipo de pesquisa, inclua um dos seguintes componentes de configuração com slot dentro de:

  • <gmp-place-text-search-request> para uma pesquisa de texto.
  • <gmp-place-nearby-search-request> para uma pesquisa nas proximidades.

Para definir como os resultados são mostrados, use o atalho <gmp-place-all-content> ou forneça seu próprio conjunto de componentes de apresentação individuais. Atributos principais, como selectable (para permitir cliques em itens da lista) e orientation (para um layout horizontal ou vertical), podem ser definidos diretamente no componente pai.

Exemplo de Nearby Search
<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>
Exemplo de pesquisa de texto
<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>

Adaptar a lógica do JavaScript

No JavaScript, receba uma referência ao componente do controlador de pesquisa usando document.querySelector(). Dependendo da sua configuração, esse será o elemento <gmp-place-text-search-request> ou <gmp-place-nearby-search-request>.

Em seguida, defina as propriedades nesse controlador para definir sua pesquisa. As propriedades necessárias dependem do tipo de pesquisa que você está realizando.

Para uma pesquisa de texto (<gmp-place-text-search-request>), a propriedade principal é textQuery:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

Para uma pesquisa de negócios próximos (<gmp-place-nearby-search-request>), defina a área de pesquisa usando um locationRestriction. Em seguida, use includedTypes para filtrar tipos específicos de lugares nessa área:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

O componente pai <gmp-place-search> inicia automaticamente uma nova pesquisa assim que as propriedades obrigatórias do controlador são definidas.

  • Para uma pesquisa de texto, a pesquisa é executada no momento em que você atribui um valor a textQuery.
  • Para uma pesquisa nas proximidades, a pesquisa é executada depois que um locationRestriction válido é fornecido.

Implementar o elemento básico do Place Autocomplete

Para desenvolvedores que precisam de uma experiência de pesquisa sem a interface fornecida pelo elemento de pesquisa de lugares, o elemento Basic Place Autocomplete está disponível.

Esse elemento é ideal para criar um campo de entrada de pesquisa e manter o controle total sobre como os resultados são mostrados na interface do usuário personalizada. A única responsabilidade do elemento de preenchimento automático é fornecer previsões de lugares à medida que o usuário digita e expor programaticamente um ID de lugar para o lugar selecionado.

Ele não mostra detalhes nem fornece outras informações acessíveis por programação.

Implementação atual

Sua lógica atual provavelmente envolve:

  • Renderizar um campo de entrada de texto na sua página que chama o Place Autocomplete conforme o usuário digita, mostrando os resultados.
  • Usando o ID de lugar do local selecionado pelo usuário para buscar mais detalhes, por exemplo, usando a API Place Details.
  • Mostrando detalhes do lugar selecionado.

Migração para o elemento Place Autocomplete

Modificar a estrutura HTML

Identifique e remova o elemento HTML ao qual você anexa o widget de preenchimento automático. Provavelmente, ele está usando um campo de entrada HTML padrão.

<input id="pac-input" type="text" placeholder="Search for a location" />

Exemplo de novo HTML, usando a abordagem de componente da Web para inicializar um elemento de preenchimento automático de lugar básico na sua página.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

Adaptar a lógica do JavaScript

Sua lógica JavaScript provavelmente envolve a criação do widget de preenchimento automático anexado a um elemento HTML input. Em seguida, esse widget detecta o evento place_changed, acionando uma ação com os dados retornados.

Exemplo de JavaScript atual a ser removido:

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

Sua nova lógica JavaScript vai receber uma referência ao elemento de preenchimento automático básico de lugares e detectar eventos gmp-select:

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

Quando um lugar é selecionado no menu suspenso de preenchimento automático, o evento gmp-select é acionado. O ID do lugar selecionado pode ser extraído do objeto event. O ID do lugar pode ser usado para inicializar uma instância do elemento de detalhes do lugar e mostrar os detalhes do lugar selecionado.

Personalização de alças

Personalização do elemento Place Details

Orientação

O elemento de detalhes do lugar pode ser renderizado na orientação horizontal e vertical. Use o atributo orientation em gmp-place-details-compact para escolher entre vertical e horizontal. Exemplo:

<gmp-place-details-compact orientation="vertical">

Escolher os campos para renderizar

Use elementos de conteúdo para especificar o conteúdo a ser renderizado no elemento de detalhes do lugar. Por exemplo, excluir o elemento de conteúdo <gmp-place-type> impediria que o elemento de detalhes do lugar renderizasse o tipo do lugar selecionado. Para uma lista completa de elementos de conteúdo, consulte a documentação de referência de PlaceContentConfigElement.

Adicionar ou remover campos do elemento de detalhes do lugar não muda o custo de renderização do elemento na página.

Definir estilos CSS

Propriedades CSS personalizadas estão disponíveis para configurar as cores e fontes do elemento. Por exemplo, para definir o plano de fundo do elemento como verde, defina a seguinte propriedade CSS:

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

Consulte a documentação de referência de PlaceDetailsCompactElement para mais detalhes.

Personalização do elemento Place Search

Orientação

O elemento de pesquisa de lugar pode ser renderizado na orientação horizontal e vertical. Use o atributo orientation em <gmp-place-search> para escolher entre vertical e horizontal. Exemplo:

<gmp-place-search orientation="horizontal" selectable>

Escolher os campos para renderizar

Use elementos de conteúdo para especificar o conteúdo a ser renderizado no elemento de pesquisa de lugar. O elemento <gmp-place-all-content> pode ser usado para mostrar todo o conteúdo, ou uma seleção de tags HTML pode ser usada para configurar o conteúdo renderizado.

Incluir <gmp-place-address> em <gmp-place-content-config> apenas renderizaria o endereço de cada lugar, por exemplo:

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Personalização básica do elemento Place Autocomplete

Definir estilos CSS

Propriedades CSS personalizadas estão disponíveis para personalizar a aparência e a funcionalidade do elemento de preenchimento automático. Por exemplo, para definir a cor de fundo como roxo claro, defina a propriedade background-color no elemento.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

Consulte a documentação de referência do BasicPlaceAutocompleteElement para mais detalhes.

Processar eventos e dados

Os elementos do kit de interface do Places são componentes interativos que permitem detectar eventos e recuperar dados de forma programática.

Detectar eventos

É possível adicionar listeners de eventos aos elementos para acionar ações com base na interação do usuário ou no estado do elemento.

Evento de seleção

  • gmp-select: esse evento é acionado quando um usuário faz uma seleção.
    • No elemento de pesquisa de lugar, ele é acionado quando um usuário clica em um lugar na lista de resultados.
    • No elemento básico de preenchimento automático de lugar, ele é acionado quando um usuário clica em uma previsão na lista suspensa.

Eventos comuns

Os elementos Place Search, Place Details e Basic Place Autocomplete são compatíveis com os seguintes eventos:

  • gmp-load: disparado quando o elemento e o conteúdo dele terminam de carregar e renderizar.
  • gmp-requesterror: disparado quando uma solicitação ao servidor falha, por exemplo, devido a uma chave de API inválida.

Acessar dados de elementos de maneira programática

É possível recuperar dados específicos dos elementos de forma programática depois que eles forem interagidos ou carregados.

  • Para o elemento de pesquisa de lugar e o elemento de detalhes do lugar, é possível recuperar as seguintes informações:
    • ID do lugar
    • Local (latitude e longitude)
    • Janela de visualização
  • Para o elemento básico do Place Autocomplete, é possível recuperar as seguintes informações:
    • ID do lugar

Todos os outros dados contidos nos elementos não são acessíveis por programação.

Para exemplos mais detalhados, consulte a documentação individual do elemento de pesquisa de lugar, do elemento de detalhes de lugar e do elemento básico de preenchimento automático de lugar.

Teste e refinamento

Depois de integrar os elementos do kit de interface do Places, o teste é crucial para uma transição tranquila e uma experiência positiva do usuário. Seus testes precisam abranger várias áreas principais, abordando todos os elementos implementados: Place Details, Place Search e Basic Place Autocomplete.

Elemento de detalhes do lugar

Para o elemento Detalhes do lugar, comece verificando se os detalhes são mostrados corretamente para uma variedade de lugares. Teste transmitindo vários IDs de lugar para a propriedade .place do elemento <gmp-place-details-place-request>. Use IDs que representam diferentes tipos de estabelecimentos (empresas com dados avançados, pontos de interesse, endereços básicos) e lugares em diferentes regiões ou idiomas. Preste muita atenção à formatação, ao layout e à presença do conteúdo.

Elemento de pesquisa de lugar

Se você implementou o elemento de pesquisa de lugar, verifique a renderização e o comportamento dele em diferentes cenários de pesquisa.

  • Para uma pesquisa de texto, teste definindo a propriedade textQuery no elemento <gmp-place-text-search-request> com várias entradas: consultas amplas, endereços específicos e consultas com tendências de local.
  • Para uma Nearby Search, teste definindo as propriedades locationRestriction e includedTypes no elemento <gmp-place-nearby-search-request>. Use diferentes tamanhos de local e filtros de tipo.

Confirme se a lista é preenchida com resultados relevantes e se o evento gmp-select é acionado corretamente após a seleção.

Elemento básico do Place Autocomplete

Para o elemento básico de preenchimento automático de lugar, concentre os testes na interação do usuário e nos dados transmitidos pelo evento de seleção. Confirme se o evento gmp-select é acionado de forma confiável quando um usuário clica em uma previsão. Verifique se o objeto event.place no manipulador de eventos contém um ID de lugar válido.

O mais importante é testar o fluxo de ponta a ponta: selecione um lugar no menu suspenso do Autocomplete e verifique se o ID do lugar pode ser usado para preencher outro elemento, como o elemento Place Details.

Tratamento de erros

É essencial testar rigorosamente o tratamento de erros em todos os componentes. Simule a transmissão de IDs de lugar inválidos ou inexistentes para o elemento Place Details ou o uso de parâmetros de pesquisa inválidos para o elemento Place Search. Acione o evento gmp-requesterror simulando problemas de rede ou usando uma chave de API inválida para garantir que o aplicativo lide com isso de maneira adequada. Implemente mensagens de erro e registros fáceis de usar para evitar uma interface do usuário confusa ou corrompida.