Elemento básico do Place Autocomplete

Selecione a plataforma: Android iOS JavaScript

O BasicPlaceAutocompleteElement cria um campo de entrada de texto, oferece previsões de lugares em uma lista de seleção na interface e retorna um ID do lugar selecionado.

O elemento Basic Place Autocomplete é mais simples de implementar do que o PlaceAutocompleteElement, e eles diferem das seguintes maneiras:

  • O elemento Basic Place Autocomplete retorna um objeto Place que contém apenas o ID do lugar, em vez de um objeto PlacePrediction. Você pode usar o ID de lugar retornado diretamente com um elemento Detalhes do kit de interface do Places para receber mais detalhes do lugar. Já um objeto PlacePrediction precisa ser convertido em um ID de lugar.
  • O elemento Basic Place Autocomplete não exige que você carregue a API Places.
  • O elemento Basic Place Autocomplete limpa o campo de entrada quando um usuário seleciona uma previsão de lugar.

Pré-requisitos

Para usar o elemento Basic Place Autocomplete, ative o Places UI Kit no projeto do Google Cloud. Consulte Começar para mais detalhes.

Adicionar um elemento básico do Place Autocomplete

Nesta seção, mostramos como adicionar um elemento de preenchimento automático básico a uma página da Web ou um mapa.

Adicionar um elemento de preenchimento automático básico a uma página da Web

Para adicionar o elemento BasicAutocomplete a uma página da Web, crie um google.maps.places.BasicPlaceAutocompleteElement e anexe-o à página, como mostrado no exemplo a seguir: 

// Request needed libraries.
const {BasicPlaceAutocompleteElement} = await google.maps.importLibrary('places');
// Create the input HTML element and append it.
const placeAutocomplete = new BasicPlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);

Adicionar um elemento de preenchimento automático básico a um mapa

Para adicionar um elemento de preenchimento automático básico a um mapa, anexe um BasicPlaceAutocompleteElement a um elemento gmp-map e defina a posição dele usando o atributo slot, conforme mostrado no exemplo a seguir:

<gmp-map zoom="12" center="37.4220656,-122.0840897" map-id="DEMO_MAP_ID">
  <gmp-basic-place-autocomplete
    slot="control-inline-start-block-start"></gmp-basic-place-autocomplete>
</gmp-map>
index.html

Restringir previsões de preenchimento automático

Por padrão, o Place Autocomplete básico apresenta todos os tipos de lugares, favorecendo previsões perto da localização do usuário. Defina BasicPlaceAutocompleteElementOptions para apresentar previsões mais relevantes restringindo ou polarizando os resultados.

Quando você limita os resultados, o elemento de preenchimento automático básico ignora todos os resultados que estão fora da área de restrição. Uma prática comum é restringir os resultados aos limites do mapa. A polarização de resultados faz com que o elemento BasicAutocomplete mostre resultados dentro da área especificada, mas algumas correspondências podem estar fora dessa região.

Se você não fornecer limites ou uma janela de visualização de mapa, a API tentará detectar a localização do usuário pelo endereço IP e priorizará os resultados para esse local. Defina limites sempre que possível. Caso contrário, cada usuário pode receber uma previsão diferente. Além disso, para melhorar as previsões, é importante oferecer uma janela de visualização adequada (como aquelas que você define movimentando ou aumentando o zoom do mapa) ou definida pelo desenvolvedor com base no raio e no local do dispositivo. Quando um raio não está disponível, 5 km é considerado um padrão adequado para o elemento Basic Place Autocomplete. Não defina uma janela de visualização com raio zero (um único ponto), que tenha apenas alguns metros de extensão (menos de 100 m) ou que abranja todo o globo.

Restringir a pesquisa de lugares por país

Se quiser restringir a pesquisa de lugares a um ou mais países específicos, use a propriedade includedRegionCodes para definir os códigos dos países, como mostrado no snippet abaixo:

const pac = new google.maps.places.BasicPlaceAutocompleteElement({
  includedRegionCodes: ['us', 'au'],
});

Restringir a pesquisa de lugares aos limites do mapa

Se quiser fazer isso, use a propriedade locationRestrictions para adicionar os limites, como mostrado no snippet abaixo:

const pac = new google.maps.places.BasicPlaceAutocompleteElement({
  locationRestriction: map.getBounds(),
});

Ao fazer a restrição, inclua um listener para atualizar os limites quando eles mudarem:

map.addListener('bounds_changed', () => {
  autocomplete.locationRestriction = map.getBounds();
});

Para remover locationRestriction, defina-o como null.

Polarizar os resultados da pesquisa de lugares

Polarize os resultados a uma área circular usando a propriedade locationBias e transmitindo um raio, como mostrado aqui:

const autocomplete = new google.maps.places.BasicPlaceAutocompleteElement({
  locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});

Para remover locationBias, defina-o como null.

Restringir os resultados da pesquisa de lugares a determinados tipos

Para fazer isso, use a propriedade includedPrimaryTypes e especifique um ou mais tipos, como mostrado aqui:

const autocomplete = new google.maps.places.BasicPlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

Para conferir uma lista completa dos tipos aceitos, consulte Tabelas A e B de tipos de lugar.

Configurar o elemento "Solicitação de lugar"

Adicione um listener para atualizar o elemento "Place Request" quando o usuário selecionar uma previsão: 

// Event listener for when a place is selected from the autocomplete list.
placeAutocompleteElement.addEventListener('gmp-select', (event) => {
    // Reset marker and InfoWindow, and prepare the details element.
    placeDetailsParent.appendChild(placeDetailsElement);
    placeDetailsElement.style.display = 'block';
    advancedMarkerElement.position = null;
    infoWindow.close();
    // Request details for the selected place.
    const placeDetailsRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
    placeDetailsRequest.place = event.place.id;
});
index.js

Neste exemplo, mostramos como adicionar um elemento de preenchimento automático básico a um mapa do Google.

JavaScript

const placeAutocompleteElement = document.querySelector('gmp-basic-place-autocomplete');
const placeDetailsElement = document.querySelector('gmp-place-details-compact');
const placeDetailsParent = placeDetailsElement.parentElement;
const gmpMapElement = document.querySelector('gmp-map');
async function initMap() {
    // Asynchronously load required libraries from the Google Maps JS API.
    await google.maps.importLibrary('places');
    const { AdvancedMarkerElement } = (await google.maps.importLibrary('marker'));
    const { InfoWindow } = (await google.maps.importLibrary('maps'));
    // Get the initial center directly from the gmp-map element's property.
    const center = gmpMapElement.center;
    // Set the initial location bias for the autocomplete element.
    placeAutocompleteElement.locationBias = center;
    // Update the map object with specified options.
    const map = gmpMapElement.innerMap;
    map.setOptions({
        clickableIcons: false,
        mapTypeControl: false,
        streetViewControl: false,
    });
    // Create an advanced marker to show the location of a selected place.
    const advancedMarkerElement = new AdvancedMarkerElement({
        map: map,
        collisionBehavior: google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL,
    });
    // Create an InfoWindow to hold the place details component.
    const infoWindow = new InfoWindow({
        minWidth: 360,
        disableAutoPan: true,
        headerDisabled: true,
        pixelOffset: new google.maps.Size(0, -10),
    });
    // Event listener for when a place is selected from the autocomplete list.
    placeAutocompleteElement.addEventListener('gmp-select', (event) => {
        // Reset marker and InfoWindow, and prepare the details element.
        placeDetailsParent.appendChild(placeDetailsElement);
        placeDetailsElement.style.display = 'block';
        advancedMarkerElement.position = null;
        infoWindow.close();
        // Request details for the selected place.
        const placeDetailsRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
        placeDetailsRequest.place = event.place.id;
    });
    // Event listener for when the place details have finished loading.
    placeDetailsElement.addEventListener('gmp-load', () => {
        const location = placeDetailsElement.place.location;
        // Position the marker and open the InfoWindow at the place's location.
        advancedMarkerElement.position = location;
        infoWindow.setContent(placeDetailsElement);
        infoWindow.open({
            map,
            anchor: advancedMarkerElement,
        });
        map.setCenter(location);
    });
    // Event listener to close the InfoWindow when the map is clicked.
    map.addListener('click', () => {
        infoWindow.close();
        advancedMarkerElement.position = null;
    });
    // Event listener for when the map finishes moving (panning or zooming).
    map.addListener('idle', () => {
        const newCenter = map.getCenter();
        // Update the autocomplete's location bias to a 10km radius around the new map center.
        placeAutocompleteElement.locationBias = new google.maps.Circle({
            center: {
                lat: newCenter.lat(),
                lng: newCenter.lng(),
            },
            radius: 10000, // 10km in meters.
        });
    });
}
initMap();
index.js

CSS

html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

gmp-map {
  height: 100%;
}

gmp-basic-place-autocomplete {
  position: absolute;
  height: 30px;
  width: 500px;
  top: 10px;
  left: 10px;
  box-shadow: 4px 4px 5px 0px rgba(0, 0, 0, 0.2);
  color-scheme: light;
  border-radius: 10px;
}
style.css

HTML

<html>
  <head>
    <title>Basic Place Autocomplete map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- prettier-ignore -->
    <script>
        (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});
    </script>
  </head>
  <body>
    <gmp-map zoom="12" center="37.4220656,-122.0840897" map-id="DEMO_MAP_ID">
      <gmp-basic-place-autocomplete
        slot="control-inline-start-block-start"></gmp-basic-place-autocomplete>
    </gmp-map>
    <!-- Use inline styles to configure the Place Details Compact element because
     it will be placed within the info window, and info window content is inside 
     the shadow DOM when using <gmp-map> -->
    <gmp-place-details-compact
      orientation="horizontal"
      style="width: 400px;
      display: none;
      border: none;
      padding: 0;
      margin: 0;
      background-color: transparent;
      color-scheme: light;">
      <gmp-place-details-place-request></gmp-place-details-place-request>
      <gmp-place-standard-content></gmp-place-standard-content>
    </gmp-place-details-compact>
  </body>
</html>
index.html

Testar amostra