שכבות-על של משבצות

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

שכבה מעל קטעי המפה, שנקראת לפעמים שכבת קטעי מפה, היא אוסף של תמונות שמוצגות מעל קטעי המפה הבסיסיים.

דוגמאות קוד

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

• TileOverlayDemoActivity - Java: תכונות של שכבה מעל קטעי המפה ב-Java
• TileCoordinateDemoActivity – Java: מערכת הקואורדינטות שמשמשת לשכבות-על של משבצות ב-Java
• TileOverlayDemoActivity – Kotlin: תכונות של שכבה מעל קטעי המפה ב-Kotlin
• ‫ TileCoordinateDemoActivity – Kotlin: מערכת הקואורדינטות שמשמשת לשכבות מעל קטעי המפה ב-Kotlin

מבוא

תג TileOverlay מגדיר קבוצה של תמונות שמוספות מעל קטעי המפה הבסיסיים.

צריך לספק את המשבצות לכל רמת זום שרוצים לתמוך בה. אם יש לכם מספיק משבצות ברמות זום שונות, אתם יכולים להוסיף לנתוני המפה של Google את כל המפה.

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

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

קואורדינטות של קטעים במפה ורמות זום

‫Google Maps API מחלק את התמונות בכל רמת זום לקבוצה של משבצות מפה מרובעות שמסודרות ברשת. כשמזיזים מפה למיקום חדש או משנים את רמת הזום שלה, Maps API קובע אילו משבצות נדרשות ומתרגם את המידע הזה לקבוצה של משבצות לאחזור.

המשבצת עם הקואורדינטות (0,0) תמיד נמצאת בפינה הצפון-מערבית של המפה, כאשר ערכי ה-X גדלים ממערב למזרח וערכי ה-Y גדלים מצפון לדרום. המשבצות נוספות לאינדקס באמצעות קואורדינטות x,y מאותה נקודת מוצא.

ברמת זום 0, כל העולם מוצג במשבצת אחת. כל רמת זום מגדילה את ההגדלה בפקטור של שתיים. לכן, ברמת זום 1, המפה תוצג כרשת של 2x2 משבצות. ברמת זום 2, הרשת היא בגודל 4x4. ברמת זום 3, הרשת היא 8x8, וכן הלאה.

לדוגמה, ברמת זום 2 כדור הארץ מחולק ל-16 משבצות. אפשר להפנות לכל משבצת באמצעות שילוב ייחודי של x, ‏ y ורמת זום:

כשיוצרים תמונות לשכבת משבצות, צריך ליצור תמונה לכל משבצת בכל רמת זום שרוצים לתמוך בה. ‫מפות Google מכוונות ל-256dp (פיקסלים בלתי תלויים במכשיר) כשמוצגים קטעי מפה. במכשירים עם רזולוציה גבוהה, מומלץ להחזיר משבצות עם DPI גבוה (‎512x512 פיקסלים). במאמרי העזרה למפתחי Android מוסבר איך לתמוך בגדלים שונים של מסכים ובצפיפויות שונות.

הערה: רמות הזום שהמצלמה תומכת בהן תלויות בגורמים שונים, והן לא קשורות לרמות הזום שהמשתתפים במסכים יתמכו בהן.

1. GoogleMap.getMaxZoomLevel() מחזירה את רמת הזום המקסימלית שזמינה במיקום הנוכחי של המצלמה. החישוב הזה מתבסס על סוג המפה שמשמשת אתכם כרגע. לדוגמה, יכול להיות שלמפת לוויין או למפת טופוגרפיה יש רמת זום מקסימלית נמוכה יותר מאשר לקטעי המפה הבסיסית.
2. GoogleMap.getMinZoomLevel() מחזירה את רמת הזום המינימלית, שהיא זהה לכל מיקום (בניגוד לרמת הזום המקסימלית), אבל יכולה להשתנות בין מכשירים וגדלים של מפות.

הוספת שכבה מעל קטעי המפה

הדרך הפשוטה והנפוצה ביותר ליצור שכבה מעל קטעי המפה היא לספק כתובת URL שמפנה לתמונה הרלוונטית של קטע המפה. ‫ UrlTileProvider הוא יישום חלקי של TileProvider שמספק משבצות תמונה על סמך כתובת URL. במחלקה הזו, כל התמונות צריכות להיות באותם ממדים.

תצטרכו להטמיע את UrlTileProvider.getTileUrl(), שמקבל את הקואורדינטות של קטע המפה (x,‏ y, זום) ומחזיר כתובת URL שמפנה לתמונה שבה צריך להשתמש בקטע המפה. השיטה צריכה להחזיר ערך null אם אין משבצת לערכי x, ‏ y ורמת הזום שצוינו. כתובת URL יכולה להפנות למקור מידע באינטרנט, לנכס של Android או לקובץ בדיסק המקומי.

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

1. מגדירים UrlTileProvider כדי לספק את תמונות המשבצות.
2. צריך לשנות את getTileUrl() כדי ליצור את כתובת ה-URL של כל תמונה במשבצת.
3. מספקים אובייקט TileOverlayOptions עם האפשרויות הרלוונטיות:
• fadeIn: ערך בוליאני. מציינת אם המשבצות צריכות להופיע בהדרגה. ערך ברירת המחדל הוא true. אם אתם עוברים במהירות בין שכבות מעל קטעי המפה, יכול להיות שכדאי לכם להשבית את ההופעה ההדרגתית. למידע על הקשר בין שקיפות לבין הופעה הדרגתית, אפשר לעיין בקטע על שקיפות בהמשך.
• ‫tileProvider: ה-TileProvider שבו משתמשים בשכבת-העל הזו.
• ‫transparency: חופש תנועה. מגדירה את רמת השקיפות של תמונות המשבצות. הערך צריך להיות בטווח [0.0f, 1.0f], כאשר 0.0f מייצג אטימות מלאה (ברירת מחדל) ו-1.0f מייצג שקיפות מלאה. בקטע שקיפות שבהמשך מופיעה דוגמת קוד והסבר על הקשר בין שקיפות לבין הבהרה הדרגתית.
• ‫visible: בוליאני. מציין את החשיפה של שכבת-העל של קטעי המפה. שכבת-על של משבצת בלתי נראית (הערך false) לא מצוירת במפה, אבל שומרת על כל שאר המאפיינים שלה. ערך ברירת המחדל הוא true.
• ‫zIndex: קובע את הסדר שבו שכבת-העל של קטע המפה תוצג ביחס לשכבות-על אחרות, כולל שכבות-על של קרקע , עיגולים, קווים שבורים ופוליגונים. שכבות-על עם ערך z-index גבוה יותר משורטטות מעל אלה עם ערכי z-index נמוכים יותר. הסדר של שכבות-על עם אותו z-index הוא שרירותי. ערך ברירת המחדל של z-index הוא 0. שימו לב שסמנים תמיד משורטטים מעל שכבות-על אחרות, בלי קשר ל-z-index של שכבות-העל האחרות.
4. מתקשרים אל GoogleMap.addTileOverlay() כדי להוסיף את שכבת העל למפה.

Kotlin

val tileProvider: TileProvider = object : UrlTileProvider(256, 256) {
    override fun getTileUrl(x: Int, y: Int, zoom: Int): URL? {

        /* Define the URL pattern for the tile images */
        val url = "http://my.image.server/images/$zoom/$x/$y.png"
        return if (!checkTileExists(x, y, zoom)) {
            null
        } else try {
            URL(url)
        } catch (e: MalformedURLException) {
            throw AssertionError(e)
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private fun checkTileExists(x: Int, y: Int, zoom: Int): Boolean {
        val minZoom = 12
        val maxZoom = 16
        return zoom in minZoom..maxZoom
    }
}

val tileOverlay = map.addTileOverlay(
    TileOverlayOptions()
        .tileProvider(tileProvider)
)
tileOverlay?.let {
    val isVisible = it.isVisible
    val fadeIn = it.fadeIn
    val transparency = it.transparency
    val zIndex = it.zIndex
}

      

Java

TileProvider tileProvider = new UrlTileProvider(256, 256) {

    @Override
    public URL getTileUrl(int x, int y, int zoom) {

        /* Define the URL pattern for the tile images */
        String s = String.format(java.util.Locale.US, "http://my.image.server/images/%d/%d/%d.png", zoom, x, y);

        if (!checkTileExists(x, y, zoom)) {
            return null;
        }

        try {
            return new URL(s);
        } catch (MalformedURLException e) {
            throw new AssertionError(e);
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private boolean checkTileExists(int x, int y, int zoom) {
        int minZoom = 12;
        int maxZoom = 16;

        return (zoom >= minZoom && zoom <= maxZoom);
    }
};

TileOverlay tileOverlay = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(tileProvider));

      

כדי לראות דוגמה לשימוש ב-UrlTileProvider, עיינו ב-TileOverlayDemoActivity בקוד לדוגמה שמצורף ל-Google Play Services SDK.

הערה: אם אתם צריכים שליטה פרטנית יותר, אתם יכולים להגדיר ספק של משבצות על ידי הטמעה של הממשק TileProvider.

הגדרת השקיפות של שכבות מעל קטעי המפה

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

דוגמת הקוד הבאה מחליפה את השקיפות של שכבת העל של המשבצות בין 0.5f לבין 0.0f:

Kotlin

val tileOverlayTransparent = map.addTileOverlay(
    TileOverlayOptions()
        .tileProvider(object : UrlTileProvider(256, 256) {
            // ...
        })
        .transparency(0.5f)
)

// Switch between 0.0f and 0.5f transparency.
tileOverlayTransparent?.let {
    it.transparency = 0.5f - it.transparency
}

      

Java

TileOverlay tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(new UrlTileProvider(256, 256) {
        // ...
    })
    .transparency(0.5f));

// Switch between 0.0f and 0.5f transparency.
if (tileOverlayTransparent != null) {
    tileOverlayTransparent.setTransparency(0.5f - tileOverlayTransparent.getTransparency());
}

      

השקיפות מיושמת כמכפיל של ערוץ אלפא לתמונות של משבצות. כדי להגדיר את השקיפות של שכבת-על של משבצת, צריך לספק אובייקט TileOverlayOptions עם ערך transparency בטווח [0.0f, 1.0f], כמו בדוגמה שלמעלה. הערך 0.0f מציין ששכבת-העל של קטעי המפה אטומה לחלוטין, והערך 1.0f מציין שהיא שקופה לחלוטין. ערך ברירת המחדל הוא 0.0f (אטום).

כדי לגשת לשקיפות של שכבת העל של קטעי המפה, מפעילים את TileOverlay.getTransparency(). כדי לשנות אותה, מפעילים את TileOverlay.setTransparency().

שקיפות, אנימציה והופעה הדרגתית

אין אנימציה כשהשקיפות משתנה. האפשרות transparency (שקיפות) פועלת לצד האפשרות fadeIn (הנפשה של הופעה הדרגתית).

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

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

אפשר להסיר שכבה מעל קטעי המפה באמצעות השיטה TileOverlay.remove().

Kotlin

tileOverlay?.remove()

      

Java

tileOverlay.remove();

      

ניקוי משבצות לא עדכניות

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

Kotlin

tileOverlay?.clearTileCache()

      

Java

tileOverlay.clearTileCache();