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

Switch to English

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

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

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

דוגמאות קוד

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

אריח שכבת-על – Java: תכונות שכבת-על של אריח ב-Java
אריח קואורדינטות - Java: מערכת הקואורדינטות המשמשת בשכבות-על של משבצות ב-Java
אריח שכבת-על כשכבת-על – קוטלין: תכונות שכבת-על של אריח ב-Kotlin
אריג'ן-דמו-פעילות - קוטלין: מערכת הקואורדינטות המשמשת לשכבות-על של אריחים בקוטלין

מבוא

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי לראות דוגמה של UrlTileProvider בפעולה, אפשר לעיין בTileOverlayDemoActivity בקוד לדוגמה הכלול בחבילה של Google Play Services SDK.

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

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

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

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());
    }
}

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
    }
}

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

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

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

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

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

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

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

Java


tileOverlay.remove();

Kotlin


tileOverlay?.remove()

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

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

Java


tileOverlay.clearTileCache();

Kotlin


tileOverlay?.clearTileCache()