Eseguire la migrazione al nuovo completamento automatico dei luoghi

Place Autocomplete è una funzionalità della libreria Places nell'API Maps JavaScript. Puoi utilizzare il completamento automatico per assegnare alle tue applicazioni il comportamento di ricerca di tipo avanzato del campo di ricerca di Google Maps.

Questa pagina spiega le differenze tra le funzionalità del Completamento automatico dei luoghi precedenti e quelle nuove. In entrambe le versioni esistono due modi generali per integrare la funzionalità di completamento automatico:

• Interfaccia programmatica: per gli sviluppatori che cercano una maggiore personalizzazione e un maggiore controllo sull'esperienza di completamento automatico.
• Widget Place Autocomplete: una barra di ricerca che può essere incorporata in una mappa o in una pagina web.

Interfaccia programmatica del completamento automatico

La tabella seguente elenca alcune delle principali differenze nell'utilizzo del completamento automatico dei luoghi programmatico tra il servizio Place Autocomplete (legacy) e l'API Autocomplete Data (nuova):

PlacesService (legacy)	Place (novità)
Riferimento al servizio Autocompletamento di Places	Riferimento ai dati di completamento automatico (novità)
AutocompletionRequest	AutocompleteRequest
AutocompleteService.getPlacePredictions	AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction	PlacePrediction
I metodi richiedono l'utilizzo di un callback per gestire l'oggetto risultati e la risposta PlacesServiceStatus.	Utilizza le promesse e funziona in modo asincrono.
I metodi richiedono un controllo PlacesServiceStatus.	Nessun controllo dello stato richiesto, è possibile utilizzare la gestione degli errori standard.
I campi dei dati dei luoghi vengono impostati come opzioni quando viene creata l'istanza Autocomplete.	I campi di dati dei luoghi vengono impostati in un secondo momento quando viene chiamato fetchFields().
Le previsioni delle query sono supportate (solo SearchBox).	Le previsioni delle query non sono disponibili nel corso Autocomplete.
Limitato a un insieme fisso di tipi di luoghi e campi di dati sui luoghi.	Accesso a una selezione ampliata di tipi di luoghi e campi di dati dei luoghi.

I seguenti elementi vengono utilizzati sia dalle API Autocomplete precedenti che da quelle nuove:

• locationBias
• locationRestriction
• AutocompleteSessionToken
• ComponentRestrictions

Confronto del codice (programmatico)

Questa sezione confronta il codice per il completamento automatico per illustrare le differenze tra il servizio Places e la classe Place per le interfacce programmatiche.

Recuperare le previsioni di completamento automatico (legacy)

Il servizio Places precedente ti consente di recuperare le previsioni di completamento automatico in modo programmatico, per un maggiore controllo sull'interfaccia dell'utente rispetto a quello offerto dalla classe Autocomplete. Nell'esempio seguente viene effettuata una singola richiesta per "par", con un AutocompletionRequest costituito dal valore di input e da un insieme di limiti per influenzare la previsione. L'esempio restituisce un elenco di AutocompletePrediction istanze e mostra la descrizione di ciascuna. La funzione di esempio crea anche un token di sessione e lo applica alla richiesta.

function init() {
  const placeInfo = document.getElementById("prediction");
  const service = new google.maps.places.AutocompleteService();
  const placesService = new google.maps.places.PlacesService(placeInfo);
  var sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    bounds: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  }

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const displaySuggestions = function (predictions, status) {
    // Check the status of the Places Service.
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");
      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });

    const placeRequest = {
      placeId: predictions[0].place_id,
      fields: ["name", "formatted_address"],
    };

    placesService.getDetails(placeRequest, (place, status) => {
      if (status == google.maps.places.PlacesServiceStatus.OK && place) {
        placeInfo.textContent = `
          First predicted place: ${place.name} at ${place.formatted_address}`
      }
    });

  };

  // Show the results of the query.
  service.getPlacePredictions(request, displaySuggestions);
}

• Recupero tramite programmazione delle previsioni del servizio Place Autocomplete
• Esempio di completamento automatico dei luoghi
• Token sessione
• AutocompletionRequest riferimento
• AutocompletePrediction riferimento

Recuperare le previsioni di completamento automatico (novità)

La nuova classe Place ti consente inoltre di recuperare predizioni di completamento automatico in modo programmatico per un maggiore controllo sull'interfaccia dell'utente rispetto a quanto offerto dalla classe PlaceAutocompleteElement. Nell'esempio seguente viene effettuata una singola richiesta per "par", con un AutocompleteRequest costituito dal valore di input e da un insieme di limiti per influenzare la previsione. L'esempio restituisce un elenco di placePrediction istanze e mostra la descrizione di ciascuna. La funzione di esempio crea anche un token di sessione e lo applica alla richiesta.

async function init() {
  let sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    locationBias: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  };

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

  const resultsElement = document.getElementById("results");

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    const listItem = document.createElement("li");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.text),
    );

    resultsElement.appendChild(listItem);
  }

  // Show the first predicted place.
  let place = suggestions[0].placePrediction.toPlace();

  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  const placeInfo = document.getElementById("prediction");

  placeInfo.textContent = `
    First predicted place: ${place.displayName} at ${place.formattedAddress}`
}

• API Place Autocomplete Data
• Esempio di previsioni dei dati di completamento automatico dei luoghi
• Esempio di sessioni di dati di completamento automatico dei luoghi
• Token sessione
• Riferimento all'interfaccia AutocompleteRequest
• Riferimento alla classe AutocompleteSuggestion
• Riferimento alla classe PlacePrediction

Widget di completamento automatico dei luoghi

La seguente tabella elenca alcune delle principali differenze nell'utilizzo dei widget di completamento automatico tra il servizio Luoghi (legacy) e la classe Luogo (nuova):

Servizio Luoghi (legacy)	Luogo (novità)
Classe Autocomplete per le previsioni dei luoghi.	Classe PlaceAutocompleteElement per le previsioni dei luoghi.
SearchBox per le previsioni delle query.	Le previsioni delle query non sono disponibili nel corso Autocomplete.
Solo il testo segnaposto predefinito per l'input è localizzato.	Il segnaposto per l'input di testo, il logo dell'elenco delle previsioni e le previsioni dei luoghi supportano tutti la localizzazione regionale.
Il widget utilizza setBounds() o autocomplete.bindTo() per limitare (polarizzare) la ricerca ai limiti specificati e strictBounds per limitare i risultati ai limiti specificati.	Il widget utilizza la proprietà locationBias per orientare i risultati in base ai limiti specificati e la proprietà locationRestriction per limitare la ricerca ai limiti specificati.
I widget possono essere integrati solo utilizzando un elemento di input HTML standard.	Il widget può essere integrato utilizzando un elemento di input HTML standard o un elemento gmp-place-autocomplete.
Quando si utilizza il widget, è possibile che gli utenti richiedano elementi che potrebbero non essere validi (ad esempio "bisneyland"); questo caso deve essere gestito esplicitamente.	Il widget restituirà risultati solo per i suggerimenti forniti e non può inviare richieste per valori arbitrari. Pertanto, non è necessario gestire richieste potenzialmente non valide.
Restituisce l'istanza PlaceResult precedente.	Restituisce l'istanza Place.
I campi dei dati dei luoghi sono impostati come opzioni per l'oggetto Autocomplete.	I campi dei dati dei luoghi vengono impostati quando l'utente effettua una selezione e viene chiamato fetchFields().
Limitato a un insieme fisso di tipi di luoghi e campi di dati sui luoghi.	Accesso a una selezione ampliata di tipi di luoghi e campi di dati dei luoghi.

Confronto del codice (widget)

Questa sezione mette a confronto il codice per il completamento automatico per illustrare le differenze tra il widget di completamento automatico dei luoghi precedente e il nuovo elemento di completamento automatico dei luoghi.

Widget di completamento automatico dei luoghi (legacy)

Il servizio Places offre due tipi di widget di completamento automatico, che puoi aggiungere utilizzando le classi Autocomplete e SearchBox. Ogni tipo di widget può essere aggiunto a una mappa come controllo della mappa o incorporato direttamente in una pagina web. Il seguente esempio di codice mostra l'inserimento di un widget Autocomplete come controllo della mappa.

• Il costruttore del widget Autocomplete accetta due argomenti:
  • Un elemento HTML input di tipo text. Si tratta del campo di immissione che il servizio di completamento automatico monitora e a cui allega i risultati.
  • Un argomento AutocompleteOptions facoltativo, in cui puoi specificare ulteriori opzioni per limitare la query.
• Per impostare i limiti, l'istanza Autocomplete può essere vincolata esplicitamente alla mappa chiamando autocomplete.bindTo().
• Specifica i campi dei dati dei luoghi nelle opzioni per il completamento automatico.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapTypeControl: false,
  });
  const card = document.getElementById("pac-card");
  const input = document.getElementById("pac-input");
  const options = {
    fields: ["formatted_address", "geometry", "name"],
    strictBounds: false,
  };

  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

  const autocomplete = new google.maps.places.Autocomplete(input, options);

  // Bind the map's bounds (viewport) property to the autocomplete object,
  // so that the autocomplete requests use the current map bounds for the
  // bounds option in the request.
  autocomplete.bindTo("bounds", map);

  const infowindow = new google.maps.InfoWindow();
  const infowindowContent = document.getElementById("infowindow-content");

  infowindow.setContent(infowindowContent);

  const marker = new google.maps.Marker({
    map,
    anchorPoint: new google.maps.Point(0, -29),
  });

  autocomplete.addListener("place_changed", () => {
    infowindow.close();
    marker.setVisible(false);

    const place = autocomplete.getPlace();

    if (!place.geometry || !place.geometry.location) {
      // User entered the name of a Place that was not suggested and
      // pressed the Enter key, or the Place Details request failed.
      window.alert("No details available for input: '" + place.name + "'");
      return;
    }

    // If the place has a geometry, then present it on a map.
    if (place.geometry.viewport) {
      map.fitBounds(place.geometry.viewport);
    } else {
      map.setCenter(place.geometry.location);
      map.setZoom(17);
    }

    marker.setPosition(place.geometry.location);
    marker.setVisible(true);
    infowindowContent.children["place-name"].textContent = place.name;
    infowindowContent.children["place-address"].textContent =
      place.formatted_address;
    infowindow.open(map, marker);
  });
}

• Documentazione di Place Autocomplete
• Esempio di widget di completamento automatico dei luoghi
• Esempio di casella di ricerca di Places
• Riferimento alla classe Autocomplete

Widget di completamento automatico dei luoghi (novità)

La classe Place offre il componente PlaceAutocompleteElement, una sottoclasse di HTMLElement che fornisce un componente dell'interfaccia utente che può essere aggiunto a una mappa come controllo della mappa o incorporato direttamente in una pagina web. L'esempio di codice riportato di seguito mostra l'inserimento di un widget PlaceAutocompleteElement come controllo della mappa.

Il widget di completamento automatico dei luoghi è stato migliorato nei seguenti modi:

• L'interfaccia utente del widget di completamento automatico supporta la localizzazione regionale (incluse le lingue RTL), per il segnaposto di immissione di testo, il logo dell'elenco di 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.
• Prestazioni e aspetto grafico migliorati.

Le differenze principali di implementazione includono:

• Le previsioni delle query non sono disponibili nella classe Autocomplete.
• PlaceAutocompleteElement viene creato utilizzando PlaceAutocompleteElementOptions.
• I campi dei dati dei luoghi vengono specificati al momento della selezione (quando viene chiamato fetchFields()).
• Imposta i limiti utilizzando l'opzione locationBounds o locationRestriction.
• Associa PlaceAutocompleteElement a un elemento di input di testo HTML utilizzando l'attributo id (ereditato da HTMLElement).

let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  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,
  });

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

  placeAutocomplete.id = "place-autocomplete-input";
  const card = document.getElementById("place-autocomplete-card");

  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.
  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,
  });
}

• Documentazione del widget di completamento automatico dei luoghi (anteprima)
• Esempio di widget di completamento automatico dei luoghi
• Esempio di elemento Place Autocomplete
• Riferimento alla classe PlaceAutocompleteElement