Elemento di completamento automatico di base

BasicPlaceAutocompleteElement crea un campo di immissione di testo, fornisce previsioni dei luoghi in un elenco di selezione dell'interfaccia utente e restituisce un ID luogo per il luogo selezionato.

L'elemento Basic Place Autocomplete è più semplice da implementare rispetto a PlaceAutocompleteElement e si differenzia per i seguenti aspetti:

  • L'elemento Basic Place Autocomplete restituisce un oggetto Place contenente solo l'ID luogo, anziché un oggetto PlacePrediction. Puoi utilizzare l'ID luogo restituito direttamente con un elemento Places UI Kit Details per ottenere ulteriori dettagli sul luogo, mentre un oggetto PlacePrediction richiederebbe prima la conversione in un ID luogo.
  • L'elemento Place Autocomplete di base non richiede l'attivazione dell'API Places nella console Google Cloud.
  • L'elemento Basic Place Autocomplete cancella il campo di immissione quando un utente seleziona una previsione di luogo.

Prerequisiti

Per utilizzare l'elemento Basic Place Autocomplete, devi attivare Places UI Kit nel tuo progetto Google Cloud. Per maggiori dettagli, consulta Inizia.

Aggiungi un elemento Place Autocomplete di base

Questa sezione mostra come aggiungere un elemento di completamento automatico di base a una pagina web o a una mappa.

Aggiungi un elemento di completamento automatico di base a una pagina web

Per aggiungere l'elemento BasicAutocomplete a una pagina web, crea un nuovo google.maps.places.BasicPlaceAutocompleteElement e aggiungilo alla pagina come mostrato nell'esempio seguente: 

// 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);

Aggiungi un elemento di completamento automatico di base a una mappa

Per aggiungere un elemento di completamento automatico di base a una mappa, aggiungi un BasicPlaceAutocompleteElement a un elemento gmp-map e imposta la sua posizione utilizzando l'attributo slot, come mostrato nell'esempio seguente:

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

Limita le previsioni di completamento automatico

Per impostazione predefinita, Basic Place Autocomplete presenta tutti i tipi di luoghi, con una preferenza per le previsioni vicine alla posizione dell'utente. Imposta BasicPlaceAutocompleteElementOptions per presentare previsioni più pertinenti limitando o influenzando i risultati.

La limitazione dei risultati fa sì che l'elemento di completamento automatico di base ignori i risultati che non rientrano nell'area di limitazione. Una pratica comune è limitare i risultati ai limiti della mappa. La polarizzazione dei risultati fa sì che l'elemento BasicAutocomplete mostri i risultati all'interno dell'area specificata, ma alcune corrispondenze potrebbero trovarsi al di fuori di quell'area.

Se non fornisci limiti o un'area visibile della mappa, l'API tenterà di rilevare la posizione dell'utente dal suo indirizzo IP e darà la priorità ai risultati relativi a quella posizione. Imposta i limiti ogni volta che è possibile. In caso contrario, utenti diversi potrebbero ricevere previsioni diverse. Inoltre, per migliorare in generale le previsioni, è importante fornire un'area visibile ragionevole, ad esempio una impostata tramite la panoramica o lo zoom sulla mappa, oppure un'area visibile impostata dallo sviluppatore in base alla posizione e al raggio del dispositivo. Se non è disponibile un raggio, 5 km è considerato un valore predefinito ragionevole per l'elemento Place Autocomplete di base. Non impostare un'area visibile con raggio pari a zero (un singolo punto), un'area visibile di pochi metri (meno di 100 m) o un'area visibile che si estende su tutto il globo.

Limita la ricerca di luoghi in base al paese

Per limitare la ricerca di luoghi a uno o più paesi specifici, utilizza la proprietà includedRegionCodes per specificare i codici paese, come mostrato nello snippet seguente:

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

Limita la ricerca di luoghi ai limiti della mappa

Per limitare la ricerca di luoghi ai limiti di una mappa, utilizza la proprietà locationRestrictions per aggiungere i limiti, come mostrato nello snippet seguente:

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

Quando limiti la mappa ai limiti, assicurati di aggiungere un listener per aggiornare i limiti quando cambiano:

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

Per rimuovere locationRestriction, impostalo su null.

Risultati di ricerca di luoghi con bias

Per orientare i risultati di ricerca dei luoghi verso un'area circolare, utilizza la proprietà locationBias e passa un raggio, come mostrato di seguito:

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

Per rimuovere locationBias, impostalo su null.

Limita i risultati di ricerca dei luoghi a determinati tipi

Limita i risultati di ricerca dei luoghi a determinati tipi di luoghi utilizzando la proprietà includedPrimaryTypes e specificando uno o più tipi, come mostrato di seguito:

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

Per un elenco completo dei tipi supportati, consulta le tabelle dei tipi di luoghi A e B.

Configura l'elemento Place Request

Aggiungi un listener per aggiornare l'elemento Place Request quando l'utente seleziona una previsione: 

// 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;
});

Questo esempio mostra come aggiungere un elemento di completamento automatico di base a una mappa 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();

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;
}

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>