ההשלמה האוטומטית למקומות היא תכונה של ספריית המקומות ב-Maps JavaScript API. אתם יכולים להשתמש בהשלמה אוטומטית כדי להוסיף לאפליקציות שלכם את ההתנהגות של שדה החיפוש במפות Google, שמאפשרת להקליד מונח חיפוש ולראות הצעות להשלמה.
בדף הזה מוסברים ההבדלים בין התכונות של Place Autocomplete (השלמה אוטומטית למקומות) מהדור הקודם לבין התכונות החדשות. בשתי הגרסאות יש שתי דרכים כלליות לשלב השלמה אוטומטית:
- ממשק פרוגרמטי: למפתחים שרוצים להתאים אישית את חוויית ההשלמה האוטומטית ולשלוט בה יותר.
- ווידג'ט של השלמה אוטומטית למקומות: סרגל חיפוש שאפשר להטמיע במפה או בדף אינטרנט.
ממשק פרוגרמטי להשלמה אוטומטית
בטבלה הבאה מפורטים כמה מההבדלים העיקריים בשימוש בהשלמה אוטומטית פרוגרמטית למקומות בין Places Autocomplete Service (מדור ישן) לבין Autocomplete Data API (חדש):
PlacesService (גרסה קודמת) |
Place (חדש) |
|---|---|
| הפניה אל Places Autocomplete Service | הפניה אל נתוני ההשלמה האוטומטית (חדש) |
AutocompletionRequest |
AutocompleteRequest |
AutocompleteService.getPlacePredictions |
AutocompleteSuggestion.fetchAutocompleteSuggestions |
AutocompletePrediction |
PlacePrediction |
ב-methods צריך להשתמש בקריאה חוזרת (callback) כדי לטפל באובייקט התוצאות ובתגובה PlacesServiceStatus. |
משתמש ב-Promises, ופועל באופן אסינכרוני. |
נדרש PlacesServiceStatus אימות של אמצעי התשלום. |
אין צורך בבדיקת סטטוס, אפשר להשתמש בטיפול רגיל בשגיאות. מידע נוסף |
שדות של נתוני מיקום מוגדרים כאפשרויות כשיוצרים את מופע Autocomplete. |
שדות הנתונים של המקום מוגדרים מאוחר יותר כשמתבצעת קריאה ל-fetchFields(). |
יש תמיכה בחיזוי שאילתות (רק SearchBox). |
התחזיות לגבי שאילתות לא זמינות בכיתה Autocomplete. |
| החיפוש מוגבל לקבוצה קבועה של סוגי מקומות ושדות נתונים של מקומות. | גישה למבחר מורחב של סוגי מקומות ושדות נתוני מקומות. |
ממשקי ה-API הבאים משמשים גם את ממשקי ה-API של ההשלמה האוטומטית מהדור הקודם וגם את ממשקי ה-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);
}
- אחזור חיזויים של השלמה אוטומטית למקומות באופן פרוגרמטי
- דוגמה להשלמה אוטומטית למקומות
- אסימונים לסשן
AutocompletionRequestreferenceAutocompletePredictionreference
אחזור של הצעות להשלמת החיפוש (חדש)
בנוסף, המחלקה 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}`
}
- Place Autocomplete Data API
- דוגמה לחיזויים של נתונים של השלמה אוטומטית למקומות
- דוגמה לסשנים של נתוני השלמה אוטומטית למקומות
- אסימונים לסשן
AutocompleteRequestהפניה לממשקAutocompleteSuggestionהפניה לכיתהPlacePredictionהפניה לכיתה
ווידג'ט של השלמה אוטומטית למקומות
בטבלה הבאה מפורטים כמה מההבדלים העיקריים בשימוש בווידג'טים של השלמה אוטומטית בין Places service (גרסה קודמת) לבין Place class (חדש):
| Places Service (דור קודם) | מקום (חדש) |
|---|---|
מחלקת Autocomplete לחיזויים של מקומות.
|
מחלקת PlaceAutocompleteElement לחיזויים של מקומות.
|
SearchBox classלחיזוי שאילתות. |
התחזיות לגבי שאילתות לא זמינות בכיתה 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שבו אפשר לציין אפשרויות נוספות להגבלת השאילתה.
- אלמנט HTML
- כדי להגדיר גבולות, אפשר לקשור את מופע
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);
});
}
- מסמכי תיעוד בנושא השלמה אוטומטית למקומות
- דוגמה לווידג'ט השלמה אוטומטית למקומות
- דוגמה לתיבת חיפוש של מקומות
Autocompleteהפניה לכיתה
ווידג'ט של השלמה אוטומטית למקומות (חדש)
המחלק 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"],
});
// 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,
});
}
- מאמרי עזרה בנושא ווידג'ט השלמה אוטומטית למקומות (תצוגה מקדימה)
- דוגמה לווידג'ט השלמה אוטומטית למקומות
- דוגמה לרכיב של השלמה אוטומטית למקומות
PlaceAutocompleteElementהפניה לכיתה