מעבר לגרסה החדשה של ההשלמה האוטומטית למקומות

מפתחים באזור הכלכלי האירופי (EEA)

ההשלמה האוטומטית למקומות היא תכונה בספריית המקומות ב-Maps JavaScript API. אתם יכולים להשתמש בהשלמה אוטומטית כדי להוסיף לאפליקציות שלכם את התנהגות החיפוש של שדה החיפוש במפות Google.

בדף הזה מוסבר על ההבדלים בין התכונות של השלמה אוטומטית של מקומות בגרסה הקודמת לבין התכונות בגרסה החדשה. בשתי הגרסאות יש שתי דרכים כלליות לשילוב של התכונה 'השלמה אוטומטית':

ממשק פרוגרמטי להשלמה אוטומטית

בטבלה הבאה מפורטים כמה מההבדלים העיקריים בשימוש בהשלמה אוטומטית למקומות באופן פרוגרמטי בין Places Autocomplete Service (גרסה קודמת) לבין Autocomplete Data API (גרסה חדשה):

‫PlacesService (גרסה קודמת) Place (חדש)
הפניה אל שירות ההשלמה האוטומטית למקומות הפניה אל נתוני השלמה אוטומטית (חדש)
AutocompletionRequest AutocompleteRequest
AutocompleteService.getPlacePredictions AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction PlacePrediction
ב-methods צריך להשתמש בקריאה חוזרת כדי לטפל באובייקט התוצאות ובתגובה PlacesServiceStatus. משתמש ב-Promises, ופועל באופן אסינכרוני.
השיטות מחייבות PlacesServiceStatusבדיקה. אין צורך בבדיקת סטטוס, אפשר להשתמש בטיפול רגיל בשגיאות. מידע נוסף
שדות המיקום מוגדרים כאפשרויות כשיוצרים את מופע Autocomplete. שדות נתוני המיקום מוגדרים מאוחר יותר כשמתבצעת קריאה ל-fetchFields().
יש תמיכה בחיזוי שאילתות (רק SearchBox). הצעות לשאילתות לא זמינות בכיתה Autocomplete.
מוגבל לסט קבוע של סוגי מקומות ושדות נתוני מקומות. גישה למבחר מורחב של סוגי מקומות ושדות נתוני מקומות.

הפרמטרים הבאים משמשים גם ב-Autocomplete API מהדור הקודם וגם ב-Autocomplete API החדש:

השוואת קוד (פרוגרמטית)

בקטע הזה מוצג קוד להשלמה אוטומטית כדי להמחיש את ההבדלים בין Places Service לבין Place class, בממשקי תכנות.

אחזור חיזויים להשלמה אוטומטית (גרסה קודמת)

שירות המקומות מדור קודם מאפשר לאחזר תחזיות להשלמה אוטומטית באופן פרוגרמטי, כדי לקבל שליטה רבה יותר בממשק המשתמש מאשר זו שמוצעת על ידי המחלקה Autocomplete. בדוגמה הבאה, מוגשת בקשה אחת ל-par, עם AutocompletionRequest שמורכב מערך הקלט ומקבוצה של גבולות להטיית התחזית. בדוגמה מוחזרת רשימה של מופעי AutocompletePrediction ומוצג התיאור של כל אחד מהם. פונקציית הדוגמה גם יוצרת טוקן סשן ומחילת אותו על הבקשה.

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

אחזור חיזויים להשלמה אוטומטית (חדש)

בנוסף, המחלקה Place החדשה מאפשרת לאחזר באופן פרוגרמטיבי תחזיות להשלמה אוטומטית, כדי לשלוט בממשק המשתמש בצורה טובה יותר מאשר במחלקה PlaceAutocompleteElement. בדוגמה הבאה, מוגשת בקשה אחת ל-par, עם AutocompleteRequest שמורכב מערך הקלט ומקבוצת גבולות להטיית התחזית. בדוגמה מוצגת רשימה של מופעי placePrediction והתיאור של כל אחד מהם. פונקציית הדוגמה גם יוצרת טוקן סשן ומחילת אותו על הבקשה.

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

ווידג'ט של השלמה אוטומטית למקומות

בטבלה הבאה מפורטים כמה מההבדלים העיקריים בשימוש בווידג'טים של השלמה אוטומטית בין שירות Places (מהדור הקודם) לבין המחלקה Place (החדשה):

Places Service (גרסה קודמת) מקום (חדש)
Autocomplete class לחיזויים של מקומות. PlaceAutocompleteElement class לחיזויים של מקומות.
‫SearchBox class
לחיזוי שאילתות. 		הצעות לשאילתות לא זמינות בכיתה Autocomplete.
רק הטקסט של הפלייסהולדר שמוגדר כברירת מחדל מוצג בשפה המקומית. placeholder להזנת טקסט, לוגו של רשימת התחזיות ותחזיות של מקומות – כולם תומכים בלוקליזציה אזורית.
בווידג'ט נעשה שימוש ב- setBounds() או ב-autocomplete.bindTo() כדי להגביל את החיפוש לגבולות שצוינו, וב- strictBounds כדי להגביל את התוצאות לגבולות שצוינו. בווידג'ט נעשה שימוש במאפיין locationBias כדי להטות את התוצאות לגבולות שצוינו, ובמאפיין locationRestriction כדי להגביל את החיפוש לגבולות שצוינו.
אפשר לשלב ווידג'טים רק באמצעות רכיב קלט HTML רגיל. אפשר לשלב את הווידג'ט באמצעות רכיב קלט HTML רגיל או רכיב gmp-place-autocomplete.
במהלך השימוש בווידג'ט, יכול להיות שהמשתמשים יבקשו דברים שלא יהיו תקפים (לדוגמה, "bisneyland"). במקרה כזה, צריך לטפל בבקשה באופן מפורש. הווידג'ט יחזיר רק תוצאות של ההצעות שסופקו, ולא יכול להנפיק בקשות לערכים שרירותיים. לכן אין צורך לטפל בבקשות שעלולות להיות לא תקינות.
השיטה מחזירה מופע מדור קודם של PlaceResult. הפונקציה מחזירה מופע של Place.
שדות נתוני המקום מוגדרים כאפשרויות לאובייקט Autocomplete. שדות נתוני המיקום מוגדרים כשהמשתמש בוחר מיקום ומתבצעת קריאה ל-fetchFields().
מוגבל לסט קבוע של סוגי מקומות ושדות נתוני מקומות. גישה למבחר מורחב של סוגי מקומות ושדות נתוני מקומות.

השוואת קוד (ווידג'טים)

בקטע הזה מוצג קוד להשלמה אוטומטית כדי להמחיש את ההבדלים בין הווידג'ט Place Autocomplete בגרסה הקודמת לבין הרכיב Place Autocomplete החדש.

ווידג'ט של השלמה אוטומטית למקומות (גרסה קודמת)

שירות המקומות מציע שני סוגים של ווידג'טים של השלמה אוטומטית, שאפשר להוסיף באמצעות המחלקות Autocomplete ו-SearchBox. אפשר להוסיף כל סוג של ווידג'ט למפה ככלי בקרה במפה, או להטמיע אותו ישירות בדף אינטרנט. בדוגמת הקוד הבאה מוצג ווידג'ט Autocompleteמוטמע ככלי לניהול מפה.

  • ה-constructor של הווידג'ט Autocomplete מקבל שני ארגומנטים:
    • אלמנט HTML ‏input מסוג text. זהו שדה הקלט שהשירות להשלמה אוטומטית ינטר ויצרף אליו את התוצאות.
    • ארגומנט אופציונלי AutocompleteOptions שבו אפשר לציין אפשרויות נוספות להגבלת השאילתה.
  • כדי להגדיר גבולות, אפשר לקשור את מופע Autocomplete באופן מפורש למפה על ידי קריאה ל-autocomplete.bindTo().
  • מציינים את שדות הנתונים של המקומות באפשרויות של ההשלמה האוטומטית.
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);
  });
}

ווידג'ט של השלמה אוטומטית למקומות (חדש)

המחלק Place מציע את המחלקה PlaceAutocompleteElement, מחלקת משנה של HTMLElement שמספקת רכיב ממשק משתמש שאפשר להוסיף למפה כרכיב בקרה של המפה, או להטמיע אותו ישירות בדף אינטרנט. בדוגמת הקוד הבאה מוצגת הטמעה של ווידג'ט PlaceAutocompleteElement כרכיב בקרה של מפה.

השיפורים שבוצעו בווידג'ט Place Autocomplete:

  • ממשק המשתמש של הווידג'ט להשלמה אוטומטית תומך בלוקליזציה אזורית (כולל שפות RTL), עבור placeholder של הזנת טקסט, לוגו של רשימת תחזיות ותחזיות של מקומות.
  • נגישות משופרת, כולל תמיכה בקוראי מסך ואינטראקציה באמצעות המקלדת.
  • ווידג'ט ההשלמה האוטומטית מחזיר את המחלקה החדשה Place כדי לפשט את הטיפול באובייקט שהוחזר.
  • שיפור התמיכה במכשירים ניידים ובמסכים קטנים.
  • שיפור הביצועים והמראה הגרפי.

ההבדלים העיקריים בהטמעה כוללים:

  • התג PlaceAutocompleteElement מספק שדה קלט משלו, והוא מוכנס ישירות לדף באמצעות HTML או JavaScript (בניגוד למצב שבו מסופק רכיב קלט קיים).
  • התחזיות לשאילתות לא זמינות במחלקה Autocomplete.
  • המאפיין PlaceAutocompleteElement מורכב מPlaceAutocompleteElementOptions.
    • שדות הנתונים של המקום מצוינים בזמן הבחירה (כשמתבצעת קריאה ל-fetchFields() ).
  • מגדירים גבולות באמצעות האפשרות locationBounds או 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 ( place ) => {
    const place = event.placePrediction.toPlace();
    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,
  });
}