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.

Elemento básico do Place Autocomplete

Selecionar 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 difere das seguintes maneiras:

O elemento Basic Place Autocomplete retorna um objeto Place que contém apenas o ID do lugar, em vez de um PlacePrediction objeto. Você pode usar o ID de lugar retornado diretamente com um elemento de detalhes do Kit de Interface do Places para receber mais detalhes sobre o lugar. Já um objeto PlacePrediction exige primeiro a conversão em um ID de lugar.
O elemento Basic Place Autocomplete não exige que você ative a API Places no console do Google Cloud.
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 Kit de Interface do Places no projeto na nuvem do Google Cloud. Consulte o artigo Começar para mais detalhes.

Adicionar um elemento Basic Place Autocomplete

Nesta seção, mostramos como adicionar um elemento Basic Autocomplete a uma página da Web ou um mapa.

Adicionar um elemento Basic Autocomplete a uma página da Web

Para adicionar o elemento BasicAutocomplete a uma página da Web, crie um novo google.maps.places.BasicPlaceAutocompleteElement, e anexe-o a 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 Basic Autocomplete a um mapa

Para adicionar um elemento Basic Autocomplete a um mapa, anexe um BasicPlaceAutocompleteElement a um gmp-map elemento e defina a posição dele usando o atributo slot, como 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

Observação:O atributo de ID do mapa permite que as configurações de estilo e configuração do mapa sejam armazenadas no Google Cloud e é obrigatório para este exemplo. O ID DEMO_MAP_ID pode ser usado para testes e não precisa ser ativado no Cloud.

Restringir previsões de preenchimento automático

Por padrão, o Basic Place Autocomplete apresenta todos os tipos de lugares, com prioridade para previsões próximas ao local do usuário. Defina BasicPlaceAutocompleteElementOptions para apresentar previsões mais relevantes restringindo ou polarizando os resultados.

Quando você limita os resultados, o elemento Basic Autocomplete 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 nenhuma janela de visualização de mapa ou limite é fornecido, a API tenta detectar a localização da pessoa pelo endereço IP e prioriza os resultados para lá. Defina limites sempre que possível. Caso contrário, usuários diferentes poderão receber previsões diferentes. 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 includedRegionCodes propriedade 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 as tabelas A e B de tipos de lugares.

Configurar o elemento Place Request

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 Basic Autocomplete 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 init() {
    // Asynchronously load required libraries from the Google Maps JS API.
    const [{ AdvancedMarkerElement }, { InfoWindow, Circle }, { Size }] =
        await Promise.all([
            google.maps.importLibrary('marker'),
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('core'),
            google.maps.importLibrary('places'),
        ]);

    // 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,
        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 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;
        if (!location) {
            advancedMarkerElement.position = null;
            return;
        }

        // 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 Circle({
            center: newCenter,
            radius: 10000, // 10km in meters.
        });
    });
}

void init();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>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </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

Elemento básico do Place Autocomplete Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Pré-requisitos

Adicionar um elemento Basic Place Autocomplete

Adicionar um elemento Basic Autocomplete a uma página da Web

Adicionar um elemento Basic Autocomplete a um mapa

Restringir previsões de preenchimento automático

Restringir a pesquisa de lugares por país

Restringir a pesquisa de lugares aos limites do mapa

Polarizar os resultados da pesquisa de lugares

Restringir os resultados da pesquisa de lugares a determinados tipos

Configurar o elemento Place Request

JavaScript

CSS

HTML

Elemento básico do Place Autocomplete