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

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

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

דוגמאות קוד

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

• GrounddataLayerDemoActivity – Java: תכונות של שכבת-על יבשתית ומאזינים ב-Java
• GroundשכבתDemoActivity – Kotlin: תכונות ומאזינים של שכבת-על יבשתית ב-Kotlin

מבוא

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

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

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

הערה: כשמוסיפים את התמונה למפה, המערכת תמיר אותה לתמונה עם צדדים שחזקים של שניים. כדי למנוע את ההמרה הזו, תוכלו להשתמש בתמונה מקורית במידות שהחזקה שלהן היא שתיים — לדוגמה, 128x512 או 1024x1024.

שלב אחר שלב:

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 קיים.

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);

      

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)

      

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

Java

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

      

Kotlin

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

      

הסרה של שכבת-על

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

Java

imageOverlay.remove();

      

Kotlin

imageOverlay?.remove()

      

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

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

Java

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

      

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

      

השיטה setImage() תחליף את התמונה הקיימת בתמונה אחרת באותן מידות.

מיקום שכבת-על של הקרקע

יש שתי דרכים לציין את המיקום של שכבת-העל קרקעית:

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

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

ממקמים תמונה באמצעות מיקום

כשמוסיפים את התמונה, מציינים את שורת ה-LatLng שאליה יחובר העוגן ואת רוחב שכבת-העל (במטרים). ברירת המחדל של anchor היא מרכז התמונה. אפשר לספק את גובה שכבת-העל (במטרים). אם לא תספקו את הגובה של שכבת-העל, הוא יחושב אוטומטית כדי לשמור על הפרופורציות של התמונה.

הקוד הבא ממקם תמונה במיקום 40.714086, -74.228697, ברוחב 8.6 ק"מ ובגובה של 6.5 ק"מ. התמונה מעוגנת לפינה השמאלית התחתונה.

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);

      

Kotlin

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

      

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

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

הקוד הבא מציב תמונה במפה כשהפינה הדרום-מערבית שלה קשורה ל-40.712216,-74.22655 והפינה הצפון-מזרחית שלה קשורה ל-40.773941, -74.12544.

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);

      

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)

      

שיוך נתונים לשכבת-על של קרקע

אפשר להפעיל את GroundOverlay.setTag() כדי לאחסן אובייקט נתונים שרירותי עם שכבת-על של קרקע, ולאחזר את אובייקט הנתונים באמצעות GroundOverlay.getTag().

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

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");

      

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"

      

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

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

טיפול באירועים של שכבת-על של הקרקע

כברירת מחדל, לא ניתן ללחוץ על שכבות-על של הקרקע. אתם יכולים להפעיל ולהשבית את הקליקביליות באמצעות קריאה ל-GroundOverlay.setClickable(boolean).

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

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