Elemento di completamento automatico di base

Seleziona la piattaforma: Android iOS JavaScript

The BasicPlaceAutocompleteElement crea un campo di input di testo, fornisce previsioni sui 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 differisce nei seguenti modi:

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

Prerequisiti

Per utilizzare l'elemento Basic Place Autocomplete, devi abilitare Places UI Kit nel tuo progetto Google Cloud. Per maggiori dettagli, consulta la guida introduttiva.

Aggiungere un elemento Basic Place Autocomplete

Questa sezione mostra come aggiungere un elemento Basic Autocomplete a una pagina web o a una mappa.

Aggiungere un elemento Basic Autocomplete a una pagina web

Per aggiungere l'elemento BasicAutocomplete a una pagina web, crea un nuovo google.maps.places.BasicPlaceAutocompleteElement e aggiungilo a la 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);

Aggiungere un elemento Basic Autocomplete a una mappa

Per aggiungere un elemento Basic Autocomplete a una mappa, aggiungi un BasicPlaceAutocompleteElement a un gmp-map elemento 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>

Limitare le previsioni di completamento automatico

Per impostazione predefinita, Basic Place Autocomplete presenta tutti i tipi di luoghi, con una preferenza per le previsioni vicino 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 Basic Autocomplete ignori tutti i risultati al di fuori dell' area di limitazione. Una pratica comune è limitare i risultati ai limiti della mappa. L'influenza dei risultati fa sì che l'elemento BasicAutocomplete mostri i risultati all'interno dell'area specificata, ma alcune corrispondenze potrebbero essere al di fuori di quest'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 influenzerà i risultati in base a questa posizione. Imposta i limiti quando 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 che hai impostato tramite panoramica o zoom sulla mappa, oppure un'area visibile impostata dallo sviluppatore in base alla posizione e al raggio del dispositivo. Quando un raggio non è disponibile, 5 km è considerato un valore predefinito ragionevole per l'elemento Basic Place Autocomplete. Non impostare un'area visibile con raggio zero (un singolo punto), un'area visibile di pochi metri (meno di 100 m) o un'area visibile che si estende su tutto il mondo.

Limitare la ricerca di luoghi per paese

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

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

Limitare la ricerca di luoghi ai limiti della mappa

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

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

Quando limiti i risultati ai limiti della mappa, 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.

Influenzare i risultati di ricerca di luoghi

Influenza i risultati di ricerca di luoghi in base a un'area circolare utilizzando la locationBias proprietà e passando 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.

Limitare i risultati di ricerca di luoghi a determinati tipi

Limita i risultati di ricerca di luoghi a determinati tipi di luoghi utilizzando la includedPrimaryTypes proprietà 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.

Configurare l'elemento Richiesta luogo

Aggiungi un listener per aggiornare l'elemento Richiesta luogo 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 Basic Autocomplete a una mappa di 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>