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

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

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

דוגמאות קוד

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

• GroundLayerDemoActivity – Java: תכונות ושכבות-על של שכבת-על ב-Java
• GroundLayerDemoActivity – 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)

      

שימוש בתמונה מסוג LatLngBounds כדי למקם תמונה

צריך לספק 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). בכל פעם שמשתמש לוחץ על שכבת-על של קרקע, מתקבל התקשרות חוזרת onGroundOverlayClick(GroundOverlay).

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