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

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

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

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

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

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

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

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

השוואת קוד (באמצעות תוכנה)

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

אחזור של הצעות להשלמת החיפוש (גרסה קודמת)

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

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

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

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

שירות המקומות מציע שני סוגים של ווידג'טים להשלמה אוטומטית, שאפשר להוסיף באמצעות המחלקות 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 כרכיב בקרה של מפה.

השיפורים בווידג'ט השלמה אוטומטית למקומות:

  • ממשק המשתמש של ווידג'ט ההשלמה האוטומטית תומך בלוקליזציה אזורית (כולל שפות 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 ( 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,
  });
}