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

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

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

דוגמאות קוד

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

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

מבוא

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

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

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

      

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

אפשר להסיר שכבת-על של קרקע באמצעות 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 עבור בשכבת-על.

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

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

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

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