עיצוב מפות חדש יתווסף בקרוב לפלטפורמה של מפות Google. העדכון הזה בסגנון המפה כולל לוח צבעים חדש שמוגדר כברירת מחדל ושיפורים בחוויית השימוש במפות ובנוחות השימוש. כל סגנונות המפה יעודכנו באופן אוטומטי במרץ 2025. אפשר לקרוא מידע נוסף על זמינות ועל האפשרות להצטרף בשלב מוקדם יותר במאמר בנושא סגנון מפה חדש לפלטפורמה של מפות Google.
בדף הזה מתוארת הספרייה בצד הלקוח שזמינה עם
API של JavaScript של מפות Google. אם אתם רוצים לעבוד עם שירות האינטרנט של Places API בשרת שלכם, בדקו את לקוח Node.js לשירותי מפות Google. הדף שבקישור הזה מציג גם את לקוח Java, לקוח Python ולקוח Go לשירותי מפות Google.
מבוא
השלמה אוטומטית היא תכונה של ספריית 'מקומות'
ב-JavaScript API של מפות Google. אפשר להשתמש בהשלמה אוטומטית כדי להציג לאפליקציות שלך את
ההתנהגות של חיפוש מסוג 'הקלדה קדימה' בשדה החיפוש במפות Google.
שירות ההשלמה האוטומטית יכול להתאים לפי מילים מלאות ומחרוזות משנה, תוך התאמת
שמות של מקומות, כתובות וקודי פלוס. לכן האפליקציות יכולות לשלוח שאילתות בזמן שהמשתמש מקליד, כדי לספק חיזויים לגבי מקומות בזמן אמת. כפי שמוגדר ב-Places API, 'מקום' יכול להיות מוסד, מיקום גיאוגרפי או נקודת עניין בולטת.
איך מתחילים
לפני השימוש בספרייה Places ב-Maps JavaScript API, צריך קודם לוודא שה-Places API מופעל במסוף Google Cloud באותו פרויקט שהגדרת ל-Maps JavaScript API.
לוחצים על הלחצן Select a project, בוחרים את אותו הפרויקט שהגדרתם ב-Maps JavaScript API ולוחצים על Open.
ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את
Places API.
אם ה-API מופיע ברשימה, אז לא צריך לבצע פעולה נוספת. אם ה-API לא מופיע ברשימה,
מפעילים אותו:
בחלק העליון של הדף לוחצים על ENABLE API כדי להציג את הכרטיסייה ספרייה. לחלופין, בתפריט שמשמאל לוחצים על Library.
מחפשים את Places API ובוחרים אותו מרשימת התוצאות.
בוחרים באפשרות הפעלה. בסיום התהליך יופיע Places API ברשימת ממשקי ה-API במרכז הבקרה.
הספרייה בטעינה
שירות 'מקומות' הוא ספרייה עצמאית, נפרדת מהקוד הראשי
של JavaScript API של מפות Google. כדי להשתמש בפונקציונליות שכלולה בספרייה הזו, קודם צריך לטעון אותה באמצעות הפרמטר libraries
בכתובת ה-URL של bootrap של מפות Google:
ב-API יש שני סוגים של ווידג'טים של השלמה אוטומטית, שאפשר להוסיף באמצעות המחלקות Autocomplete ו-SearchBox בהתאמה.
בנוסף, תוכלו להשתמש במחלקה AutocompleteService כדי לאחזר תוצאות של השלמה אוטומטית באופן פרוגרמטי (ראו מידע על JavaScript API של Maps:
InventoryService class)
לפניכם סיכום של הכיתות הזמינות:
Autocomplete מוסיף שדה להזנת טקסט לדף האינטרנט ועוקב אחרי רשומות התווים בשדה הזה. כשהמשתמש מזין טקסט, ההשלמה האוטומטית מחזירה חיזויים של מקומות בצורה של רשימה נפתחת לבחירה. כשהמשתמש בוחר מקום מהרשימה, המידע על המקום מוחזר לאובייקט של ההשלמה האוטומטית, והאפליקציה יכולה לאחזר אותו. פרטים נוספים זמינים בהמשך.
איור 1: השלמה אוטומטית של שדה טקסט ובחירת רשימהאיור 2: טופס כתובת מלא
SearchBox מוסיפה לדף האינטרנט שדה להזנת טקסט, באופן דומה מאוד ל-Autocomplete. אלה ההבדלים:
ההבדל העיקרי טמון
בתוצאות שמופיעות ברשימת הבחירה. SearchBox מספקת רשימה מורחבת של חיזויים, שכוללים מקומות (כפי שהוגדרו על ידי Places API) וגם הצעות למונחי חיפוש. לדוגמה, אם המשתמש
יזין את המילה 'פיצה', רשימת הבחירות עשויה לכלול את הביטוי
'פיצה בתל אביב, ישראל' וגם את השמות של פיצריות שונות.
SearchBox מציע פחות אפשרויות מאשר Autocomplete להגבלת החיפוש. באפשרות הראשונה, אפשר
להטות את החיפוש לפי LatLngBounds נתון. באפשרות השנייה, אפשר להגביל את החיפוש למדינה מסוימת ולסוגים מסוימים של מקומות, וכן להגדיר גבולות. מידע נוסף מופיע
בהמשך.
איור 3: תיבת חיפוש מציגה מונחי חיפוש ומציבה חיזויים.
פרטים נוספים מופיעים בהמשך.
תוכלו ליצור אובייקט AutocompleteService כדי לאחזר חיזויים באופן פרוגרמטי. צריך להתקשר למספר getPlacePredictions() כדי
לאחזר מקומות תואמים, או להתקשר למספר getQueryPredictions() כדי
לאחזר מקומות תואמים וגם הצעות למונחי חיפוש.
הערה: AutocompleteService לא מוסיפה פקדים בממשק המשתמש.
במקום זאת, השיטות שלמעלה מחזירות מערך של אובייקטים של חיזוי. כל
אובייקט חיזוי מכיל את הטקסט של החיזוי, וגם פרטי הפניה ופרטים לגבי האופן שבו התוצאה תואמת לקלט של המשתמש. אפשר לקרוא פרטים נוספים בהמשך.
הוספת ווידג'ט של השלמה אוטומטית
הווידג'ט Autocomplete יוצר שדה להזנת טקסט בדף האינטרנט, מספק תחזיות לגבי מקומות ברשימת בחירה של ממשק המשתמש ומחזיר את פרטי המקום בתגובה לבקשת getPlace(). כל רשומה ברשימה שנבחרה תואמת למקום אחד (כפי שמוגדר ב-Places API).
ה-constructor של Autocomplete מקבל שני ארגומנטים:
רכיב input HTML מסוג text. זה השדה להזנת הקלט ששירות ההשלמה האוטומטית יעקוב אחריו ויצורף אליו את התוצאות.
מערך של הנתונים fields שייכלל בתשובה Place Details ב-PlaceResult שנבחר על ידי המשתמש. אם המאפיין לא מוגדר או אם ['ALL'] מועבר, יוחזרו כל השדות הזמינים ויחויבו על (לא מומלץ בפריסות בסביבת ייצור). לרשימת השדות: PlaceResult.
מערך של types שמציין סוג מפורש או אוסף סוגים, כפי שמפורט בסוגים הנתמכים. אם לא תציינו סוג, כל הסוגים יוחזרו.
bounds הוא אובייקט google.maps.LatLngBounds שמציין את האזור שבו מחפשים מקומות. התוצאות מוטות כלפי מקומות שנכללים בגבולות האלה, אבל לא רק.
strictBounds הוא boolean, שמציין אם ה-API חייב להחזיר רק את המקומות שנמצאים אך ורק בתוך האזור שהוגדר על ידי bounds הנתון. ה-API לא מחזיר תוצאות מחוץ לאזור הזה, גם אם הן תואמות לקלט של המשתמשים.
אפשר להשתמש ב-componentRestrictions כדי להגביל את התוצאות לקבוצות ספציפיות. כרגע אפשר לסנן באמצעות componentRestrictions לפי עד 5 מדינות. צריך להעביר את המדינות כקוד מדינה בן שני תווים שתואם ל-ISO 3166-1 Alpha-2. יש להעביר כמה מדינות כרשימה של קודי מדינות.
אפשר להשתמש ב-placeIdOnly כדי להורות לווידג'ט Autocomplete לאחזר רק מזהי מקומות. בהפעלת getPlace() באובייקט Autocomplete, ל-PlaceResult שיהיה זמין יוגדרו רק המאפיינים place id, types ו-name. אפשר להשתמש במזהה המקום שהוחזר בקריאות לשירותים 'מקומות', 'קידוד גיאוגרפי', 'מסלולים' או
'מטריצת מרחק'.
הגבלת חיזויים של השלמה אוטומטית
כברירת מחדל, ההשלמה האוטומטית של המקום מציגה את כל סוגי המקומות, עם הטיה לגבי חיזויים שנמצאים בקרבת
המיקום של המשתמש, ומאחזרת את כל שדות הנתונים שזמינים למקום שנבחר על ידי המשתמש. אתם יכולים להגדיר אפשרויות להשלמה אוטומטית של מקומות כדי להציג חיזויים רלוונטיים יותר על סמך התרחיש לדוגמה שלכם.
הגדרת אפשרויות בזמן הבנייה
ה-constructor של Autocomplete מקבל את הפרמטר AutocompleteOptions כדי להגדיר אילוצים ביצירת הווידג'ט. הדוגמה הבאה מגדירה את האפשרויות
bounds, componentRestrictions ו-types
כדי לבקש מקומות מסוג establishment, עם עדיפות לאלה שנמצאים באזור הגיאוגרפי שצוין ומגבילה את החיזויים רק למקומות בתוך ארצות הברית. האפשרות fields מציינת איזה מידע יוחזר לגבי המקום שנבחר על ידי המשתמש.
קוראים לפונקציה setOptions() כדי לשנות ערך של אפשרות בווידג'ט קיים.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
north: center.lat + 0.1,
south: center.lat - 0.1,
east: center.lng + 0.1,
west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
bounds: defaultBounds,
componentRestrictions: { country: "us" },
fields: ["address_components", "geometry", "icon", "name"],
strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
מציינים שדות נתונים כדי למנוע חיוב עבור מק"טים של נתוני מקומות שאין בהם צורך. כוללים את המאפיין fields ב-AutocompleteOptions שמועבר ל-constructor של הווידג'טים, כמו שמוצג בדוגמה הקודמת, או קוראים לפונקציה setFields() באובייקט Autocomplete קיים.
צריך להגדיר את האפשרות strictBounds כדי להגביל את התוצאות לגבולות הנוכחיים, על סמך אזור התצוגה של המפה או גבולות מלבניים.
autocomplete.setOptions({ strictBounds: true });
הגבלת החיזויים למדינה ספציפית
אפשר להשתמש באפשרות componentRestrictions או להפעיל את הפקודה setComponentRestrictions() כדי להגביל את חיפוש ההשלמה האוטומטית לקבוצה ספציפית של עד חמש מדינות.
אפשר להשתמש באפשרות types או להפעיל את הפקודה setTypes() כדי להגביל חיזויים לסוגים מסוימים של מקומות. האילוץ הזה מציין סוג או אוסף של סוגי פריטים, כפי שמפורט בקטע Place types (סוגי מקומות).
אם לא מגדירים אילוץ, מוחזרים כל הסוגים.
בשביל הערך של האפשרות types או של הערך שמועבר ל-setTypes(), אפשר לציין אחת מהאפשרויות הבאות:
כשמשתמש בוחר מקום מהחיזויים שמצורפים לשדה הטקסט של ההשלמה האוטומטית, השירות מפעיל אירוע place_changed. כדי לקבל את פרטי המקום:
יוצרים handler של אירוע עבור האירוע place_changed ומפעילים את הפקודה addListener()
באובייקט Autocomplete כדי להוסיף את ה-handler.
קוראים לפונקציה Autocomplete.getPlace() באובייקט Autocomplete כדי לאחזר אובייקט PlaceResult, ולהשתמש בו כדי לקבל מידע נוסף על המקום שנבחר.
כברירת מחדל, כשמשתמש בוחר מקום, ההשלמה האוטומטית מחזירה את כל
שדות הנתונים שזמינים למקום שנבחר, והחיוב יתבצע בהתאם.
משתמשים ב-Autocomplete.setFields() כדי לציין אילו שדות של נתוני מקום יוחזרו. מידע נוסף על האובייקט PlaceResult, כולל רשימת שדות של נתוני מקום שאפשר לבקש. כדי להימנע מתשלום על נתונים שאתם לא צריכים, חשוב להשתמש ב-Autocomplete.setFields() כדי לציין
רק את נתוני המקום שבהם תשתמשו.
בטופסי כתובת מומלץ להשתמש בפורמט מובנה של הכתובת. כדי
להחזיר את הכתובת המובנית למקום שנבחר, קוראים
Autocomplete.setFields()
ומציינים את השדה address_components.
בדוגמה הבאה נעשה שימוש בהשלמה אוטומטית כדי למלא את השדות בטופס כתובת.
TypeScript
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
(document.querySelector("#locality") as HTMLInputElement).value =
component.long_name;
break;
case "administrative_area_level_1": {
(document.querySelector("#state") as HTMLInputElement).value =
component.short_name;
break;
}
case "country":
(document.querySelector("#country") as HTMLInputElement).value =
component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
document.querySelector("#locality").value = component.long_name;
break;
case "administrative_area_level_1": {
document.querySelector("#state").value = component.short_name;
break;
}
case "country":
document.querySelector("#country").value = component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
window.initAutocomplete = initAutocomplete;
כברירת מחדל, שדה הטקסט שנוצר על ידי שירות ההשלמה האוטומטית מכיל
placeholder של טקסט סטנדרטי. כדי לשנות את הטקסט, צריך להגדיר את המאפיין placeholder ברכיב input:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
הערה: הטקסט של ה-placeholder שמוגדר כברירת מחדל מותאם לשוק המקומי באופן אוטומטי. אם אתם
מציינים ערך placeholder משלכם, תצטרכו לטפל בלוקליזציה של הערך הזה באפליקציה. למידע על האופן שבו ה-JavaScript API של מפות Google בוחר את השפה שבה רוצים להשתמש, אפשר לקרוא את המסמכים בנושא
התאמה לשוק המקומי.
המאפיין SearchBox מאפשר למשתמשים לבצע חיפוש גיאוגרפי מבוסס-טקסט, כמו 'פיצה בתל אביב' או 'חנויות נעליים ליד רחוב תומר'.
אפשר לצרף את SearchBox לשדה טקסט, וכשמזינים טקסט, השירות יחזיר תוצאות חזויות בצורה של רשימה נפתחת עם אפשרויות לבחירה.
SearchBox מספק רשימה מורחבת של חיזויים, שיכולים לכלול מקומות (כפי שהוגדר ב-Places API) וגם הצעות למונחי חיפוש. לדוגמה, אם המשתמש יזין 'פיצה בחדש', רשימת הבחירות עשויה
לכלול את הביטוי 'פיצה בתל אביב', וגם את השמות של מגוון
פיצריות. כשמשתמש בוחר מקום מהרשימה, המידע על המקום הזה מוחזר לאובייקט SearchBox וניתן לאחזר אותו באמצעות האפליקציה.
ה-constructor של SearchBox מקבל שני ארגומנטים:
רכיב input HTML מסוג text. זה
השדה להזנת קלט, יעקוב השירות של SearchBox
ויצטרף אליו את התוצאות.
ארגומנט options, שיכול להכיל את המאפיין bounds: bounds הוא אובייקט google.maps.LatLngBounds שמציין את האזור שבו מחפשים מקומות. התוצאות
מוטות כלפי מקומות שנכללים
בגבולות האלה, אבל לא רק.
הקוד הבא משתמש בפרמטר גבולות כדי להטות את התוצאות
למקומות בתוך אזור גיאוגרפי מסוים, שצוין באמצעות
קואורדינטות של קווי אורך ורוחב.
var defaultBounds = new google.maps.LatLngBounds(
new google.maps.LatLng(-33.8902, 151.1759),
new google.maps.LatLng(-33.8474, 151.2631));
var input = document.getElementById('searchTextField');
var searchBox = new google.maps.places.SearchBox(input, {
bounds: defaultBounds
});
שינוי אזור החיפוש של תיבת החיפוש
כדי לשנות את אזור החיפוש של SearchBox קיים, מפעילים את הפונקציה setBounds() באובייקט SearchBox ומעבירים את האובייקט LatLngBounds הרלוונטי.
כשמשתמש בוחר פריט מהחיזויים שמצורפים לתיבת החיפוש, השירות מפעיל אירוע places_changed. אפשר לקרוא ל-getPlaces() באובייקט SearchBox, כדי לאחזר מערך שמכיל מספר חיזויים, כשכל אחד מהם הוא אובייקט PlaceResult.
למידע נוסף על האובייקט PlaceResult, עיינו במסמכי התיעוד בנושא
תוצאות של פרטי מקום.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon as string,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
})
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
}),
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
אחזור פרוגרמטי של חיזויים של שירות ההשלמה האוטומטית של מקומות
כדי לאחזר חיזויים באופן פרוגרמטי, משתמשים במחלקה AutocompleteService. הפונקציה AutocompleteService
לא מוסיפה פקדים בממשק המשתמש. במקום זאת, היא מחזירה מערך של אובייקטי חיזוי, שכל אחד מהם מכיל את הטקסט של החיזוי, פרטי הפניה ופרטים על האופן שבו התוצאה תואמת לקלט של המשתמש.
האפשרות הזו שימושית אם אתם רוצים יותר שליטה בממשק המשתמש, ממה שמוצע ב-Autocomplete וב-SearchBox שמתוארים למעלה.
הקוד AutocompleteService חושף את השיטות הבאות:
הפונקציה getPlacePredictions() מחזירה חיזויים לגבי מקום.
הערה: 'מקום' יכול להיות מוסד, מיקום גיאוגרפי או נקודת עניין
בולטת, כפי שמוגדר ב-Places API.
הפונקציה getQueryPredictions() מחזירה רשימה מורחבת של
חיזויים, שיכולים לכלול מקומות (כפי שהוגדר ב-Places API)
וגם הצעות למונחי חיפוש. לדוגמה, אם המשתמש
יזין 'פיצה בחדש', רשימת הבחירות עשויה לכלול את הביטוי
'פיצה בתל אביב, ישראל' וגם את השמות של פיצריות שונות.
distance_meters הוא המרחק במטרים מהמקום
מה-AutocompletionRequest.origin שצוין.
matched_substrings מכיל קבוצה של מחרוזות משנה בתיאור
שתואמות לרכיבים בקלט של המשתמש. האפשרות הזו שימושית כדי
להדגיש את מחרוזות המשנה האלה באפליקציה. במקרים רבים
השאילתה תופיע כמחרוזת משנה של שדה התיאור.
length הוא האורך של מחרוזת המשנה.
offset הוא היסט התווים, שנמדד מתחילת מחרוזת התיאור, שבה מופיעה מחרוזת המשנה התואמת.
terms הוא מערך שמכיל את הרכיבים של השאילתה. במקום מסוים, כל רכיב בדרך כלל מהווה חלק מהכתובת.
offset הוא היסט התווים, שנמדד מתחילת מחרוזת התיאור, שבה מופיעה מחרוזת המשנה התואמת.
value הוא המונח התואם.
הדוגמה הבאה מפעילה בקשה לחיזוי שאילתה עבור הביטוי 'פיצה ליד', ומציגה את התוצאה ברשימה.
TypeScript
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
const displaySuggestions = function (
predictions: google.maps.places.QueryAutocompletePrediction[] | null,
status: google.maps.places.PlacesServiceStatus
) {
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") as HTMLUListElement).appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
declare global {
interface Window {
initService: () => void;
}
}
window.initService = initService;
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
const displaySuggestions = function (predictions, status) {
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 service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
window.initService = initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<p>Query suggestions for 'pizza near Syd':</p>
<ul id="results"></ul>
<!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
<img
class="powered-by-google"
src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
alt="Powered by Google"
/>
<!--
The `defer` attribute causes the script to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises. See
https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
defer
></script>
</body>
</html>
AutocompleteService.getPlacePredictions() יכול להשתמש באסימוני סשן (אם הם הוטמעו) כדי לקבץ יחד בקשות להשלמה אוטומטית למטרות חיוב. אסימוני סשן מקבצים את שלבי השאילתה והבחירה של החיפוש בהשלמה אוטומטית של משתמש לסשן נפרד למטרות חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהוא בוחר מקום. כל סשן יכול לכלול כמה שאילתות, ואחריו צריך לבחור מקום אחד.
האסימון כבר לא תקף אחרי שהסשן מסתיים. האפליקציה שלכם צריכה ליצור אסימון חדש לכל סשן. מומלץ להשתמש באסימוני סשנים בכל הסשנים של ההשלמה האוטומטית. אם משמיטים את הפרמטר sessionToken, או אם משתמשים שוב באסימון סשן, הסשן יחויב כאילו לא סופק אסימון סשן (כל בקשה מחויב בנפרד).
אפשר להשתמש באותו אסימון סשן כדי לשלוח בקשה אחת של פרטי מקום במקום שמתקבל מקריאה ל-AutocompleteService.getPlacePredictions().
במקרה כזה, הבקשה להשלמה האוטומטית משולבת עם הבקשה של פרטי המקום, והשיחה מחויבת כבקשה רגילה של פרטי המקום. בקשת ההשלמה האוטומטית לא כרוכה בתשלום.
חשוב להעביר אסימון סשן ייחודי לכל סשן חדש. שימוש באותו אסימון ליותר מסשן אחד של השלמה אוטומטית יבטל את התוקף של הסשנים האלה של ההשלמה האוטומטית, וכל בקשות להשלמה אוטומטית בסשנים הלא חוקיים יחויבו בנפרד באמצעות השלמה אוטומטית
לכל מק"ט של בקשה. מידע נוסף על אסימוני סשנים
הדוגמה הבאה מציגה יצירה של אסימון סשן והעברתו ב-AutocompleteService (הפונקציה displaySuggestions() הושמטה כדי לקצר):
// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
input: 'pizza near Syd',
sessionToken: sessionToken
},
displaySuggestions);
חשוב להעביר אסימון סשן ייחודי לכל סשן חדש. שימוש באותו אסימון ליותר מסשן אחד יגרום לכך שכל בקשה תחויב בנפרד.
כברירת מחדל, רכיבי ממשק המשתמש שסופקו על ידי Autocomplete
ו-SearchBox מעוצבים בסגנון כדי להופיע במפת Google. מומלץ
לשנות את הסגנון כך שיתאים לאתר שלך. מחלקות ה-CSS הבאות זמינות. כל המחלקות שמפורטות בהמשך חלות גם על הווידג'טים Autocomplete וגם על SearchBox.
מחלקות CSS לווידג'טים של השלמה אוטומטית וווידג'טים של תיבת חיפוש
רמת CSS
תיאור
pac-container
הרכיב החזותי שמכיל את רשימת החיזויים שהוחזרו על ידי שירות ההשלמה האוטומטית של המקום. הרשימה הזו מופיעה כרשימה נפתחת מתחת לווידג'ט Autocomplete או SearchBox.
pac-icon
הסמל שמוצג מימין לכל פריט ברשימת החיזויים.
pac-item
פריט ברשימת החיזויים שסופק על ידי
הווידג'ט Autocomplete או SearchBox.
pac-item:hover
הפריט כשהמשתמש מעביר מעליו את סמן העכבר.
pac-item-selected
הפריט כשהמשתמש בוחר בו באמצעות המקלדת. הערה: הפריטים שנבחרו
יהיו חברים בכיתה הזו ובכיתה pac-item.
pac-item-query
טווח בתוך pac-item שהוא החלק המרכזי של
החיזוי. עבור מיקומים גיאוגרפיים, המאפיין הזה כולל שם של מקום, כמו
'סידני', או שם של רחוב ומספר, כמו 'רחוב קינג 10'. בחיפושים מבוססי-טקסט כמו 'פיצה בתל אביב', מילת המפתח מכילה את הטקסט המלא
של השאילתה. כברירת מחדל, pac-item-query צבוע
בשחור. אם יש טקסט נוסף ברכיב pac-item, הוא נמצא מחוץ ל-pac-item-query ויורש את העיצוב שלו מ-pac-item. הוא צבוע באפור כברירת מחדל. הטקסט הנוסף הוא בדרך כלל כתובת.
pac-matched
החלק בחיזוי שהוחזר שתואם לקלט של המשתמש. כברירת מחדל, הטקסט המותאם הזה מודגש בטקסט מודגש. חשוב לשים לב
שהטקסט המותאם יכול להיות במקום כלשהו בתוך pac-item. הוא לא
בהכרח חלק מ-pac-item-query, ויכול להיות שהוא חלק
בתוך pac-item-query, וכן באופן חלקי בטקסט הנותר ב-pac-item.
שימוש ברכיב של בוחר המקומות
הערה: הדוגמה הזו מתבססת על ספריית קוד פתוח. אפשר לעיין
בקובץ README
לקבלת תמיכה
ומשוב שקשורים לספרייה.
אפשר לנסות רכיבי אינטרנט. משתמשים ב
רכיב האינטרנט של הכלי לבחירת מקום כדי להפעיל קלט טקסט שמאפשר למשתמשי קצה לחפש כתובת או מקום ספציפיים באמצעות השלמה אוטומטית.
איור 1: קלט טקסט לחיפוש כתובת או מקום ספציפיים באמצעות השלמה אוטומטית
אופטימיזציה להשלמה אוטומטית של מקומות
בקטע הזה מתוארות שיטות מומלצות שיעזרו לך להפיק את המרב
משירות ההשלמה האוטומטית של המקומות.
לפתח הבנה של שדות נתונים חיוניים להשלמה אוטומטית של מקומות.
השדות 'הטיית מיקום' ו'הגבלת מיקום' הם אופציונליים, אבל יכולה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
כדאי להשתמש בטיפול בשגיאות כדי לוודא שאיכות האפליקציה תשתפר אם ה-API מחזיר שגיאה.
חשוב לוודא שהאפליקציה מטפלת כשלא צריך לבחור אפשרות ומציעה למשתמשים אפשרות
להמשיך.
שיטות מומלצות לאופטימיזציה של עלויות
אופטימיזציה בסיסית של עלויות
כדי לייעל את עלות השימוש בשירות ההשלמה האוטומטית של המקומות, משתמשים במסכות של שדות בווידג'טים של פרטי מקום והשלמה אוטומטית של מקומות כדי להחזיר רק את השדות של נתוני המקום שדרושים.
אופטימיזציה מתקדמת של עלויות
כדאי לשקול הטמעה פרוגרמטית של השלמה אוטומטית של מקומות כדי לגשת לתמחור לפי בקשה ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום פרטי המקום. תמחור לפי בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לפי פעילות (מבוסס-סשן) אם שני התנאים הבאים מתקיימים:
אם אתם צריכים רק את קו הרוחב/קו האורך או הכתובת של המקום שהמשתמש בחר, Geocoding API מספק את המידע הזה בפחות מקריאה של פרטי מקום.
אם משתמשים בוחרים חיזוי להשלמה אוטומטית בתוך ארבע בקשות או פחות חיזויים להשלמה אוטומטית, תמחור לפי בקשה עשוי להיות משתלם יותר מהתמחור לכל סשן.
לקבלת עזרה בבחירת ההטמעה של ההשלמה האוטומטית המקום שמתאימה לצרכים שלכם, בחרו את הכרטיסייה שתואמת לתשובה שלכם לשאלה הבאה.
האם באפליקציה נדרשים פרטים כלשהם מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?
בהנחיות הבאות מתוארות דרכים לאופטימיזציה של ביצועי ההשלמה האוטומטית של המקום:
מוסיפים הגבלות לפי מדינה,
הטיה לפי מיקום וגם את העדפת השפה (בהטמעות פרוגרמטיות) להטמעת ההשלמה האוטומטית של המקום. אין צורך בהעדפת שפה
עם ווידג'טים כי הם בוחרים את העדפות השפה מהדפדפן או מהנייד של המשתמש.
אם ההשלמה האוטומטית של מקומות מלווה במפה, ניתן להטות את המיקום לפי אזור התצוגה של המפה.
במצבים שבהם המשתמש לא בוחר באחת מהחיזויים של ההשלמה האוטומטית, בדרך כלל
מכיוון שאף אחת מהחיזויים האלה אינה כתובת התוצאה הרצויה, אפשר להשתמש שוב בקלט
המשתמש המקורי כדי לנסות לקבל תוצאות רלוונטיות יותר:
אם אתם מצפים מהמשתמש להזין רק פרטי כתובת, צריך להשתמש שוב בקלט המקורי של המשתמש
בקריאה ל-Geocoding API.
אם אתם מצפים מהמשתמש להזין שאילתות לגבי מקום ספציפי לפי שם או כתובת,
יש להשתמש בבקשה לחיפוש מקום.
אם התוצאות צפויות להתקבל רק באזור ספציפי, משתמשים
בהטיה לפי מיקום.
תרחישים נוספים שבהם מומלץ להשתמש ב-Geocoding API כוללים:
משתמשים המזינים כתובות של תת-דומיינים במדינות שבהן התמיכה בהשלמה האוטומטית של המקום בכתובות משנה אינה מלאה. למשל, צ'כיה, אסטוניה וליטא. לדוגמה, הכתובת בצ'כית 'Stroupežnického 3191/17, Praha' מניבה חיזוי חלקי בהשלמה האוטומטית של Place.
משתמשים שמזינים כתובות עם קידומות של קטעי כביש כמו "23-30 29th St, Queens"
בתל אביב או " 47-380 Kamehameha Hwy, Kaneohe" באי קאוואי בהוואי.
