הודעת אבטחה: נודע לנו על בעיית אבטחה שעשויה להשפיע על אתרים שמשתמשים בספריות ספציפיות של צד שלישי (כולל polyfill.io). בעיה זו עלולה לפעמים להפנות מבקרים אל מחוץ לאתר המיועד ללא ידיעתו או אישור של בעלי האתר. רבות מדוגמאות ה-JavaScript שלנו כללו בעבר הצהרה של סקריפט polyfill.io. הסרנו את הדוגמאות האלה מהדוגמאות. אם השתמשת בדוגמאות JavaScript שלנו שמכילות את ההצהרה הזו, מומלץ להסיר את ההצהרה.
דף זה מתאר את הספרייה בצד הלקוח שזמינה עם
של Maps JavaScript API. אם רוצים לעבוד עם
בשירות האינטרנט של Places API בשרת שלכם, קראו את
לקוח Node.js לשירותי מפות Google. הדף ב-
מציג גם את לקוח Java,
לקוח Python ולקוח Go לשירותי מפות Google.
מבוא
השלמה אוטומטית היא תכונה של ספריית 'מקומות'
API של מפות Google ל-JavaScript. אפשר להשתמש בהשלמה האוטומטית כדי לתת
מציג את התנהגות החיפוש מסוג 'חיפוש קדימה' בשדה החיפוש במפות Google.
שירות ההשלמה האוטומטית יכול להתאים למילים שלמות ולמחרוזות משנה,
שמות של מקומות, כתובות ועוד
קודים. לכן האפליקציות יכולות לשלוח שאילתות בזמן שהמשתמש מקליד,
לספק חיזויים לגבי מקומות בזמן אמת. כפי שהוגדר על ידי Places API,
'מקום' יכולה להיות מוסד, מיקום גיאוגרפי או
נקודת עניין.
תחילת העבודה
לפני השימוש בספריית 'מקומות' ב-API של JavaScript של מפות Google, יש לוודא תחילה
ש-Places API מופעל במסוף Google Cloud,
שהגדרתם עבור ממשק ה-API של JavaScript של מפות Google.
לוחצים על הלחצן Select a project, ובוחרים את הפרויקט שהגדרתם.
של Maps JavaScript API ולוחצים על Open.
ברשימת ממשקי ה-API במרכז הבקרה, מחפשים
Places API.
אם ה-API מופיע ברשימה, אז לא צריך לבצע פעולה נוספת. אם ה-API לא מופיע ברשימה,
להפעיל אותו:
בחלק העליון של הדף, בוחרים באפשרות ENABLE API כדי להציג את
ספרייה. לחלופין, בתפריט שבצד שמאל,
בוחרים באפשרות ספרייה.
מחפשים את Places API ובוחרים אותו מתוך
רשימת התוצאות.
בוחרים באפשרות הפעלה. כשהתהליך מסתיים,
Places API מופיע ברשימת ממשקי ה-API
מרכז השליטה.
הספרייה בטעינה
שירות 'מקומות' הוא ספרייה בפני עצמה, הנפרדת מהספרייה הראשית
קוד JavaScript של Maps API. כדי להשתמש בפונקציונליות שכלולה
בספרייה הזו, קודם צריך לטעון אותה באמצעות libraries
בכתובת ה-URL של אתחול ה-API של מפות Google:
ב-API יש שני סוגים של ווידג'טים של השלמה אוטומטית, שניתן להוסיף באמצעות
המחלקות Autocomplete ו-SearchBox בהתאמה.
בנוסף, אפשר להשתמש במחלקה AutocompleteService כדי לאחזר
להשלמה אוטומטית של תוצאות באופן פרוגרמטי (עיינו בחומר העזר בנושא JavaScript API של מפות Google:
CompleteService 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() כדי להגביל
חיזויים לסוגים מסוימים של מקומות. האילוץ הזה מציין סוג או אוסף של טיפוסים,
כפי שמפורט בקטע סוגי מקומות.
אם לא מגדירים אילוץ, מוחזרים כל הסוגים.
כדי לחשב את הערך של האפשרות types או של הערך שמועבר אל setTypes(), צריך:
יכול לציין אחת מהאפשרויות הבאות:
כברירת מחדל, כשמשתמש בוחר מקום, ההשלמה האוטומטית מחזירה את כל
שדות הנתונים הזמינים עבור המקום שנבחר, ותחויב בהתאם.
שימוש ב-Autocomplete.setFields()
כדי לציין אילו שדות של נתוני מקום יוחזרו. מידע נוסף על
PlaceResult, כולל רשימה של שדות של נתוני מקומות
שאתם יכולים לבקש. כדי להימנע מתשלום על נתונים שאתם לא צריכים, חשוב להשתמש ב-Autocomplete.setFields() כדי לציין
רק את נתוני המקום שבהם תשתמשו.
המאפיין name מכיל את הפונקציה
description מהחיזויים להשלמה אוטומטית של מקומות. אפשר לקרוא מידע נוסף על
description ב-
מקומות
מסמכי תיעוד בנושא השלמה אוטומטית.
בטופסי כתובת מומלץ להשתמש בפורמט מובנה של הכתובת. שפת תרגום
החזרת הכתובת המובנית למקום שנבחר, להתקשרות אל
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 משלכם, וצריך לבצע את ההתאמה לשוק המקומי.
באפליקציה שלכם. לקבלת מידע על האופן שבו מפות Google
JavaScript API בוחר את השפה לשימוש. יש לקרוא את המסמכים ב-
התאמה לשוק המקומי.
SearchBox מאפשר למשתמשים לבצע מיקום גיאוגרפי מבוסס-טקסט
חיפוש, למשל 'פיצה בתל אביב' או 'חנויות נעליים ליד רחוב רובסון'.
אפשר לצרף את SearchBox לשדה טקסט וכמו
טקסט מוזן, השירות יחזיר חיזויים
רשימה נפתחת של אפשרויות.
SearchBox מספק רשימה מורחבת של תחזיות,
יכול לכלול מקומות (כפי שמוגדר ב-Places API) וגם הצעות לחיפוש
תנאים. לדוגמה, אם המשתמש מזין 'פיצה במצב חדש', רשימת הבחירה עשויה
כוללים את הביטוי 'פיצה בתל אביב, ישראל' וגם את השמות של
מסעדות פיצה. כשמשתמש בוחר מקום מהרשימה,
מידע על המקום הזה מוחזר לאובייקט SearchBox, ויכול להיות
האפליקציה שלך אוחזרה.
ה-constructor של SearchBox מקבל שני ארגומנטים:
רכיב input HTML מסוג text. הדבר
שדה הקלט שאחריו השירות של SearchBox יעקוב
מצרפים את התוצאות אליה.
ארגומנט options, שיכול להכיל את הפונקציה
מאפיין bounds:
bounds הוא google.maps.LatLngBounds
שמציין את האזור שבו יש לחפש מקומות. התוצאות
מוטים כלפי מקומות שנכללים, אך לא מוגבלים אליהם
את הגבולות האלה.
הקוד הבא משתמש בפרמטר bounds כדי להטות את התוצאות
למקומות בתוך אזור גיאוגרפי מסוים, שצוין באמצעות
קואורדינטות של קו אורך/רוחב.
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.
// 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);
});
אחזור פרוגרמטי של חיזויים של שירות ההשלמה האוטומטית של מקומות
כדי לאחזר חיזויים באופן פרוגרמטי, משתמשים ברכיב
AutocompleteServiceAutocompleteService
לא מוסיפה פקדים בממשק המשתמש. במקום זאת, היא מחזירה מערך של חיזוי
אובייקטים, שכל אחד מהם מכיל את הטקסט של החיזוי, מידע על הפניה
ופרטים על האופן שבו התוצאה תואמת לקלט של המשתמש.
האפשרות הזו שימושית אם אתם רוצים יותר שליטה בממשק המשתמש
מוצע על ידי Autocomplete, SearchBox
שתוארו למעלה.
הקוד AutocompleteService חושף את השיטות הבאות:
הפונקציה getPlacePredictions() מחזירה חיזויים לגבי מקום.
הערה: 'מקום' יכול להיות מוסד, מיקום גיאוגרפי,
של נקודת עניין, כפי שמוגדר ב-Places API.
הפונקציה getQueryPredictions() מחזירה רשימה מורחבת של
חיזויים, שיכולים לכלול מקומות (כפי שהוגדר על ידי Places API)
וגם הצעות למונחי חיפוש. לדוגמה, אם המשתמש
מזין 'פיצה בחדש', רשימת הבחירות עשויה לכלול את הביטוי
"פיצה בתל אביב, ישראל" וגם שמות של מסעדות פיצות שונות.
שתי ה-methods שלמעלה מחזירות מערך של
חיזוי
אובייקטים בצורה הבאה:
description הוא החיזוי התואם.
distance_meters הוא המרחק במטרים מהמקום
AutocompletionRequest.origin שצוין.
matched_substrings מכיל קבוצה של מחרוזות משנה
שמתאים לרכיבים בקלט של המשתמש. האפשרות הזאת שימושית במקרים
באמצעות הדגשת מחרוזות המשנה האלה באפליקציה. במקרים רבים,
השאילתה תופיע כמחרוזת משנה של שדה התיאור.
length הוא האורך של מחרוזת המשנה.
offset הוא היסט התווים, שנמדד
תחילת מחרוזת התיאור, שבה מחרוזת המשנה שתואמת
מופיעה.
place_id הוא מזהה טקסטואלי שמזהה באופן ייחודי
מקום מסוים. כדי לאחזר מידע על המקום, צריך להעביר את המזהה הזה
השדה placeId של
פרטי מקום
בקשה.
אזכור מקום
עם מזהה מקום.
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 לווידג'טים של השלמה אוטומטית וווידג'טים של SearchBox
רמת 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:
משתמשים המזינים כתובות של תת-דומיינים במדינות שבהן יש תמיכה בהשלמה אוטומטית של Place:
חסרות כתובות משנה ספציפיות, למשל ליטא, אסטוניה וצ'כיה. לדוגמה,
הכתובת בצ'כית: "Stroupežnického 3191/17, Praha" מניב חיזוי חלקי ב-Place
השלמה אוטומטית.
משתמשים שמזינים כתובות עם קידומות של קטעי כביש כמו " 23-30 29th St, Queens" באזור
New York City או "47-380 Kamehameha Hwy, Kaneohe" באי קאואי בהוואי.
