שכבות-על של קרקע הן שכבות-על לתמונות שמקושרות לקואורדינטות של קו רוחב/אורך, ולכן הן זזות כשגוררים או משנים את מרחק התצוגה של המפה.
דוגמאות קוד
מאגר ApiDemos ב-GitHub כולל דוגמה שמדגימה שכבות-על של קרקע:
- GroundroundDemoActivity – Java: תכונות של שכבת-על קרקע ומאזינים ב-Java
- GroundroundDemoActivity – Kotlin: תכונות של שכבות-על ומאזינים ב-Kotlin
מבוא
שכבת-על של קרקע היא תמונה שקבועה במפה. שלא כמו סמנים, שכבות-על של פני הקרקע ממוקמות על פני השטח של כדור הארץ ולא על המסך, כך שסיבוב, הטיה או שינוי מרחק התצוגה של המפה ישנו את כיוון התמונה. שכבות-על של קרקע הן שימושיות כשרוצים לתקן תמונה יחידה באזור אחד במפה. אם רוצים להוסיף תמונות נרחבות שמכסות חלק גדול מהמפה, כדאי להשתמש בשכבה מעל קטעי המפה.
הוספת שכבת-על
כדי להוסיף GroundOverlay
, יוצרים אובייקט GroundOverlayOptions
שמגדיר גם תמונה וגם מיקום. אפשר לציין הגדרות נוספות שישפיעו על מיקום התמונה במפה. אחרי שמגדירים את האפשרויות הנדרשות, מעבירים את האובייקט ל-method GoogleMap.addGroundOverlay()
כדי להוסיף את התמונה למפה. ה-method 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);
הסרה של שכבת-על
אפשר להסיר שכבת-על של קרקע באמצעות method GroundOverlay.remove()
.
Kotlin
imageOverlay?.remove()
Java
imageOverlay.remove();
שינוי של שכבת-על
אפשר לשנות את התמונה של שכבת-העל של הקרקע אחרי שמוסיפים אותה למפה באמצעות method 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-index של שכבת-העל.
טיפול באירועים של שכבת-על של קרקע
כברירת מחדל, לא ניתן ללחוץ על שכבות-על של קרקע. אפשר להפעיל ולהשבית את הקליקביליות באמצעות קריאה ל-GroundOverlay.setClickable(boolean)
.
משתמשים ב-OnGroundOverlayClickListener
כדי להאזין לאירועים לוחצים בשכבת-על של קרקע שאפשר ללחוץ עליה. כדי להגדיר את ה-listener הזה במפה, צריך לבצע קריאה אל GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener)
.
כשמשתמש ילחץ על שכבת-על של קרקע, תקבלו קריאה חוזרת (callback) מסוג onGroundOverlayClick(GroundOverlay)
.