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

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

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

דוגמאות קוד

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

מבוא

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

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

כדי להוסיף 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 קיים.

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

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

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

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