O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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

Saiba como migrar sua implementação atual da API Places ou da classe Place para os componentes do Kit de Interface do Places.

Público-alvo deste guia

Este guia é destinado a desenvolvedores que já têm uma implementação usando a API Places e querem atualizar o código para usar o Kit de Interface do Places. Será mais útil se você já:

Fazer solicitações HTTP para endpoints da API Places (nova ou legada).
Como usar a classe Place na API Maps JavaScript.
Processar a resposta da API para renderizar informações de lugares na interface do seu aplicativo da Web.

Pré-requisitos

Ative o Kit de interface do Places no seu projeto na nuvem 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 de carregamento Dynamic Library Import da 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

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

Implementação atual

Você faz uma chamada do Place Details usando uma solicitação HTTP ou a classe Place da API JavaScript.
Você analisa a resposta da API e exibe os Place Details usando HTML e CSS.

Migração para o elemento Place Details

Modificar a estrutura HTML

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

Há dois elementos para escolher:

Elemento compacto de Place Details
Elemento Place Details

Para mais informações sobre qual usar, consulte Elemento Place Details.

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, indicando explicitamente qual conteúdo mostrar:

<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.
Usar PlacesService().getDetails() ou fazer uma chamada de serviço da Web.
Especificar uma matriz de campos (para a API JS) ou FieldMask (para o serviço Web) para solicitar dados específicos.
Na resolução do callback, selecione manualmente os elementos HTML e preencha-os com os dados recebidos.

Veja um exemplo de como implementar o Place Details:

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 o ID ou o objeto de lugar.
Acesse uma referência ao elemento <gmp-place-details-place-request>.
Transmita o ID de lugar 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 do Place Details na sua lógica JavaScript. Receba uma referência ao elemento Place Details. Se houver, consiga uma referência ao elemento Place Request do Place Details e defina a propriedade do lugar usando um ID de lugar. No exemplo de código HTML acima, o estilo do elemento Place Details está definido como display: none. Isso foi 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);

Implementar o elemento Place Search

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

Implementação atual

Você faz uma Text Search ou Nearby Search usando uma solicitação HTTP ou a classe Place da API JavaScript.
Você especifica parâmetros de consulta, restrições ou vieses de local, tipos e campos solicitados usando FieldMask.
Você analisa a resposta da API, faz uma iteração na matriz de lugares e cria manualmente itens de lista HTML.

Migração para o elemento Place Search

Modificar a estrutura HTML

Identifique o contêiner HTML em que você renderiza a lista de Seus lugares. Substitua seus elementos HTML personalizados (divs, spans para nome, endereço etc.) pelo elemento HTML do Place Search.

Seu HTML atual pode ser parecido com este:

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

<gmp-place-text-search-request> para uma Text Search.
<gmp-place-nearby-search-request> para uma Nearby Search.

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 importantes, como selectable (para permitir cliques em itens de 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 Text Search

<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, use document.querySelector() para receber uma referência ao componente do controlador de pesquisa. Dependendo da 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 obrigatórias dependem do tipo de pesquisa que você está realizando.

Para uma Text Search (<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 Nearby Search (<gmp-place-nearby-search-request>), é preciso definir 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 Text Search, a pesquisa é executada no momento em que você atribui um valor a textQuery.
Para uma Nearby Search, 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 do elemento Place Search, o elemento Basic Place Autocomplete está disponível.

Esse elemento é ideal para criar um campo de entrada de pesquisa e, ao mesmo tempo, manter o controle total sobre como os resultados são exibidos na interface do usuário personalizada. A única responsabilidade do elemento Autocomplete é fornecer previsões de lugares conforme o usuário digita e expor de forma programática um ID de lugar para o local selecionado.

Ele não mostra detalhes nem fornece outras informações acessíveis de forma programática.

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.
Usar 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ê anexou o widget do Autocomplete. É provável que ele use 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 básico do Place Autocomplete na sua página.

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

Adaptar a lógica do JavaScript

Sua lógica de JavaScript provavelmente envolve a criação do widget de preenchimento automático anexado a um elemento HTML input. 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 básico do Place Autocomplete e detectar eventos gmp-select:

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

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

Ao selecionar um lugar no menu suspenso do Autocomplete, o evento gmp-select será acionado. O ID de lugar do lugar selecionado pode ser recuperado do objeto event. O ID de lugar pode ser usado para inicializar uma instância do elemento Place Details e mostrar os detalhes do lugar selecionado.

Personalização do identificador

Personalização do elemento Place Details

Orientação

O elemento Place Details 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 campos para renderizar

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

Adicionar ou remover campos do elemento Place Details não muda o custo de renderização dele na página.

Definir estilos CSS

As 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 lugares 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 campos para renderizar

Use elementos de conteúdo para especificar o conteúdo a ser renderizado no elemento Place Search. O elemento <gmp-place-all-content> pode ser usado para exibir 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> renderizaria apenas 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

As propriedades CSS personalizadas estão disponíveis para personalizar a aparência 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 de 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 Place Search, ele é acionado quando um usuário clica em um lugar na lista de resultados.
- No elemento básico do Place Autocomplete, 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: acionado 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 de forma programática dados específicos dos elementos depois que eles forem carregados ou interagirem com o usuário.

Para o elemento Place Search e o elemento Place Details, é possível recuperar as seguintes informações:
- ID do lugar
- Local (latitude e longitude)
- Janela de visualização
No 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 de forma programática.

Para exemplos mais detalhados, consulte a documentação individual do elemento Place Search, do elemento Place Details e do elemento Basic Place Autocomplete.

Depois de integrar os elementos do Kit de Interface do Places, é fundamental fazer testes para garantir uma transição tranquila e uma experiência positiva para o usuário. Seus testes devem abranger várias áreas importantes, abordando todos os elementos que você implementou: Place Details, Place Search e Basic Place Autocomplete.

Elemento Place Details

Para o elemento Place Details, comece verificando se os detalhes são exibidos corretamente para uma ampla variedade de lugares. Teste transmitindo vários IDs de lugar para a propriedade .place do elemento <gmp-place-details-place-request>. Use IDs que representem diferentes tipos de estabelecimento (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 Place Search

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

Para uma Text Search, 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 vieses de localização.
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 do Place Autocomplete, concentre os testes na interação do usuário e nos dados transmitidos pelo evento de seleção. Confirme se o evento gmp-select é disparado 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 de lugar pode ser usado para preencher outro elemento, como o 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 use 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 corrompida ou confusa.

Adotar o Kit de Interface do Places para usuários da API Places Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Público-alvo deste guia

Pré-requisitos

Atualizar o carregamento da API Maps JavaScript

Implementar o elemento Place Details

Implementação atual

Migração para o elemento Place Details

Modificar a estrutura HTML

Adaptar a lógica do JavaScript

Lógica atual

Nova lógica

Implementar o elemento Place Search

Implementação atual

Migração para o elemento Place Search

Modificar a estrutura HTML

Exemplo de Nearby Search

Exemplo de Text Search

Adaptar a lógica do JavaScript

Implementar o elemento básico do Place Autocomplete

Implementação atual

Migração para o elemento Place Autocomplete

Modificar a estrutura HTML

Adaptar a lógica do JavaScript

Personalização do identificador

Personalização do elemento Place Details

Orientação

Escolher campos para renderizar

Definir estilos CSS

Personalização do elemento Place Search

Orientação

Escolher campos para renderizar

Personalização básica do elemento Place Autocomplete

Definir estilos CSS

Processar eventos e dados

Detectar eventos

Evento de seleção

Eventos comuns

Acessar dados de elementos de maneira programática

Teste e refinamento

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