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

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

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

דוגמאות קוד

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

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

מבוא

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

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

כדי להוסיף GroundOverlay, יוצרים אובייקט GroundOverlayOptions שמגדיר גם תמונה וגם מיקום. אפשר גם לציין הגדרות נוספות שישפיעו על המיקום של התמונה במפה. אחרי שמגדירים את האפשרויות הנדרשות, מעבירים את האובייקט לשיטה GoogleMap.addGroundOverlay() כדי להוסיף את התמונה למפה. השיטה addGroundOverlay() מחזירה אובייקט GroundOverlay. אם רוצים לשנות את האובייקט מאוחר יותר, צריך לשמור את ההפניה אליו.

הערה: כשהתמונה תתווסף למפה, היא תוסב לתמונה עם צדדים שהם חזקות של שתיים. כדי למנוע את ההמרה הזו, אפשר להשתמש בתמונה מקורית עם מידות שהן כפולות של שתיים – לדוגמה, 128x512 או 1,024x1,024.

שלב אחר שלב:

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

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

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

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

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