שכבות-על של קרקע

שכבות-על של קרקע הן שכבות-על של תמונות שמקושרות לקואורדינטות של קו הרוחב/קו האורך, כך שהן זזות כשגוררים את המפה או משנים את מרחק התצוגה שלה.

דוגמאות קוד

המאגר ApiDemos ב-GitHub כולל דוגמה שממחישה שכבות-על של מידע גיאוגרפי:

• GroundOverlayDemoActivity – Java: תכונות של שכבות-על של קרקע ומאזינים ב-Java
• GroundOverlayDemoActivity – Kotlin: מאפיינים ומאזינים של שכבות-על של קרקע ב-Kotlin

מבוא

שכבת-על של קרקע היא תמונה שמקובעת במפה. בניגוד לסמנים, שכבות-על של שטח מוצגות ביחס לפני כדור הארץ ולא למסך, כך ששינוי הכיוון של המפה, הטיה שלה או שינוי הזום ישנו את הכיוון של התמונה. שכבות-על של שטח מתאימות כשרוצים להציב תמונה אחת באזור מסוים במפה. אם רוצים להוסיף תמונות נרחבות שמכסות חלק גדול מהמפה, כדאי להשתמש בשכבת-על של משבצות.

הוספת שכבת-על

כדי להוסיף GroundOverlay, יוצרים אובייקט GroundOverlayOptions שמגדיר גם תמונה וגם מיקום. אפשר גם לציין הגדרות נוספות שישפיעו על המיקום של התמונה במפה. אחרי שמגדירים את האפשרויות הנדרשות, מעבירים את האובייקט לשיטה GoogleMap.addGroundOverlay() כדי להוסיף את התמונה למפה. השיטה addGroundOverlay() מחזירה אובייקט GroundOverlay. אם רוצים לשנות את האובייקט מאוחר יותר, צריך לשמור את ההפניה אליו.

שלב אחר שלב:

1. יצירה של אובייקט GroundOverlayOptions חדש
2. מציינים את התמונה כ-BitmapDescriptor.
3. מגדירים את המיקום של התמונה באחת מהשיטות הזמינות:
   • position(LatLng location, float width, float height)
   • position(LatLng location, float width)
   • positionFromBounds(LatLngBounds bounds)
4. מגדירים את המאפיינים האופציונליים, כמו transparency, לפי הצורך.
5. אפשר להתקשר למספר GoogleMap.addGroundOverlay() כדי להוסיף את התמונה למפה.

הדוגמה הבאה מראה איך להוסיף שכבת-על של שטח לאובייקט GoogleMap קיים.

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)

      

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. תוכלו לשנות את שכבת-העל מאוחר יותר על ידי ביצוע שינויים באובייקט הזה.

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)

      

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

      

הסרת שכבת-על

אפשר להסיר שכבת-על של שטח באמצעות השיטה GroundOverlay.remove().

imageOverlay?.remove()

      

imageOverlay.remove();

      

שינוי שכבת-על

אפשר לשנות את התמונה של שכבת-העל של הקרקע אחרי שמוסיפים אותה למפה באמצעות השיטה GroundOverlay.setImage(BitmapDescriptor).

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

      

// 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 ק"מ. התמונה מעוגנת בפינה הימנית התחתונה.

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

      

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.

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)

      

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().

בקוד לדוגמה הבא מאוחסן תיאור של מחרוזת עם שכבת-על של שטח:

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay?.tag = "Sydney"

      

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 כדי להאזין לאירועי קליקים בשכבת-על של פני השטח שניתן ללחוץ עליה. כדי להגדיר את המאזין הזה במפה, צריך להפעיל את הפונקציה GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). כשמשתמש לוחץ על שכבת-על של מפה, תקבלו קריאה חוזרת מסוג onGroundOverlayClick(GroundOverlay).