צורות

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

מפה עם קו פוליגוני אדום מלא

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

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

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

דוגמאות קוד

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

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

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

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

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

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

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

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

לאחר מכן אפשר להוסיף את קו הפוליגון למפה באמצעות קריאה ל-GoogleMap.addPolyline(PolylineOptions). השיטה מחזירה אובייקט 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() ולספק רשימה חדשה של נקודות לקו הפוליגון.

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

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

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

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

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

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

מפה עם קו פוליגוני צבעוני

אפשר להשתמש ב-spans כדי לצבוע פלחים ספציפיים של קו פוליגון. לשם כך, יוצרים אובייקטים מסוג 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)));

יצירת קו פוליגון עם שיפוע

מפה עם קו פוליגון בגוון פסטל

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

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

יצירת קו מרובה עם חותמת

מפה עם קו מרובה עם חותמת

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

פוליגונים

אובייקטים מסוג 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 אחד כדי ליצור צורות מורכבות כמו טבעות מלאות או 'דנאטס' (כאשר אזורים פוליגונים מופיעים בתוך הפוליגון כ'איים'). צורות מורכבות הן תמיד הרכבה של נתיבים מרובים ופשוטים יותר.

יש להגדיר שני נתיבים באותו אזור. האזור הגדול מבין השניים מגדיר את אזור המילוי, והוא פוליגון פשוט ללא אפשרויות נוספות. לאחר מכן, מעבירים נתיב שני לשיטה 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 כדי להאזין לאירועי קליקים על פוליגון שניתן ללחוץ עליו. כדי להגדיר את המאזין הזה במפה, צריך להפעיל את הפונקציה GoogleMap.setOnPolygonClickListener(OnPolygonClickListener). כשמשתמש לוחץ על פוליגון, תקבלו קריאה חוזרת מסוג onPolygonClick(Polygon).

מעגלים

מפה עם מעגל

בנוסף לכיתה הגנרית Polygon, ממשק Maps API כולל גם כיתות ספציפיות לאובייקטים מסוג 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 כדי להאזין לאירועים לוחצים על עיגול שניתן ללחוץ עליו. כדי להגדיר את המאזין הזה במפה, צריך להפעיל את הפונקציה 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);
    }
});

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

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

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

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

המפה מופיעה כפי שמוצג בהמשך:

מפה עם קו פוליגון ממלבורן לפרת&#39;

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

צבע משיכה

צבע הקו הוא מספר שלם של 32 ביט בפורמט אלפא-אדום-ירוק-כחול (ARGB), שמציין את האטימות ואת הצבע של הקו של הצורה. מגדירים את המאפיין הזה באובייקט האפשרויות של הצורה באמצעות קריאה ל-*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 לכל קצה של קו פוליגוני. האפשרויות הן: 'חיתוך ישר' (ברירת המחדל), 'מרובע', 'עגול' או 'קובץ BMP בהתאמה אישית'. מגדירים את הסגנון ב-PolylineOptions.startCap וב-PolylineOptions.endCap, או משתמשים בשיטות ה-getter וה-setter המתאימות.

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

Kotlin



polyline.startCap = RoundCap()

Java


polyline.setStartCap(new RoundCap());

קטע הקוד הבא מציין קובץ bitmap מותאם אישית לקצה העליון:

Kotlin



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

Java


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

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

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

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

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

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

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

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

אינדקס Z

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

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

כדי להגדיר את המאפיין הזה באובייקט האפשרויות של הצורה, צריך להפעיל את *Options.zIndex(). אם לא צוין, ערך ברירת המחדל של z-index הוא 0. אחרי שמוסיפים את הצורה למפה, אפשר לגשת למזהה z באמצעות קריאה ל-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 של הצורה.