צורות

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

ה-API של מפות Google ל-Android מציע כמה דרכים פשוטות להוספת צורות למפות, כדי להתאים אותן אישית לאפליקציה.

• Polyline היא סדרה של מקטעי קווים מחוברים שיכולים ליצור כל צורה שרוצים, שאפשר להשתמש בהם כדי לסמן נתיבים ומסלולים במפה.
• Polygon הוא צורה מתוחכמת שאפשר להשתמש בה כדי לסמן אזורים במפה.
• Circle הוא היטל מדויק מבחינה גיאוגרפית של מעגל על פני כדור הארץ שמשורטט במפה.

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

דוגמאות קוד

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

בנוסף, מאגר ApiDemos ב-GitHub כולל דוגמאות שמדגימות את השימוש בצורות ואת התכונות שלהן:

• CircleDemoActivity (Java / Kotlin): מעגל
• PolygonDemoActivity (Java / Kotlin): פוליגון
• PolylineDemoActivity (Java / Kotlin): Polyline

קווים פוליגוניים

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

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

כדי ליצור Polyline, קודם יוצרים אובייקט PolylineOptions ומוסיפים אליו נקודות. הנקודות מייצגות נקודה על פני כדור הארץ ובאות לידי ביטוי כאובייקט LatLng. מקטעי קו משורטטים בין נקודות בהתאם לסדר שבו הוספתם אותם לאובייקט PolylineOptions.

כדי להוסיף נקודות לאובייקט PolylineOptions, קוראים לפונקציה PolylineOptions.add(). שימו לב שהשיטה הזו לוקחת מספר משתנה של פרמטרים, כך שאפשר להוסיף כמה נקודות בכל פעם (אפשר גם לקרוא ל-PolylineOptions.addAll(Iterable<LatLng>) אם הנקודות כבר מופיעות ברשימה).

עכשיו אפשר להוסיף את הקו הפוליגוני למפה באמצעות קריאה ל-GoogleMap.addPolyline(PolylineOptions). ה-method מחזירה אובייקט Polyline, שאיתו אפשר לשנות את הקו הפוליגוני מאוחר יותר.

קטע הקוד הבא ממחיש איך להוסיף מלבן למפה:

Kotlin

// Instantiates a new Polyline object and adds points to define a rectangle
val polylineOptions = PolylineOptions()
    .add(LatLng(37.35, -122.0))
    .add(LatLng(37.45, -122.0)) // North of the previous point, but at the same longitude
    .add(LatLng(37.45, -122.2)) // Same latitude, and 30km to the west
    .add(LatLng(37.35, -122.2)) // Same longitude, and 16km to the south
    .add(LatLng(37.35, -122.0)) // Closes the polyline.

// Get back the mutable Polyline
val polyline = map.addPolyline(polylineOptions)

      

Java

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions polylineOptions = new PolylineOptions()
    .add(new LatLng(37.35, -122.0))
    .add(new LatLng(37.45, -122.0))  // North of the previous point, but at the same longitude
    .add(new LatLng(37.45, -122.2))  // Same latitude, and 30km to the west
    .add(new LatLng(37.35, -122.2))  // Same longitude, and 16km to the south
    .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = map.addPolyline(polylineOptions);

      

המלבן מופיע במפה באופן הבא:

כדי לשנות את הצורה של הקו הפוליגוני אחרי שהוא נוסף, אפשר לקרוא ל-Polyline.setPoints() ולספק רשימה חדשה של נקודות לקו הפוליגוני.

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

התאמה אישית של קו פוליגוני

יש כמה דרכים להתאים אישית את המראה של קווים פוליגוניים:

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

כדי להשתמש בהתאמות האישיות של Polyline, צריך להשתמש ב-SDK של מפות Google ל-Android בגרסה 18.1.0 ואילך ולהשתמש ב-SDK העדכני של מפות Google ל-Android.

יצירת קו פוליגוני צבעוני

אפשר להשתמש בטווחים כדי לצבוע בנפרד מקטעי קו פוליגוני על ידי יצירת אובייקטים StyleSpan, והוספתם ל-PolylineOptions באמצעות השיטות addSpan() או addSpans(). כברירת מחדל, כל פריט במערך יגדיר את הצבע של פלח השורה המתאים. הדוגמה הבאה מציגה את הגדרת צבעי הקטע כדי ליצור קו פוליגוני עם קטעים אדומים וירוקים:

Kotlin

val line = map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(StyleSpan(Color.RED))
        .addSpan(StyleSpan(Color.GREEN))
)

      

Java

Polyline line = map.addPolyline(new PolylineOptions()
        .add(new LatLng(47.6677146,-122.3470447), new LatLng(47.6442757,-122.2814693))
        .addSpan(new StyleSpan(Color.RED))
        .addSpan(new StyleSpan(Color.GREEN)));

      

יצירת קו פוליגוני הדרגתי

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

Kotlin

val line = map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(
            StyleSpan(
                StrokeStyle.gradientBuilder(
                    Color.RED,
                    Color.YELLOW
                ).build()
            )
        )
)

      

Java

Polyline line = map.addPolyline(new PolylineOptions()
        .add(new LatLng(47.6677146,-122.3470447), new LatLng(47.6442757,-122.2814693))
        .addSpan(new StyleSpan(StrokeStyle.gradientBuilder(Color.RED, Color.YELLOW).build())));

      

יצירת קו פוליגוני עם חותמת

ניתן להגדיר את המראה של קו פוליגוני למרקם חוזר של מפת סיביות (bitmap). כדי לעשות את זה, צריך ליצור StampStyle של TextureStyle ואז להגדיר את המאפיין הזה באובייקט האפשרויות של הצורה באמצעות קריאה ל-PolylineOptions.addSpan() כמו בדוגמה הבאה:

Kotlin

val stampStyle =
    TextureStyle.newBuilder(BitmapDescriptorFactory.fromResource(R.drawable.walking_dot)).build()
val span = StyleSpan(StrokeStyle.colorBuilder(Color.RED).stamp(stampStyle).build())
map.addPolyline(
    PolylineOptions()
        .add(LatLng(47.6677146, -122.3470447), LatLng(47.6442757, -122.2814693))
        .addSpan(span)
)

      

Java

StampStyle stampStyle =
        TextureStyle.newBuilder(BitmapDescriptorFactory.fromResource(R.drawable.walking_dot)).build();
StyleSpan span = new StyleSpan(StrokeStyle.colorBuilder(Color.RED).stamp(stampStyle).build());
map.addPolyline(new PolylineOptions()
        .add(new LatLng(47.6677146,-122.3470447), new LatLng(47.6442757,-122.2814693))
        .addSpan(span));

      

אירועים של קו פוליגוני

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

משתמשים ב-OnPolylineClickListener כדי להאזין ללחיצה על אירועים בקו פוליגוני קליקבילי. כדי להגדיר את ה-listener הזה במפה, צריך לקרוא ל-GoogleMap.setOnPolylineClickListener(OnPolylineClickListener). כשמשתמש ילחץ על קו פוליגוני, תקבלו קריאה חוזרת (callback) מסוג onPolylineClick(Polyline).

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

פוליגונים

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

אפשר להוסיף Polygon למפה בדיוק כמו שמוסיפים Polyline. קודם כול יוצרים אובייקט PolygonOptions ומוסיפים לו כמה נקודות. הנקודות האלה יהוו את קווי המתאר של הפוליגון. אחר כך מוסיפים את הפוליגון למפה באמצעות קריאה ל-GoogleMap.addPolygon(PolygonOptions), ותחזיר אובייקט Polygon.

קטע הקוד הבא מוסיף מלבן למפה.

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

Kotlin

// Instantiates a new Polygon object and adds points to define a rectangle
val rectOptions = PolygonOptions()
    .add(
        LatLng(37.35, -122.0),
        LatLng(37.45, -122.0),
        LatLng(37.45, -122.2),
        LatLng(37.35, -122.2),
        LatLng(37.35, -122.0)
    )

// Get back the mutable Polygon
val polygon = map.addPolygon(rectOptions)

      

Java

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions polygonOptions = new PolygonOptions()
    .add(new LatLng(37.35, -122.0),
        new LatLng(37.45, -122.0),
        new LatLng(37.45, -122.2),
        new LatLng(37.35, -122.2),
        new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = map.addPolygon(polygonOptions);

      

כדי לשנות את הצורה של הפוליגון אחרי שמוסיפים אותו, אפשר לקרוא לפונקציה Polygon.setPoints() ולספק רשימה חדשה של נקודות לקווי המתאר של הפוליגון.

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

השלמה אוטומטית בפוליגון

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

שני הפוליגונים הבאים זהים, והפעלת ה-polygon.getPoints() בכל אחד מהפוליגונים תחזיר את כל 4 הנקודות.

Kotlin

val polygon1 = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0),
            LatLng(0.0, 0.0)
        )
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE)
)
val polygon2 = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0)
        )
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE)
)

      

Java

Polygon polygon1 = map.addPolygon(new PolygonOptions()
    .add(new LatLng(0, 0),
        new LatLng(0, 5),
        new LatLng(3, 5),
        new LatLng(0, 0))
    .strokeColor(Color.RED)
    .fillColor(Color.BLUE));

Polygon polygon2 = map.addPolygon(new PolygonOptions()
    .add(new LatLng(0, 0),
        new LatLng(0, 5),
        new LatLng(3, 5))
    .strokeColor(Color.RED)
    .fillColor(Color.BLUE));

      

יצירת פוליגון חלול

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

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

קטע הקוד הבא ייצור מלבן יחיד עם חור מלבני קטן יותר.

Kotlin

val hole = listOf(
    LatLng(1.0, 1.0),
    LatLng(1.0, 2.0),
    LatLng(2.0, 2.0),
    LatLng(2.0, 1.0),
    LatLng(1.0, 1.0)
)
val hollowPolygon = map.addPolygon(
    PolygonOptions()
        .add(
            LatLng(0.0, 0.0),
            LatLng(0.0, 5.0),
            LatLng(3.0, 5.0),
            LatLng(3.0, 0.0),
            LatLng(0.0, 0.0)
        )
        .addHole(hole)
        .fillColor(Color.BLUE)
)

      

Java

List<LatLng> hole = Arrays.asList(new LatLng(1, 1),
    new LatLng(1, 2),
    new LatLng(2, 2),
    new LatLng(2, 1),
    new LatLng(1, 1));
Polygon hollowPolygon = map.addPolygon(new PolygonOptions()
    .add(new LatLng(0, 0),
        new LatLng(0, 5),
        new LatLng(3, 5),
        new LatLng(3, 0),
        new LatLng(0, 0))
    .addHole(hole)
    .fillColor(Color.BLUE));

      

הפוליגון החלול מופיע במפה באופן הבא:

אירועי פוליגון

כברירת מחדל, לא ניתן ללחוץ על פוליגונים. אפשר להפעיל ולהשבית את הקליקביליות על ידי קריאה ל-Polygon.setClickable(boolean).

משתמשים ב-OnPolygonClickListener כדי להאזין ללחיצה על אירועים בפוליגון שניתן ללחוץ עליו. כדי להגדיר את ה-listener הזה במפה, צריך לקרוא ל-GoogleMap.setOnPolygonClickListener(OnPolygonClickListener). כשמשתמש ילחץ על פוליגון, תקבלו קריאה חוזרת (callback) מסוג onPolygonClick(Polygon).

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

עיגולים

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

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

• center בתור LatLng.
• radius במטרים.

בשלב זה, מעגל מוגדר כקבוצת כל הנקודות על פני כדור הארץ, שנמצאות במרחק של radius מטרים מה-center הנתון. בגלל האופן שבו ההיטל של Mercator שבו משתמשים ב-API של מפות Google מציג עיגול על משטח ישר, הוא ייראה כעיגול כמעט מושלם במפה כשהוא ימוקם ליד קו המשווה, והוא ייראה יותר לא מעגלי (על המסך) כשהעיגול יתרחק מקו המשווה.

כדי לשנות את הצורה של העיגול אחרי הוספת העיגול, אפשר לקרוא ל-Circle.setRadius() או ל-Circle.setCenter() ולספק ערכים חדשים.

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

קטע הקוד הבא מוסיף עיגול למפה על ידי בניית אובייקט CircleOptions וקריאה ל-GoogleMap.addCircle(CircleOptions):

Kotlin

// Instantiates a new CircleOptions object and defines the center and radius
val circleOptions = CircleOptions()
    .center(LatLng(37.4, -122.1))
    .radius(1000.0) // In meters

// Get back the mutable Circle
val circle = map.addCircle(circleOptions)

      

Java

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions = new CircleOptions()
    .center(new LatLng(37.4, -122.1))
    .radius(1000); // In meters

// Get back the mutable Circle
Circle circle = map.addCircle(circleOptions);

      

אירועים של מעגלים

כברירת מחדל, לא ניתן ללחוץ על מעגלים. אפשר להפעיל ולהשבית את הקליקביליות על ידי קריאה ל-GoogleMap.addCircle() באמצעות CircleOptions.clickable(boolean) או בקריאה ל-Circle.setClickable(boolean).

משתמשים ב-OnCircleClickListener כדי להאזין לאירועים לוחצים על עיגול שניתן ללחוץ עליו. כדי להגדיר את ה-listener הזה במפה, צריך לקרוא ל-GoogleMap.setOnCircleClickListener(OnCircleClickListener).

כשמשתמש ילחץ על מעגל, תקבלו קריאה חוזרת ב-onCircleClick(Circle), כפי שמוצג בדוגמת הקוד הבאה:

Kotlin

val circle = map.addCircle(
    CircleOptions()
        .center(LatLng(37.4, -122.1))
        .radius(1000.0)
        .strokeWidth(10f)
        .strokeColor(Color.GREEN)
        .fillColor(Color.argb(128, 255, 0, 0))
        .clickable(true)
)
map.setOnCircleClickListener {
    // Flip the r, g and b components of the circle's stroke color.
    val strokeColor = it.strokeColor xor 0x00ffffff
    it.strokeColor = strokeColor
}

      

Java

Circle circle = map.addCircle(new CircleOptions()
    .center(new LatLng(37.4, -122.1))
    .radius(1000)
    .strokeWidth(10)
    .strokeColor(Color.GREEN)
    .fillColor(Color.argb(128, 255, 0, 0))
    .clickable(true));

map.setOnCircleClickListener(new GoogleMap.OnCircleClickListener() {
    @Override
    public void onCircleClick(Circle circle) {
        // Flip the r, g and b components of the circle's stroke color.
        int strokeColor = circle.getStrokeColor() ^ 0x00ffffff;
        circle.setStrokeColor(strokeColor);
    }
});

      

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

התאמה אישית של תצוגות

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

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

Kotlin

val polyline = map.addPolyline(
    PolylineOptions()
        .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
        .width(25f)
        .color(Color.BLUE)
        .geodesic(true)
)

      

Java

Polyline polyline = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

      

המפה תיראה כך:

הערה: אפשר להחיל את רוב המאפיינים האלה על כל אחת מהצורות שמתוארות במאמר, אבל יכול להיות שחלק מהתכונות לא יחשבו על צורות מסוימות (למשל, לא יכול להיות צבע מילוי ל-Polyline כי אין לו פנים).

צבע משיכה

צבע הקווים הוא מספר שלם בצבע אלפא-אדום-ירוק-כחול (ARGB) של 32 ביט, שמציין את האטימות והצבע של קו הצורה. כדי להגדיר את המאפיין הזה באובייקט האפשרויות של הצורה, קוראים ל-*Options.strokeColor() (או PolylineOptions.color() במקרה של קו פוליגוני). אם לא צוין צבע קו, ברירת המחדל של צבע הקו הוא שחור (Color.BLACK).

אחרי שמוסיפים את הצורה למפה, אפשר לגשת לצבע הקו באמצעות קריאה ל-getStrokeColor() (או getColor() לקו פוליגוני), ואפשר לשנות אותו באמצעות הפקודה setStrokeColor() (setColor() for a polyline).

צבע המילוי

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

צבע המילוי הוא מספר שלם בצבע אלפא-אדום-ירוק-כחול (ARGB) של 32 ביט, שמציין את האטימות והצבע של החלק הפנימי של הצורה. מגדירים את המאפיין הזה באובייקט האפשרויות של הצורה באמצעות קריאה ל-*Options.fillColor(). אם לא צוין, צבע ברירת המחדל של קו הוא שקוף (Color.TRANSPARENT).

אחרי שמוסיפים את הצורה למפה, אפשר לגשת לצבע המילוי באמצעות קריאה ל-getFillColor(), ואפשר לשנות אותו באמצעות setFillColor().

רוחב משיכה

רוחב קו הקו, כצף ב-פיקסלים (px). הרוחב לא משתנה כשהמפה מוגדלת (כלומר, לצורה יהיה אותו רוחב קווים בכל רמות הזום). מגדירים את המאפיין הזה באובייקט האפשרות של הצורה באמצעות קריאה ל-*Options.strokeWidth() (או PolylineOptions.width() לקו פוליגוני). אם לא צוין קו, קו ברירת המחדל הוא 10 פיקסלים.

אחרי הוספת הצורה למפה, ניתן לגשת לרוחב הקווים באמצעות קריאה של getStrokeWidth() (או getWidth() לקו פוליגוני) ולשנות אותו באמצעות קריאה ל-setStrokeWidth() (setWidth() for a polyline).

קו ביטול נעילה

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

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

Kotlin

val pattern = listOf(
    Dot(), Gap(20F), Dash(30F), Gap(20F)
)
polyline.pattern = pattern

      

Java

List<PatternItem> pattern = Arrays.asList(
    new Dot(), new Gap(20), new Dash(30), new Gap(20));
polyline.setPattern(pattern);

      

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

סוגי המפרקים

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

הדוגמה הבאה מחילה סוג מפרק עגול על קו פוליגוני:

Kotlin

polyline.jointType = JointType.ROUND

      

Java

polyline.setJointType(JointType.ROUND);

      

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

אותיות רישיות

אפשר לציין סגנון Cap לכל קצה של קו פוליגוני. האפשרויות הן תחת (ברירת המחדל), ריבוע, עגול או מפת סיביות מותאמת אישית. אפשר להגדיר את הסגנון ב-PolylineOptions.startCap וב-PolylineOptions.endCap, או להשתמש בשיטות מתאימות של getter ו-setter.

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

Kotlin

polyline.startCap = RoundCap()

      

Java

polyline.setStartCap(new RoundCap());

      

קטע הקוד הבא מציין מפת סיביות מותאמת אישית עבור מודעת הסיום:

Kotlin

polyline.endCap = CustomCap(BitmapDescriptorFactory.fromResource(R.drawable.arrow), 16F)

      

Java

polyline.setEndCap(
    new CustomCap(BitmapDescriptorFactory.fromResource(R.drawable.arrow), 16));

      

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

אם משתמשים ב-BitmapDescriptorFactory.fromResource() כדי ליצור את מפת הסיביות, צריך לוודא שאתם משתמשים במשאב שלא תלוי בדחיסות (nodpi).

פלחים גיאודזיים

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

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

כדי להגדיר את המאפיין הזה באובייקט האפשרות של הצורה, קוראים לפונקציה *Options.geodesic() כש-true מציין שיש לצייר את הקטעים כגיאודסיקה ו-false מציין שיש לצייר את הקטעים כקווים ישרים. אם לא צוין אחרת, ברירת המחדל היא פלחים לא גיאוגרפיים (false).

אחרי הוספת הצורה למפה, ניתן לגשת להגדרה הגיאודסית על ידי קריאה ל-isGeodesic(), וכדי לשנות אותה על ידי קריאה ל-setGeodesic().

אינדקס Z

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

שימו לב שהסמנים תמיד משורטטים מעל שכבות-על אחרות, בלי קשר ל-z-index של שאר שכבות-העל.

כדי להגדיר את המאפיין הזה באובייקט האפשרויות של הצורה, שולחים קריאה ל-*Options.zIndex(). אם לא צוין, ערך ברירת המחדל של z-index הוא 0. אחרי שמוסיפים את הצורה למפה, ניתן לגשת ל-z-index באמצעות קריאה ל-getZIndex(), ואפשר לשנות אותו באמצעות הפקודה setZIndex().

חשיפה

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

כדי להגדיר את המאפיין הזה באובייקט האפשרויות של הצורה, שולחים קריאה ל-*Options.visible(). אם לא צוין, ברירת המחדל של הרשאות הגישה היא true. אחרי שהצורה נוספה למפה, אפשר לגשת להרשאות על ידי קריאה ל-isVisible(), ואפשר לשנות אותה בקריאה setVisible().

שיוך נתונים לצורה

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

הקוד שבהמשך מגדיר תג שרירותי (A) עבור הקו הפוליגוני שצוין:

Kotlin

val polyline = map.addPolyline(
    PolylineOptions()
        .clickable(true)
        .add(
            LatLng(-35.016, 143.321),
            LatLng(-34.747, 145.592),
            LatLng(-34.364, 147.891),
            LatLng(-33.501, 150.217),
            LatLng(-32.306, 149.248),
            LatLng(-32.491, 147.309)
        )
)
polyline.tag = "A"

      

Java

Polyline polyline = map.addPolyline((new PolylineOptions())
    .clickable(true)
    .add(new LatLng(-35.016, 143.321),
        new LatLng(-34.747, 145.592),
        new LatLng(-34.364, 147.891),
        new LatLng(-33.501, 150.217),
        new LatLng(-32.306, 149.248),
        new LatLng(-32.491, 147.309)));

polyline.setTag("A");

      

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

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