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

דף זה תורגם על ידי Cloud Translation API.

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

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

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

דוגמאות קוד

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

TileOverlayDemoActivity – Java: תכונות של שכבת-על של משבצות ב-Java
TilecoordinateDemoActivity – Java: מערכת הקואורדינטות שמשמשת לשכבות-על של משבצות ב-Java
TileOverlayDemoActivity – Kotlin: תכונות של שכבת-על של משבצות ב-Kotlin
Tile שמניב DemoActivity – Kotlin: מערכת הקואורדינטות שמשמשת לשכבות-על של משבצות ב-Kotlin

מבוא

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

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

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

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

קואורדינטות של משבצות ורמות מרחק מתצוגה

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

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

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

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

מפת העולם המחולקת לארבע שורות וארבע עמודות של אריחים.

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

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

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

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

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

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

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

מגדירים UrlTileProvider כדי להוסיף את תמונות המשבצת.
שינוי של getTileUrl() כדי ליצור כתובת URL לכל תמונת משבצת.
מספקים אובייקט TileOverlayOptions עם האפשרויות הרלוונטיות:

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

מפעילים את GoogleMap.addTileOverlay() כדי להוסיף את שכבת-העל למפה.

Kotlin



private lateinit var map: GoogleMap

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

Java


private GoogleMap map;

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("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 בקוד לדוגמה שכלול ב-SDK של Google Play Services.

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

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

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

Kotlin



private var tileOverlayTransparent: TileOverlay? = null

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

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

Java


private TileOverlay tileOverlayTransparent;

@Override
public void onMapReady(GoogleMap map) {
    tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
        .tileProvider(new UrlTileProvider(256, 256) {
            // ...
        })
        .transparency(0.5f));
}

// Switch between 0.0f and 0.5f transparency.
public void toggleTileOverlayTransparency() {
    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().

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

לא תוצג אנימציה כשמשנים את השקיפות. אפשרות השקיפות פועלת לצד האפשרות fadeIn.

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

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

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

Kotlin



tileOverlay?.remove()

Java


tileOverlay.remove();

ניקוי אריחים לא עדכניים

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

Kotlin



tileOverlay?.clearTileCache()

Java


tileOverlay.clearTileCache();