Eseguire la migrazione al nuovo completamento automatico dei luoghi

Sviluppatori dello Spazio economico europeo (SEE)

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

Questa pagina spiega le differenze tra le funzionalità di Place Autocomplete legacy e quelle nuove. In entrambe le versioni esistono due modi generali per integrare Autocomplete:

  • 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 di programmazione di Autocomplete

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

PlacesService (Legacy) Place (Nuovo)
Riferimento del servizio Place Autocomplete Riferimento Autocomplete Data (new)
AutocompletionRequest AutocompleteRequest
AutocompleteService.getPlacePredictions AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction PlacePrediction
I metodi richiedono l'utilizzo di un callback per gestire l'oggetto dei risultati e la risposta PlacesServiceStatus. Utilizza le Promise e funziona in modo asincrono.
I metodi richiedono un controllo PlacesServiceStatus. Non è richiesto alcun controllo dello stato, è possibile utilizzare la gestione degli errori standard. Ulteriori informazioni.
I campi di 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 nella classe Autocomplete.
Limitato a un insieme fisso di tipi di luoghi e campi di dati dei luoghi. Accesso a una selezione ampliata di tipi di luoghi e campi di dati dei luoghi.

Le seguenti vengono utilizzate sia dalle API Autocomplete legacy sia da quelle nuove:

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 di programmazione.

Recupera 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 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 istanze AutocompletePrediction 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);
}

Recupera le previsioni di completamento automatico (novità)

La nuova classe Place consente inoltre di recuperare le previsioni di completamento automatico in modo programmatico per un maggiore controllo sull'interfaccia utente rispetto a quello 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 istanze placePrediction 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}`
}

Widget Place Autocomplete

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

Servizio Places (legacy) Place (novità)
Classe Autocomplete per le previsioni dei luoghi. Classe PlaceAutocompleteElement per le previsioni dei luoghi.
Classe SearchBox
per le previsioni delle query. 		Le previsioni delle query non sono disponibili nella classe Autocomplete.
Solo il testo segnaposto di input predefinito è localizzato. Il segnaposto per l'inserimento 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 (bias) la ricerca ai limiti specificati e strictBounds per limitare i risultati ai limiti specificati. Il widget utilizza la proprietà locationBias per influenzare 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 utilizzano il widget, gli utenti possono richiedere elementi che potrebbero non essere validi (ad esempio "bisneyland"); questo caso deve essere gestito esplicitamente. Il widget restituirà solo i risultati per i suggerimenti forniti e non può inviare richieste per valori arbitrari, pertanto non è necessario gestire richieste potenzialmente non valide.
Restituisce l'istanza PlaceResult legacy. Restituisce un'istanza Place.
I campi di dati dei luoghi sono impostati come opzioni per l'oggetto Autocomplete. I campi di 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 dei 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 Place Autocomplete precedente e il nuovo elemento Place Autocomplete.

Widget Place Autocomplete (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'incorporamento di un widget Autocomplete come controllo della mappa.

  • Il costruttore del widget Autocomplete accetta due argomenti:
    • Un elemento HTML input di tipo text. Questo è il campo di immissione che il servizio di completamento automatico monitorerà e a cui allegherà 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 associata 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);
  });
}

Widget Place Autocomplete (nuovo)

La classe Place offre PlaceAutocompleteElement, una sottoclasse HTMLElement che fornisce un componente UI che può essere aggiunto a una mappa come controllo della mappa o incorporato direttamente in una pagina web. L'esempio di codice seguente mostra l'incorporamento di un widget PlaceAutocompleteElement come controllo della mappa.

Il widget Place Autocomplete è stato migliorato nei seguenti modi:

  • La UI del widget Autocomplete supporta la localizzazione regionale (incluse le lingue con scrittura da destra a sinistra) per il segnaposto di immissione del testo, il logo dell'elenco delle previsioni e le previsioni dei luoghi.
  • Accessibilità migliorata, incluso il supporto per screen reader e interazione da tastiera.
  • Il widget Autocomplete restituisce la nuova classe Place per semplificare la gestione dell'oggetto restituito.
  • Migliore supporto per dispositivi mobili e schermi di piccole dimensioni.
  • Prestazioni migliori e aspetto grafico migliorato.

Le principali differenze di implementazione includono:

  • PlaceAutocompleteElement fornisce il proprio campo di immissione e viene inserito direttamente nella pagina utilizzando HTML o JavaScript (anziché fornire un elemento di immissione esistente).
  • Le previsioni delle query non sono disponibili nella classe Autocomplete.
  • PlaceAutocompleteElement viene costruito utilizzando PlaceAutocompleteElementOptions.
    • I campi di dati dei luoghi vengono specificati al momento della selezione (quando viene chiamato fetchFields()).
  • Imposta i limiti utilizzando l'opzione locationBounds o locationRestriction.
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-select listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-select", async ( event ) => {
    const place = event.placePrediction.toPlace();
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location", "viewport"],
    });
    // 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,
  });
}