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

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

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

דוגמאות קוד

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

• GroundOverlayDemoActivity – Java: תכונות ומאזינים של שכבת-על קרקע ב-Java
• GroundOverlayDemoActivity – 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 קיים.

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

// 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 של שכבת-העל.

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

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

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

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