צורות

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

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

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

דוגמאות קוד

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

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

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

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

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

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

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

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

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

קטע הקוד הבא מדגים איך מוסיפים מלבן למפה:

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

      

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

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

      

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.

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

      

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(), כפי שמוצג כאן:

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

      

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.

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

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

      

// 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 הנקודות.

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

      

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

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

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

      

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

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

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

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

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

      

// 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), כפי שמתואר בדוגמת הקוד הבאה:

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
}

      

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 נחשפות לכל המאפיינים, כך שתוכלו לגשת בקלות למצב הנוכחי של הצורה.

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

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

      

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

      

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

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

צבע משיכה

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

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

צבע מילוי

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

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

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

רוחב משיכה

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

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

תבנית הקו

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

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

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

      

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

      

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

סוגי המפרקים

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

בדוגמה הבאה חל סוג צומת עגול על קו פוליגון:

polyline.jointType = JointType.ROUND

      

polyline.setJointType(JointType.ROUND);

      

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

מגבלות על מספר השורות

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

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

polyline.startCap = RoundCap()

      

polyline.setStartCap(new RoundCap());

      

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

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

      

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

      

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

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

קטעי נתיב גיאודזיים

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

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

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

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

Z-index

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

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

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

חשיפה

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

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

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

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

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

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"

      

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 של הצורה.