שכבות-על של קרקע הן שכבות-על של תמונה הקשורות לקואורדינטות של קווי רוחב/אורך, כך שהן זזות כשגוררים או משנים את מרחק התצוגה של המפה.
דוגמאות קוד
המאגר של ApiDemos ב-GitHub כולל דוגמה שמדגימה שכבות-על של קרקע:
- GroundOverlayDemoActivity – Java: תכונות ומאזינים של שכבת-על קרקע ב-Java
- GroundOverlayDemoActivity – Kotlin: תכונות ומאזינים של שכבות-על קרקע ב-Kotlin
מבוא
שכבת-על של קרקע היא תמונה הקבועה במפה. בשונה מסמנים, שכבות-על של הקרקע ממוקמות על פני השטח של כדור הארץ ולא על המסך, ולכן סיבוב, הטיה או שינוי מרחק התצוגה של המפה ישנו את כיוון התמונה. שכבות-על של קרקע שימושיות כשרוצים לתקן תמונה יחידה באזור אחד במפה. אם רוצים להוסיף תמונות מקיפות שמכסה חלק גדול מהמפה, כדאי להשתמש בשכבת-על של אריחים.
הוספת שכבת-על
כדי להוסיף GroundOverlay
, יוצרים אובייקט GroundOverlayOptions
שמגדיר גם תמונה וגם מיקום. אפשר לציין הגדרות נוספות שישפיעו על מיקום התמונה במפה. אחרי שמגדירים את האפשרויות הנדרשות, מעבירים את האובייקט ל-method GoogleMap.addGroundOverlay()
כדי להוסיף את התמונה למפה. השיטה addGroundOverlay()
מחזירה אובייקט GroundOverlay
. עליכם לשמור הפניה לאובייקט הזה אם תרצו לשנות אותו מאוחר יותר.
שלב אחר שלב:
- יצירת אובייקט
GroundOverlayOptions
חדש - צריך לציין את התמונה בתור
BitmapDescriptor
. - אפשר להגדיר את המיקום של התמונה באחת מהשיטות הזמינות:
position(LatLng location, float width, float height)
position(LatLng location, float width)
positionFromBounds(LatLngBounds bounds)
- מגדירים כל מאפיין אופציונלי, כמו
transparency
, לפי הצורך. - התקשרות אל
GoogleMap.addGroundOverlay()
כדי להוסיף את התמונה למפה.
הדוגמה הבאה ממחישה איך להוסיף שכבת-על של קרקע לאובייקט GoogleMap
קיים.
Kotlin
val newarkLatLng = LatLng(40.714086, -74.228697) val newarkMap = GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .position(newarkLatLng, 8600f, 6500f) map.addGroundOverlay(newarkMap)
Java
LatLng newarkLatLng = new LatLng(40.714086, -74.228697); GroundOverlayOptions newarkMap = new GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .position(newarkLatLng, 8600f, 6500f); map.addGroundOverlay(newarkMap);
אם אתם רוצים לשנות או להסיר שכבת-על של קרקע אחרי שהוספתם אותה למפה, הקפידו ללחוץ לחיצה ארוכה על האובייקט GroundOverlay
. אפשר לשנות את שכבת-העל מאוחר יותר על ידי ביצוע שינויים באובייקט.
Kotlin
// Add an overlay to the map, retaining a handle to the GroundOverlay object. val imageOverlay = map.addGroundOverlay(newarkMap)
Java
// Add an overlay to the map, retaining a handle to the GroundOverlay object. GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);
הסרת שכבת-על
אפשר להסיר שכבת-על של קרקע באמצעות השיטה GroundOverlay.remove()
.
Kotlin
imageOverlay?.remove()
Java
imageOverlay.remove();
שינוי של שכבת-על
אפשר לשנות את התמונה של שכבת-העל של הקרקע אחרי שמוסיפים אותה למפה באמצעות השיטה GroundOverlay.setImage(BitmapDescriptor)
.
Kotlin
// Update the GroundOverlay with a new image of the same dimension // Update the GroundOverlay with a new image of the same dimension imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
Java
// Update the GroundOverlay with a new image of the same dimension imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));
השיטה setImage()
תחליף את התמונה הקיימת בתמונה אחרת באותם מימדים.
מיקום שכבת-על של קרקע
יש שתי דרכים לציין את המיקום של שכבת-העל של הקרקע:
- שימוש ב-
LatLng
למרכז את שכבת-העל, ומידות במטרים כדי לציין את גודל התמונה. - באמצעות
LatLngBounds
כדי לציין את הפינות הצפון-מזרחיות והדרום-מערביות של התמונה.
עליכם לציין את המיקום של שכבת-העל של הקרקע לפני שתוסיפו אותה למפה.
שימוש במיקום כדי למקם תמונה
כשמוסיפים את התמונה, צריך לציין LatLng שאליו יקבע העוגן
ואת רוחב שכבת-העל (במטרים). ברירת המחדל של anchor
היא מרכז התמונה. אפשר לציין את גובה שכבת-העל (במטרים). אם לא מציינים את הגובה של שכבת-העל, היא תחושב באופן אוטומטי כדי לשמר את הפרופורציות של התמונה.
הקוד הבא ממקמים תמונה במיקום 40.714086, -74.228697
,
ברוחב של 8.6 ק"מ ובגובה של 6.5 ק"מ. התמונה מעוגנת לפינה השמאלית התחתונה.
Kotlin
val newarkMap = GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .anchor(0f, 1f) .position(LatLng(40.714086, -74.228697), 8600f, 6500f)
Java
GroundOverlayOptions newarkMap = new GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .anchor(0, 1) .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);
שימוש ב-LatLngBounds כדי למקם תמונה
צריך לספק LatLngBounds
שמכיל את התמונה. הסימן LatLngBounds
מגדיר את הפינות הצפון-מזרחיות והדרום-מערביות של התמונה. כשהתמונה משורטטת במפה, היא תסובב בהתאם לגבולות. אם הגבולות לא תואמים ליחס הגובה-רוחב המקורי, התמונה תהיה מוטה.
הקוד שבהמשך מציב תמונה במפה, שהפינה הדרום-מערבית שלה קשורה אל 40.712216,-74.22655
והפינה הצפון-מזרחית שלה קשורה ל-40.773941, -74.12544
.
Kotlin
val newarkBounds = LatLngBounds( LatLng(40.712216, -74.22655), // South west corner LatLng(40.773941, -74.12544) // North east corner ) val newarkMap = GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .positionFromBounds(newarkBounds)
Java
LatLngBounds newarkBounds = new LatLngBounds( new LatLng(40.712216, -74.22655), // South west corner new LatLng(40.773941, -74.12544)); // North east corner GroundOverlayOptions newarkMap = new GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .positionFromBounds(newarkBounds);
שיוך נתונים לשכבת-על של קרקע
אפשר לקרוא ל-GroundOverlay.setTag()
כדי לאחסן אובייקט נתונים שרירותי עם שכבת-על של קרקע, ולאחזר את אובייקט הנתונים באמצעות GroundOverlay.getTag()
.
דוגמת הקוד הבאה מאחסנת תיאור של מחרוזת עם שכבת-על של קרקע:
Kotlin
val sydneyGroundOverlay = map.addGroundOverlay( GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge)) .position(LatLng(-33.873, 151.206), 100f) .clickable(true) ) sydneyGroundOverlay?.tag = "Sydney"
Java
GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge)) .position(new LatLng(-33.873, 151.206), 100) .clickable(true)); sydneyGroundOverlay.setTag("Sydney");
הנה כמה דוגמאות לתרחישים שבהם כדאי לאחסן ולאחזר נתונים באמצעות שכבות-על של קרקע:
- יכול להיות שהאפליקציה שלכם תטפל בשכבות-על שונות של קרקע, ואתם רוצים להתייחס אליהן באופן שונה כשהמשתמש לוחץ עליהן.
- יכול להיות שאתם מתממשקים עם מערכת שיש לה מזהי רשומות ייחודיים, שבה שכבות-העל מייצגות רשומות ספציפיות במערכת הזו.
- נתוני שכבת-העל עשויים להצביע על עדיפות לקביעת אינדקס ה-z של שכבת-העל.
טיפול באירועים של שכבת-על של קרקע
כברירת מחדל, לא ניתן ללחוץ על שכבות-על של קרקע. אפשר להפעיל ולהשבית את הקליקביליות באמצעות קריאה ל-GroundOverlay.setClickable(boolean)
.
משתמשים ב-OnGroundOverlayClickListener
כדי להאזין לאירועים מסוג קליק על שכבת-על של קרקע ניתנת ללחיצה. כדי להגדיר את ה-listener הזה במפה, צריך להתקשר אל GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener)
.
כשמשתמש ילחץ על שכבת-על של קרקע, תקבלו קריאה חוזרת בסך onGroundOverlayClick(GroundOverlay)
.