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

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

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

דוגמאות קוד

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

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

מבוא

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

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

כדי להוסיף GroundOverlay, יוצרים אובייקט GroundOverlayOptions שמגדיר גם תמונה וגם מיקום. אפשר גם לציין הגדרות נוספות שישפיעו על מיקום התמונה במפה. אחרי שמגדירים את האפשרויות הנדרשות, מעבירים את האובייקט לשיטה 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)
imageOverlay?.let {
    val isClickable = it.isClickable
    val isVisible = it.isVisible
    val bearing = it.bearing
    val transparency = it.transparency
    val zIndex = it.zIndex
    val position = it.position
    val width = it.width
    val height = it.height
}

      

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

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