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

בחירת פלטפורמה: Android iOS JavaScript

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

דוגמאות קוד

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

מבוא

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

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

כדי להוסיף GroundOverlay, יוצרים אובייקט GroundOverlayOptions שמגדיר גם תמונה וגם מיקום. אפשר גם לציין הגדרות נוספות שישפיעו על מיקום התמונה במפה. אחרי שמגדירים את האפשרויות הנדרשות, מעבירים את האובייקט ל-method‏ GoogleMap.addGroundOverlay() כדי להוסיף את התמונה למפה. ה-method‏ 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 קיים.

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

לפני שמוסיפים שכבת-על של קרקע למפה, צריך לציין את המיקום שלה.

שימוש במיקום כדי להציב תמונה

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