Il widget di completamento automatico dei luoghi crea un campo di immissione di testo, fornisce le previsioni dei luoghi in un elenco di scelta dell'interfaccia utente e restituisce i dettagli del luogo in risposta alla selezione dell'utente. Utilizza il widget di completamento automatico dei luoghi per incorporare nella tua pagina web un'interfaccia utente di completamento automatico completa e autosufficiente.
Prerequisiti
Per utilizzare la funzionalità di completamento automatico dei luoghi (anteprima), devi attivare l'API "Places" nel tuo progetto Google Cloud e specificare il canale beta (v: "beta") nel caricatore di bootstrap. Per maggiori dettagli, consulta la guida introduttiva.
Novità
La funzionalità di compilazione automatica dei luoghi (anteprima) è stata migliorata nei seguenti modi:
- L'interfaccia utente del widget di completamento automatico supporta la localizzazione regionale (incluse le lingue RTL), per il visualizzatore di testo inserito, il logo dell'elenco delle previsioni e le previsioni dei luoghi.
- Accessibilità migliorata, incluso il supporto di screen reader e interazione con la tastiera.
- Il widget di completamento automatico restituisce la nuova classe Place per semplificare la gestione dell'oggetto restituito.
- Supporto migliore per dispositivi mobili e schermi di piccole dimensioni.
- Migliore rendimento e aspetto grafico migliorato.
Aggiungere un widget di completamento automatico
Puoi aggiungere un widget di completamento automatico a una pagina web o a una mappa di Google. Il widget di completamento automatico crea un campo di immissione di testo, fornisce le previsioni dei luoghi in un elenco di scelta dell'interfaccia utente e restituisce i dettagli del luogo in risposta a un clic dell'utente tramite l'ascoltatore gmp-placeselect. Questa sezione mostra come aggiungere un widget di completamento automatico a una pagina web o a una mappa di Google.
Aggiungere un widget di completamento automatico a una pagina web
Per aggiungere il widget di completamento automatico a una pagina web, crea un nuovo google.maps.places.PlaceAutocompleteElement e aggiungilo alla pagina come mostrato nell'esempio seguente:
TypeScript
// Request needed libraries.
//@ts-ignore
await google.maps.importLibrary("places") as google.maps.PlacesLibrary;
// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
document.body.appendChild(placeAutocomplete);
JavaScript
// Request needed libraries.
//@ts-ignore
await google.maps.importLibrary("places");
// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
document.body.appendChild(placeAutocomplete);
Guarda l'esempio di codice completo
Aggiungere un widget di completamento automatico a una mappa
Per aggiungere un widget di completamento automatico a una mappa, crea una nuova istanza google.maps.places.PlaceAutocompleteElement, accoda PlaceAutocompleteElement a div e inseriscilo nella mappa come controllo personalizzato, come mostrato nell'esempio seguente:
TypeScript
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
placeAutocomplete.id = 'place-autocomplete-input';
const card = document.getElementById('place-autocomplete-card') as HTMLElement;
//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
JavaScript
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
placeAutocomplete.id = "place-autocomplete-input";
const card = document.getElementById("place-autocomplete-card");
//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
Guarda l'esempio di codice completo
Limitare le previsioni di completamento automatico
Per impostazione predefinita, la funzionalità di completamento automatico dei luoghi presenta tutti i tipi di luoghi, con una preferenza per le previsioni nelle vicinanze della posizione dell'utente, e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta PlaceAutocompleteElementOptions per presentare previsioni più pertinenti, limitando o influenzando i risultati.
Se limiti i risultati, il widget di completamento automatico ignora i risultati al di fuori dell'area di limitazione. Una pratica comune è limitare i risultati ai confini della mappa. La distorsione dei risultati consente al widget di completamento automatico di mostrare i risultati all'interno dell'area specificata, ma alcune corrispondenze potrebbero essere al di fuori di quell'area.
Se non fornisci limiti o un viewport della mappa, l'API tenterà di rilevare la posizione dell'utente dal suo indirizzo IP e inclinerà i risultati in base a questa posizione. Imposta un limite 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 quella 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. Quando non è disponibile un raggio, 5 km è considerato un valore predefinito ragionevole per la funzionalità di completamento automatico dei luoghi. 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 copre il globo.
Limitare la ricerca dei luoghi per paese
Per limitare la ricerca dei luoghi a uno o più paesi specifici, utilizza la proprietà componentRestrictions
per specificare i codici paese, come mostrato nello snippet seguente:
const pac = new google.maps.places.PlaceAutocompleteElement({
componentRestrictions: {country: ['us', 'au']},
});
Limitare la ricerca dei luoghi ai confini della mappa
Per limitare la ricerca dei luoghi ai confini di una mappa, utilizza la proprietà locationRestrictions
per aggiungere i confini, come mostrato nel seguente snippet:
const pac = new google.maps.places.PlaceAutocompleteElement({
locationRestriction: map.getBounds(),
});
Quando limiti la ricerca ai confini della mappa, assicurati di aggiungere un ascoltatore per aggiornare i confini quando cambiano:
map.addListener('bounds_changed', () => {
autocomplete.locationRestriction = map.getBounds();
});
Per rimuovere locationRestriction, impostalo su null.
Spostare i risultati di ricerca dei luoghi
Inclina i risultati di ricerca dei luoghi verso un'area circolare utilizzando la proprietà locationBias e passando un raggio, come mostrato di seguito:
const autocomplete = new google.maps.places.PlaceAutocompleteElement({
locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});
Per rimuovere locationBias, impostalo su null.
Limitare i risultati di ricerca dei luoghi a determinati tipi
Limita i risultati di ricerca dei luoghi a determinati tipi di luoghi utilizzando la proprietà types
e specificando uno o più tipi, come mostrato di seguito:
const autocomplete = new google.maps.places.PlaceAutocompleteElement({
types: ['establishment'],
});
Per un elenco completo dei tipi supportati, consulta la Tabella 3: tipi supportati nelle richieste di completamento automatico in situ.
Ottenere i dettagli del luogo
Per ottenere i dettagli del luogo selezionato, aggiungi un ascoltatore gmp-placeselect al PlaceAutocompleteElement, come mostrato nell'esempio seguente:
TypeScript
// Add the gmp-placeselect listener, and display the results.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
selectedPlaceTitle.textContent = 'Selected Place:';
selectedPlaceInfo.textContent = JSON.stringify(
place.toJSON(), /* replacer */ null, /* space */ 2);
});
JavaScript
// Add the gmp-placeselect listener, and display the results.
//@ts-ignore
placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
await place.fetchFields({
fields: ["displayName", "formattedAddress", "location"],
});
selectedPlaceTitle.textContent = "Selected Place:";
selectedPlaceInfo.textContent = JSON.stringify(
place.toJSON(),
/* replacer */ null,
/* space */ 2,
);
});
Guarda l'esempio di codice completo
Nell'esempio precedente, l'ascoltatore di eventi restituisce un oggetto della classe Place.
Chiama place.fetchFields() per ottenere i campi di dati di Places Details necessari per la tua applicazione.
L'ascoltatore nell'esempio seguente richiede informazioni sui luoghi e le mostra su una mappa.
TypeScript
// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
// If the place has a geometry, then present it on a map.
if (place.viewport) {
map.fitBounds(place.viewport);
} else {
map.setCenter(place.location);
map.setZoom(17);
}
let content = '<div id="infowindow-content">' +
'<span id="place-displayname" class="title">' + place.displayName + '</span><br />' +
'<span id="place-address">' + place.formattedAddress + '</span>' +
'</div>';
updateInfoWindow(content, place.location);
marker.position = place.location;
});
JavaScript
// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
await place.fetchFields({
fields: ["displayName", "formattedAddress", "location"],
});
// If the place has a geometry, then present it on a map.
if (place.viewport) {
map.fitBounds(place.viewport);
} else {
map.setCenter(place.location);
map.setZoom(17);
}
let content =
'<div id="infowindow-content">' +
'<span id="place-displayname" class="title">' +
place.displayName +
"</span><br />" +
'<span id="place-address">' +
place.formattedAddress +
"</span>" +
"</div>";
updateInfoWindow(content, place.location);
marker.position = place.location;
});
Guarda l'esempio di codice completo
Mappe di esempio
Questa sezione contiene il codice completo delle mappe di esempio mostrate in questa pagina.
Elemento di completamento automatico
Questo esempio aggiunge un widget di completamento automatico a una pagina web e mostra i risultati per ogni località selezionata.
TypeScript
async function initMap(): Promise<void> {
// Request needed libraries.
//@ts-ignore
await google.maps.importLibrary("places") as google.maps.PlacesLibrary;
// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
document.body.appendChild(placeAutocomplete);
// Inject HTML UI.
const selectedPlaceTitle = document.createElement('p');
selectedPlaceTitle.textContent = '';
document.body.appendChild(selectedPlaceTitle);
const selectedPlaceInfo = document.createElement('pre');
selectedPlaceInfo.textContent = '';
document.body.appendChild(selectedPlaceInfo);
// Add the gmp-placeselect listener, and display the results.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
selectedPlaceTitle.textContent = 'Selected Place:';
selectedPlaceInfo.textContent = JSON.stringify(
place.toJSON(), /* replacer */ null, /* space */ 2);
});
}
initMap();
JavaScript
async function initMap() {
// Request needed libraries.
//@ts-ignore
await google.maps.importLibrary("places");
// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
document.body.appendChild(placeAutocomplete);
// Inject HTML UI.
const selectedPlaceTitle = document.createElement("p");
selectedPlaceTitle.textContent = "";
document.body.appendChild(selectedPlaceTitle);
const selectedPlaceInfo = document.createElement("pre");
selectedPlaceInfo.textContent = "";
document.body.appendChild(selectedPlaceInfo);
// Add the gmp-placeselect listener, and display the results.
//@ts-ignore
placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
await place.fetchFields({
fields: ["displayName", "formattedAddress", "location"],
});
selectedPlaceTitle.textContent = "Selected Place:";
selectedPlaceInfo.textContent = JSON.stringify(
place.toJSON(),
/* replacer */ null,
/* space */ 2,
);
});
}
initMap();
CSS
/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
#map {
height: 100%;
}
/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
p {
font-family: Roboto, sans-serif;
font-weight: bold;
}
HTML
<html>
<head>
<title>Place Autocomplete element</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<p style="font-family: roboto, sans-serif">Search for a place here:</p>
<!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "beta"});</script>
</body>
</html>
Prova Sample
Mappa di completamento automatico
Questo esempio mostra come aggiungere un widget di completamento automatico a una mappa di Google.
TypeScript
let map: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function initMap(): Promise<void> {
// Request needed libraries.
//@ts-ignore
const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
google.maps.importLibrary("marker"),
google.maps.importLibrary("places")
]);
// Initialize the map.
map = new google.maps.Map(document.getElementById('map') as HTMLElement, {
center: { lat: 40.749933, lng: -73.98633 },
zoom: 13,
mapId: '4504f8b37365c3d0',
mapTypeControl: false,
});
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
placeAutocomplete.id = 'place-autocomplete-input';
const card = document.getElementById('place-autocomplete-card') as HTMLElement;
//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
// Create the marker and infowindow
marker = new google.maps.marker.AdvancedMarkerElement({
map,
});
infoWindow = new google.maps.InfoWindow({});
// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
// If the place has a geometry, then present it on a map.
if (place.viewport) {
map.fitBounds(place.viewport);
} else {
map.setCenter(place.location);
map.setZoom(17);
}
let content = '<div id="infowindow-content">' +
'<span id="place-displayname" class="title">' + place.displayName + '</span><br />' +
'<span id="place-address">' + place.formattedAddress + '</span>' +
'</div>';
updateInfoWindow(content, place.location);
marker.position = place.location;
});
}
// Helper function to create an info window.
function updateInfoWindow(content, center) {
infoWindow.setContent(content);
infoWindow.setPosition(center);
infoWindow.open({
map,
anchor: marker,
shouldFocus: false,
});
}
initMap();
JavaScript
let map;
let marker;
let infoWindow;
async function initMap() {
// Request needed libraries.
//@ts-ignore
const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
google.maps.importLibrary("marker"),
google.maps.importLibrary("places"),
]);
// Initialize the map.
map = new google.maps.Map(document.getElementById("map"), {
center: { lat: 40.749933, lng: -73.98633 },
zoom: 13,
mapId: "4504f8b37365c3d0",
mapTypeControl: false,
});
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
placeAutocomplete.id = "place-autocomplete-input";
const card = document.getElementById("place-autocomplete-card");
//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
// Create the marker and infowindow
marker = new google.maps.marker.AdvancedMarkerElement({
map,
});
infoWindow = new google.maps.InfoWindow({});
// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
await place.fetchFields({
fields: ["displayName", "formattedAddress", "location"],
});
// If the place has a geometry, then present it on a map.
if (place.viewport) {
map.fitBounds(place.viewport);
} else {
map.setCenter(place.location);
map.setZoom(17);
}
let content =
'<div id="infowindow-content">' +
'<span id="place-displayname" class="title">' +
place.displayName +
"</span><br />" +
'<span id="place-address">' +
place.formattedAddress +
"</span>" +
"</div>";
updateInfoWindow(content, place.location);
marker.position = place.location;
});
}
// Helper function to create an info window.
function updateInfoWindow(content, center) {
infoWindow.setContent(content);
infoWindow.setPosition(center);
infoWindow.open({
map,
anchor: marker,
shouldFocus: false,
});
}
initMap();
CSS
/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
#map {
height: 100%;
}
/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
#place-autocomplete-card {
background-color: #fff;
border-radius: 5px;
box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
margin: 10px;
padding: 5px;
font-family: Roboto, sans-serif;
font-size: large;
font-weight: bold;
}
gmp-place-autocomplete {
width: 300px;
}
#infowindow-content .title {
font-weight: bold;
}
#map #infowindow-content {
display: inline;
}
HTML
<html>
<head>
<title>Place Autocomplete map</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<div class="place-autocomplete-card" id="place-autocomplete-card">
<p>Search for a place here:</p>
</div>
<div id="map"></div>
<!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "beta"});</script>
</body>
</html>
Prova Sample
Utilizzare il componente Selettore di luoghi
Il componente di selezione dei luoghi è un input di testo che consente agli utenti finali di cercare un indirizzo o un luogo specifico utilizzando il completamento automatico. Fa parte della Extended Component Library, un insieme di componenti web che aiutano gli sviluppatori a creare più velocemente mappe e funzionalità di geolocalizzazione migliori.
Utilizza il configuratore di Seleziona luogo per creare codice embeddable per un componente Seleziona luogo personalizzato, quindi esportalo per utilizzarlo con framework comuni come React e Angular o senza alcun framework.