צורות

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

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

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

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

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

דוגמאות קוד

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

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

  • ‫CircleDemoActivity‏ (Java / Kotlin): מעגל
  • ‫PolygonDemoActivity‏ (Java / Kotlin): Polygon
  • ‫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)
polyline?.let {
    val isClickable = it.isClickable
    val isGeodesic = it.isGeodesic
    val isVisible = it.isVisible
    val color = it.color
    val width = it.width
    val zIndex = it.zIndex
    val points = it.points
}

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() ולספק רשימה חדשה של נקודות לקו הפוליגוני.

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

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

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

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

כדי להשתמש בהתאמות האישיות של קווים פוליגוניים, צריך להשתמש בגרסה 18.1.0 ואילך של ה-SDK של מפות ל-Android ולהשתמש במנוע הרינדור העדכני ביותר של ה-SDK של מפות ל-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())));

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

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

אפשר להגדיר את המראה של קו פוליגוני כטקסטורה של מפת סיביות חוזרת. כדי לעשות את זה, יוצרים 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)
)
hollowPolygon?.let {
    val isClickable = it.isClickable
    val isGeodesic = it.isGeodesic
    val isVisible = it.isVisible
    val fillColor = it.fillColor
    val strokeColor = it.strokeColor
    val strokeWidth = it.strokeWidth
    val zIndex = it.zIndex
    val points = it.points
    val holes = it.holes
}

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

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

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

מעגלים

מפה עם עיגול

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

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

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

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

כדי לשנות את הצורה של העיגול אחרי שמוסיפים אותו, אפשר לקרוא לפונקציות 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)
circle?.let {
    val isClickable = it.isClickable
    val isVisible = it.isVisible
    val center = it.center
    val radius = it.radius
    val fillColor = it.fillColor
    val strokeWidth = it.strokeWidth
    val zIndex = it.zIndex
}

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

כשמשתמש לוחץ על עיגול, אתם מקבלים קריאה חוזרת (callback) מסוג 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));

המפה תופיע כמו בתמונה הבאה:

מפה עם קו פוליגוני ממלבורן לפרת'

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

צבע משיכה

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

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

צבע מילוי

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

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

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

רוחב משיכה

רוחב הקו, כערך מסוג float בפיקסלים (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());

קטע הקוד הבא מציין מפת סיביות (bitmap) מותאמת אישית למודעת הסגירה לסרטון:

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

קטעים גיאודזיים

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

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

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

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

Z-index

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

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

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

חשיפה

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

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

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

אפשר לאחסן אובייקט נתונים שרירותי עם קו פוליגוני, פוליגון או עיגול באמצעות ה-method‏ 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-index של הצורה.