מבוא
השלמה אוטומטית היא תכונה של ספריית 'מקומות' API של מפות Google ל-JavaScript. אפשר להשתמש בהשלמה האוטומטית כדי לתת מציג את התנהגות החיפוש מסוג 'חיפוש קדימה' בשדה החיפוש במפות Google. שירות ההשלמה האוטומטית יכול להתאים למילים שלמות ולמחרוזות משנה, שמות של מקומות, כתובות ועוד קודים. לכן האפליקציות יכולות לשלוח שאילתות בזמן שהמשתמש מקליד, לספק חיזויים לגבי מקומות בזמן אמת. כפי שהוגדר על ידי Places API, 'מקום' יכולה להיות מוסד, מיקום גיאוגרפי או נקודת עניין.
תחילת העבודה
לפני השימוש בספריית 'מקומות' ב-API של JavaScript של מפות Google, יש לוודא תחילה ש-Places API מופעל במסוף Google Cloud, שהגדרתם עבור ממשק ה-API של JavaScript של מפות Google.
כדי להציג את רשימת ממשקי ה-API המופעלים:
- נכנסים אל מסוף Google Cloud.
- לוחצים על הלחצן 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:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
סקירה כללית של הספריות למידע נוסף.
סיכום הכיתות
ב-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
. זהו השדה להזנת הקלט שההשלמה האוטומטית יעקוב אחרי התוצאות שלו ויצרף אותן אליו. - אופציונלי
ארגומנט
AutocompleteOptions
, שיכול מכיל את המאפיינים הבאים:- מערך נתונים מסוג
fields
שייכלל התשובהPlace Details
עבור הבחירה ב-PlaceResult
שהמשתמש בחר. אם לא מוגדר, או אם['ALL']
מועבר, כל השדות הזמינים מוחזרים חויב עבור (לא מומלץ לפריסות בסביבת ייצור). לרשימת השדות:PlaceResult
. - מערך של
types
מציין סוג מפורש או אוסף סוגים, כפי שמפורט בסוגים נתמכים. אם לא תציינו סוג, כל הסוגים הוחזרו. bounds
הוא אובייקטgoogle.maps.LatLngBounds
שמציין האזור שבו המערכת מחפשת מקומות. התוצאות מוטות כלפי, אך לא מוגבלות ל: מקומות שנמצאים בגבולות האלה.strictBounds
הואboolean
ציון אם ה-API חייב להחזיר רק את המקומות שנמצאים אך ורק בתוך האזור שהוגדר לפי הערךbounds
הנתון. ה-API לא מחזיר תוצאות מחוץ לאזור הזה, גם אם תואמים לקלט של המשתמש.- אפשר להשתמש בתוסף
componentRestrictions
כדי להגביל את התוצאות ל- קבוצות ספציפיות. נכון לעכשיו, אפשר לסנן לפיcomponentRestrictions
כדי לסנן לפי 5 מדינות. יש להעביר מדינות בפורמט של שני תווים, בפורמט ISO 3166-1 Alpha-2 יש להעביר כמה מדינות כרשימה של קודי מדינות.הערה: אם אתם מקבלים תוצאות בלתי צפויות עם קוד מדינה, שבהם אתם משתמשים בקוד שכולל את המדינות, טריטוריות תלויות תחומי עניין גיאוגרפיים שבחרת. מידע על הקוד זמין בכתובת ויקיפדיה: רשימת ISO קודי מדינות של 3166 או גלישה באינטרנט לפי תקן ISO פלטפורמה.
- אפשר להשתמש באפליקציה
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);
JavaScript
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"); 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
קיים.
autocomplete.setFields(["place_id", "geometry", "name"]);
הגדירו הטיות וגבולות של אזור חיפוש השלמה אוטומטית
ניתן להטות את תוצאות ההשלמה האוטומטית כך שתינתן עדיפות לערך משוער מיקום או אזור, בדרכים הבאות:
- מגדירים את גבולות היצירה של האובייקט
Autocomplete
. - שינוי הגבולות ב
Autocomplete
קיים. - מגדירים את הגבולות לאזור התצוגה של המפה.
- מגבילים את החיפוש לגבולות.
- להגביל את החיפוש למדינה ספציפית.
הדוגמה הקודמת ממחישה את גבולות ההגדרות בזמן היצירה. הדוגמאות הבאות ממחישות את הטכניקות האחרות של הטייה.
שינוי הגבולות של השלמה אוטומטית קיימת
התקשרות אל setBounds()
כדי לשנות את אזור החיפוש בחשבון קיים
Autocomplete
לגבולות מלבניים.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
מגדירים את הגבולות לאזור התצוגה של המפה
יש להשתמש ב-bindTo()
כדי להטות את התוצאות לאזור התצוגה של המפה,
גם כשאזור התצוגה משתנה.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
יש להשתמש ב-unbind()
כדי לבטל את הקישור בין החיזויים של ההשלמה האוטומטית לבין אזור התצוגה של המפה.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
הגבלת החיפוש לגבולות הנוכחיים
צריך להגדיר את האפשרות strictBounds
כדי להגביל את התוצאות לגבולות הנוכחיים, על סמך אזור התצוגה של המפה או גבולות מלבניים.
autocomplete.setOptions({ strictBounds: true });
הגבלת החיזויים למדינה ספציפית
אפשר להשתמש באפשרות componentRestrictions
או להתקשר למספר setComponentRestrictions()
כדי להגביל
להשלים אוטומטית את החיפוש לקבוצה ספציפית של עד חמש מדינות.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
הגבלה של סוגי מקומות
אפשר להשתמש באפשרות types
או להתקשר למספר setTypes()
כדי להגביל
חיזויים לסוגים מסוימים של מקומות. האילוץ הזה מציין סוג או אוסף של טיפוסים,
כפי שמפורט בקטע סוגי מקומות.
אם לא מגדירים אילוץ, מוחזרים כל הסוגים.
כדי לחשב את הערך של האפשרות types
או של הערך שמועבר אל setTypes()
, צריך:
יכול לציין אחת מהאפשרויות הבאות:
מערך שמכיל עד חמישה ערכים מטבלה 1 או טבלה 2 מאת סוגי מקומות. לדוגמה:
types: ['hospital', 'pharmacy', 'bakery', 'country']
או:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- כל מסנן אחד בטבלה 3 מתוך סוגי מקומות. אפשר לציין רק ערך אחד מטבלה 3.
הבקשה תידחה אם:
- ציינת יותר מחמישה סוגים.
- יש לציין סוגים לא מזוהים.
- משלבים את כל הסוגים מטבלה 1 או טבלה 2 עם לסנן מטבלה 3.
ההדגמה של ההשלמה האוטומטית של המקומות מדגימה את ההבדלים בחיזויים בין סוגי מקומות שונים.
קבלת מידע על המקום
כשמשתמש בוחר מקום מהחיזויים שמצורפים להשלמה האוטומטית
שדה טקסט, השירות מפעיל אירוע place_changed
. כדי לקבל את המקום
פרטים:
- יוצרים הגורם המטפל באירוע עבור האירוע
place_changed
וקוראים ל-addListener()
על האובייקטAutocomplete
כדי להוסיף את ה-handler. - התקשרות אל
Autocomplete.getPlace()
באובייקטAutocomplete
, כדי לאחזרPlaceResult
לאובייקט, שאפשר להשתמש בו כדי לקבל מידע נוסף על במקום.
כברירת מחדל, כשמשתמש בוחר מקום, ההשלמה האוטומטית מחזירה את כל
שדות הנתונים הזמינים עבור המקום שנבחר, ותחויב בהתאם.
שימוש ב-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(); }
JavaScript
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 רגיל. כדי לשנות את הטקסט, מגדירים את
המאפיין placeholder
ברכיב input
:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
הערה: הטקסט של ה-placeholder שמוגדר כברירת מחדל מותאם לשוק המקומי באופן אוטומטי. אם תצטרכו להגדיר ערך placeholder משלכם, וצריך לבצע את ההתאמה לשוק המקומי. באפליקציה שלכם. לקבלת מידע על האופן שבו מפות Google JavaScript API בוחר את השפה לשימוש. יש לקרוא את המסמכים ב- התאמה לשוק המקומי.
ראה עיצוב הווידג'טים של השלמה אוטומטית ו-SearchBox כדי להתאים אישית את מראה הווידג'ט.
הוספת ווידג'ט של SearchBox
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
.
למידע נוסף על האובייקט 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); });
JavaScript
// 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); });
ראה עיצוב הווידג'טים של השלמה אוטומטית ו-SearchBox כדי להתאים אישית את מראה הווידג'ט.
אחזור פרוגרמטי של חיזויים של שירות ההשלמה האוטומטית של מקומות
כדי לאחזר חיזויים באופן פרוגרמטי, משתמשים ברכיב
AutocompleteService
AutocompleteService
לא מוסיפה פקדים בממשק המשתמש. במקום זאת, היא מחזירה מערך של חיזוי
אובייקטים, שכל אחד מהם מכיל את הטקסט של החיזוי, מידע על הפניה
ופרטים על האופן שבו התוצאה תואמת לקלט של המשתמש.
האפשרות הזו שימושית אם אתם רוצים יותר שליטה בממשק המשתמש
מוצע על ידי 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;
JavaScript
// 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;
CSS
HTML
<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);
חשוב להעביר אסימון סשן ייחודי לכל סשן חדש. שימוש באותה עבור יותר מסשן אחד, התוצאה תהיה חיוב על כל בקשה בנפרד.
עיצוב הווידג'טים של השלמה אוטומטית ו-SearchBox
כברירת מחדל, רכיבי ממשק המשתמש מסופקים על ידי Autocomplete
ו-
התבניות SearchBox
מעוצבות בהתאם למפת Google. ייתכן שתרצו
כדי להתאים את הסגנון לאתר שלכם. מחלקות ה-CSS הבאות הן
זמינים. כל הכיתות ברשימה למטה רלוונטיות
Autocomplete
והווידג'טים של SearchBox
.
![איור גרפי של מחלקות ה-CSS להשלמה אוטומטית
ווידג'טים של SearchBox](https://developers.google.cn/static/maps/documentation/javascript/images/place-autocomplete-css-diagram.png?authuser=0000&hl=he)
רמת 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 לקבלת תמיכה ומשוב שקשור לספרייה.
אפשר לנסות רכיבי אינטרנט. אפשר להשתמש ב רכיב האינטרנט של הכלי לבחירת מיקום כדי להפעיל קלט טקסט שמאפשר למשתמשי קצה לחפש כתובת או מקום ספציפיים באמצעות השלמה אוטומטית.
![קובץ GIF עם תיבת חיפוש. המשתמש מתחיל להקליד כתובת כקלט, ותפריט נפתח עם אפשרויות קשורות
יופיעו כתובות. המשתמש לוחץ על כתובת בתפריט הנפתח ותיבת החיפוש מתמלאת
בשאר הכתובת.](https://developers.google.cn/static/maps/documentation/javascript/images/place-picker.gif?authuser=0000&hl=he)
אופטימיזציה להשלמה אוטומטית של מקומות
בקטע הזה מתוארות שיטות מומלצות שיעזרו לכם להפיק את המרב שירות השלמה אוטומטית למקומות.
הנה כמה הנחיות כלליות:
- הדרך המהירה ביותר לפתח ממשק משתמש תקין היא להשתמש ווידג'ט ההשלמה האוטומטית של Maps JavaScript API, Places SDK ל-Android ווידג'ט השלמה אוטומטית, או Places SDK ל-iOS שליטה בממשק המשתמש של השלמה אוטומטית
- לפתח הבנה של השלמה אוטומטית חיונית של מקום שדות נתונים מההתחלה.
- השדות 'הטיית מיקום' ו'הגבלת מיקום' הם אופציונליים, אבל הם יכולים משפיעים באופן משמעותי על הביצועים של ההשלמה האוטומטית.
- שימוש בטיפול בשגיאות כדי לוודא שאיכות האפליקציה משתפרת אם ה-API מחזיר שגיאה.
- חשוב לוודא שהאפליקציה מטפלת כשלא צריך לבחור אפשרות ומציעה למשתמשים אפשרות כדי להמשיך.
שיטות מומלצות לאופטימיזציה של עלויות
אופטימיזציה בסיסית של עלויות
כדי לייעל את עלות השימוש בהשלמה אוטומטית של מקומות השירות, שימוש במסכות של שדות בווידג'טים של פרטי מקום והשלמה אוטומטית של מקומות כדי להחזיר רק את למקם שדות נתונים שדרושים לכם.
אופטימיזציה מתקדמת של עלויות
כדאי לשקול הטמעה פרוגרמטית של השלמה אוטומטית של מקומות כדי לגשת לתמחור לפי בקשה ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום פרטי המקום. תמחור לפי בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לפי פעילות (מבוסס-סשן) אם שני התנאים הבאים מתקיימים:
- אם אתם צריכים רק את קו הרוחב/קו האורך או הכתובת של המקום שהמשתמש בחר, Geocoding API מספק את המידע הזה בפחות מקריאה של פרטי מקום.
- אם משתמשים בוחרים חיזוי להשלמה אוטומטית בתוך ארבע בקשות או פחות חיזויים להשלמה אוטומטית, תמחור לפי בקשה עשוי להיות משתלם יותר מהתמחור לכל סשן.
האם באפליקציה נדרשים פרטים כלשהם מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?
כן, אני רוצה פרטים נוספים
שימוש בהשלמה אוטומטית של מקומות עם פרטי מקום.
מאחר שהאפליקציה שלך דורשת פרטי מקום כמו שם המקום, סטטוס העסק או שעות הפתיחה, ההטמעה של ההשלמה האוטומטית של המקום צריכה להשתמש באסימון סשן (באופן פרוגרמטי או מובנה בווידג'טים של JavaScript, Android או iOS) בעלות כוללת של $0.017 לכל סשן, בתוספת מק"טים רלוונטיים של נתוני מקומות בהתאם לשדות הנתונים של המקומות שביקשת.
הטמעה של ווידג'ט
ניהול הסשנים מובנה אוטומטית בווידג'טים JavaScript, Android או iOS. המידע הזה כולל את הבקשות להשלמה אוטומטית של מקומות וגם את הבקשה 'פרטי מקום' בחיזוי שנבחר. חשוב לציין את הפרמטר fields
כדי לוודא שמבקשים רק את
שדות נתונים של מקומות שדרושים לכם.
הטמעה פרוגרמטית
משתמשים באסימון סשן בבקשות להשלמה אוטומטית של מקומות. כשמבקשים פרטי מקום לגבי החיזוי שנבחר, צריך לכלול את הפרמטרים הבאים:
- מזהה המקום מתגובת ההשלמה האוטומטית של מקום
- אסימון הסשן שבו נעשה שימוש בבקשת ההשלמה האוטומטית של המקום
- הפרמטר
fields
שמציין את שדות של נתוני מקומות שדרושים לכם
לא, נדרשת רק כתובת ומיקום
Geocoding API יכול להיות אפשרות חסכונית יותר מאשר פרטי מקום עבור האפליקציה שלכם, בהתאם לביצועים של השימוש שלכם בהשלמה אוטומטית של Place. יעילות ההשלמה האוטומטית של כל אפליקציה משתנה בהתאם לתוכן שהמשתמשים מזינים, למיקום שבו נעשה שימוש באפליקציה וליישום של שיטות מומלצות לאופטימיזציה של הביצועים.
כדי לענות על השאלה הבאה, יש לנתח כמה תווים משתמש מקליד בממוצע לפני שבוחרים חיזוי להשלמה אוטומטית של מקומות באפליקציה.
האם המשתמשים שלך בוחרים חיזוי להשלמה אוטומטית של מקומות בארבע בקשות או פחות, בממוצע?
כן
הטמעה של השלמה אוטומטית במקום באופן פרוגרמטי ללא אסימוני סשן וקריאה ל-Geocoding API בחיזוי המקום שנבחר.
Geocoding API מספק כתובות וקואורדינטות של קווי אורך ורוחב בסכום של $0.005 לכל בקשה. ניתן לבצע ארבע בקשות של השלמה אוטומטית במקום – לכל בקשה בעלות של 0.01,132$, כך שהעלות הכוללת של ארבע בקשות בנוסף לקריאת Geocoding API לגבי חיזוי המקום שנבחר תהיה 0.01632$. מחיר זה נמוך מהמחיר להשלמה אוטומטית לכל סשן בסך 0.017 $לכל סשן.1
כדאי להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את החיזוי שהם מחפשים, תוך פחות תווים.
לא
שימוש בהשלמה אוטומטית של מקומות עם פרטי מקום.
מאחר שהמספר הממוצע של הבקשות שאתה מצפה לשלוח לפני שמשתמש בוחר בחיזוי להשלמה אוטומטית של מקומות עולה על המחיר של לכל סשן, ההטמעה של ההשלמה האוטומטית של מקומות צריכה להשתמש באסימון סשן גם לבקשות להשלמה אוטומטית של מקומות וגם לבקשת פרטי המקום המשויכת, בעלות כוללת של 0.017 $לכל סשן.1
הטמעה של ווידג'ט
ניהול הסשנים מובנה אוטומטית בווידג'טים JavaScript, Android או iOS. המידע הזה כולל את הבקשות להשלמה אוטומטית של מקומות וגם את הבקשה 'פרטי מקום' בחיזוי שנבחר. חשוב לציין את הפרמטר fields
כדי לוודא שאתם מבקשים רק שדות של נתונים בסיסיים.
הטמעה פרוגרמטית
משתמשים באסימון סשן בבקשות להשלמה אוטומטית של מקומות. כשמבקשים פרטי מקום לגבי החיזוי שנבחר, צריך לכלול את הפרמטרים הבאים:
- מזהה המקום מתגובת ההשלמה האוטומטית של מקום
- אסימון הסשן שבו נעשה שימוש בבקשת ההשלמה האוטומטית של המקום
- הפרמטר
fields
שמציין שדות של נתונים בסיסיים, כמו כתובת וגיאומטריה
כדאי לעכב בקשות להשלמה אוטומטית של מקומות
תוכלו להשתמש באסטרטגיות כמו דחייה של בקשה להשלמה אוטומטית של מקום עד שהמשתמש יקליד בשלושת או ארבעת התווים הראשונים, כך שהאפליקציה תשלח פחות בקשות. לדוגמה, כששולחים בקשות להשלמה אוטומטית של מקומות לכל תו אחרי שהמשתמש הקליד את התו השלישי, המשמעות היא שאם המשתמש מקליד את התו השלישי ולאחר מכן בוחר חיזוי שעבורו שלחתם בקשת Geocoding API, העלות הכוללת תהיה $0.01632 (4 * $0.00283 בקשת השלמה אוטומטית לכל בקשה + 0.005 $קידוד גיאוגרפי).1
אם בקשות מעכבות יכולות לגרום לבקשה הפרוגרמטית הממוצעת שלכם נמוכה מארבע, אפשר לפעול לפי ההנחיות להטמעת השלמה אוטומטית של מיקום בעזרת Geocoding API. חשוב לשים לב שבקשות מעכבות יכולות להיחשב כזמן אחזור, שהמשתמש יצפה לראות חיזויים בכל מקש חדש.
כדאי להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את החיזוי שהם מחפשים, בפחות תווים.
-
העלויות המפורטות כאן הן בדולר ארה"ב. מידע על התמחור המלא זמין בדף חיוב בפלטפורמה של מפות Google.
שיטות מומלצות לשיפור הביצועים
בהנחיות הבאות מתוארות דרכים לאופטימיזציה של ביצועי ההשלמה האוטומטית של המקום:
- הוספת הגבלות לפי מדינה, הטיה לפי מיקום, וגם (להטמעות פרוגרמטיות) של העדפת השפה להשלמה האוטומטית של המקום יישום בפועל. לא נדרשת העדפת שפה עם ווידג'טים כי הם בוחרים העדפות שפה מהדפדפן או מהנייד של המשתמש.
- אם ההשלמה האוטומטית של מקומות מלווה במפה, ניתן להטות את המיקום לפי אזור התצוגה של המפה.
- במצבים שבהם המשתמש לא בוחר באחת מהחיזויים של ההשלמה האוטומטית, בדרך כלל
מכיוון שאף אחת מהחיזויים האלה אינה כתובת התוצאה הרצויה, אפשר להשתמש שוב בגרסה המקורית
קלט של משתמשים בניסיון לקבל תוצאות רלוונטיות יותר:
- אם אתם מצפים מהמשתמש להזין רק פרטי כתובת, השתמשו שוב בקלט המקורי של המשתמש קריאה ל-Geocoding API.
- אם אתם מצפים מהמשתמש להזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, להשתמש בבקשה לחיפוש מקום. אם התוצאות צפויות רק באזור ספציפי, משתמשים ב- הטיה לפי מיקום.
- משתמשים המזינים כתובות של תת-דומיינים במדינות שבהן יש תמיכה בהשלמה אוטומטית של Place: חסרות כתובות משנה ספציפיות, למשל ליטא, אסטוניה וצ'כיה. לדוגמה, הכתובת בצ'כית: "Stroupežnického 3191/17, Praha" מניב חיזוי חלקי ב-Place השלמה אוטומטית.
- משתמשים שמזינים כתובות עם קידומות של קטעי כביש כמו " 23-30 29th St, Queens" באזור New York City או "47-380 Kamehameha Hwy, Kaneohe" באי קאואי בהוואי.
מגבלות שימוש ומדיניות
מכסות
מידע נוסף על מכסות ותמחור זמין במאמר מאמרי עזרה על שימוש וחיוב ל-Places API.
מדיניות
השימוש בספריית המקומות, Maps JavaScript API חייב להיות בהתאם המדיניות שמתוארת ל-Places API.