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

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

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

דוגמאות קוד

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

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

מבוא

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

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

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

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

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