Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 é para desenvolvedores que têm uma implementação atual usando a API Places e querem atualizar o código para usar o Kit de Interface do Places. Ele será mais útil se você já estiver:

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

Pré-requisitos

Ative o Kit de Interface 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 de importação de biblioteca dinâmica 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 e o elemento 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 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 Place Details

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 Place Details.

Há dois elementos para escolher:

Elemento Place Details Compact
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, declarando 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 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 da Web) para solicitar dados específicos.
Na resolução de callback, selecionar manualmente os elementos HTML e preenchê-los com os dados recebidos.

Confira a seguir um exemplo de como você pode ter o Place Details implementado:

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:

Recuperar o ID de lugar ou o objeto de lugar.
Receber uma referência ao <gmp-place-details-place-request> elemento.
Transmitir o ID de lugar ou o objeto do lugar para a propriedade do lugar no <gmp-place-details-place-request> elemento.

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 ele existir, receba uma referência ao elemento Place Details Place Request 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. Ele é 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ê executa um Text Search ou Nearby Search usando uma solicitação HTTP ou usa a classe Place da API JavaScript.
Você especifica parâmetros de consulta, restrições ou preferê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.

Migração para o elemento Place Search

Modificar a estrutura HTML

Identifique o contêiner HTML em que você renderiza a lista de lugares. Substitua seus elementos HTML personalizados (divs, spans para nome, endereço etc.) pelo elemento HTML 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 <gmp-place-search> componente. Para configurar o tipo de pesquisa, inclua um dos seguintes componentes de configuração com slot dentro de:

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

Para definir como os resultados são mostrados, você pode usar o <gmp-place-all-content> atalho ou fornecer seu próprio conjunto de componentes de apresentação individuais. Atributos importantes, 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 pesquisa nas proximidades

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

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

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

Para um 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>), é necessário definir a área de pesquisa usando uma locationRestriction. Em seguida, você pode usar 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 necessárias do controlador são definidas.

Para um Text Search, a pesquisa é executada no momento em que você atribui um valor a textQuery.
Para um Nearby Search, a pesquisa é executada depois que uma locationRestriction válida é fornecida.

Implementar o elemento Basic Place Autocomplete

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

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

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

Implementação atual

Sua lógica atual provavelmente envolve:

Renderizar um campo de entrada de texto na página que chama o Place Autocomplete à medida que 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.
Mostrar 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 Autocomplete. É provável que ele esteja 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 Basic Place Autocomplete na página.

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

Adaptar a lógica JavaScript

Sua lógica JavaScript provavelmente envolve a criação do widget Autocomplete 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 Basic 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 Autocomplete, o evento gmp-select será acionado. O ID de lugar do local selecionado pode ser recuperado do objeto event. O ID de lugar pode ser usado para inicializar uma instância do Place Details Element, para mostrar os detalhes do lugar selecionado.

Tratar a personalização

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. Por exemplo:

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

Escolher os campos a serem renderizados

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 de lugar do local selecionado Para uma lista completa de elementos de conteúdo, consulte a PlaceContentConfigElement documentação de referência.

Adicionar ou remover campos do elemento Place Details 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 para PlaceDetailsCompactElement para mais detalhes.

Personalização do elemento Place Search

Orientação

O elemento Place Search pode ser renderizado na orientação horizontal e vertical. Use o atributo orientation em <gmp-place-search> para escolher entre vertical e horizontal. Por exemplo:

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

Escolher os campos a serem renderizados

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 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> 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 do elemento Basic Place Autocomplete

Definir estilos CSS

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

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

Consulte a BasicPlaceAutocompleteElement para mais detalhes.

Tratar eventos e dados

Os elementos do Kit de Interface do Places são componentes interativos que permitem detectar eventos e recuperar dados programaticamente.

Detectar eventos

Você pode 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 Basic 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 oferecem suporte aos seguintes eventos:

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

Acessar dados de elementos programaticamente

É possível recuperar dados específicos dos elementos programaticamente depois que eles forem interagidos ou carregados.

Para o elemento Place Search e o elemento Place Details, você pode recuperar as seguintes informações:
- ID de lugar
- Local (latitude e longitude)
- Janela de visualização
Para o elemento Basic Place Autocomplete, você pode recuperar as seguintes informações:
- ID de lugar

Todos os outros dados contidos nos elementos não são acessíveis programaticamente.

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, o teste é fundamental para uma transição tranquila e uma experiência positiva do usuário. O teste precisa abranger várias áreas importantes, abordando todos os elementos implementados: Place Details, Place Search e Basic Place Autocomplete.

Elemento Place Details

Para o elemento Place Details, comece verificando se os detalhes são mostrados corretamente para uma variedade de lugares. Teste transmitindo vários IDs de lugar para a .place propriedade do <gmp-place-details-place-request> elemento. 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 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 um 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 preferências de local.
Para uma Nearby Search, teste definindo as propriedades locationRestriction e includedTypes no <gmp-place-nearby-search-request> elemento. Use tamanhos de local e filtros de tipo diferentes.

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

Elemento Basic Place Autocomplete

Para o elemento Basic Place Autocomplete, concentre o teste 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.

Mais importante ainda, teste o fluxo completo: selecione um lugar no menu suspenso Autocomplete e verifique se o ID de lugar pode ser usado para preencher outro elemento, como o elemento Place Details.

Tratamento de erros

O teste rigoroso do tratamento de erros é essencial 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 o trate corretamente. Implemente mensagens de erro e registros fáceis de usar para evitar uma interface quebrada 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 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 pesquisa nas proximidades

Exemplo de Text Search

Adaptar a lógica JavaScript

Implementar o elemento Basic Place Autocomplete

Implementação atual

Migração para o elemento Place Autocomplete

Modificar a estrutura HTML

Adaptar a lógica JavaScript

Tratar a personalização

Personalização do elemento Place Details

Orientação

Escolher os campos a serem renderizados

Definir estilos CSS

Personalização do elemento Place Search

Orientação

Escolher os campos a serem renderizados

Personalização do elemento Basic Place Autocomplete

Definir estilos CSS

Tratar eventos e dados

Detectar eventos

Evento de seleção

Eventos comuns

Acessar dados de elementos programaticamente

Teste e refinamento

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