צורות

בחירת פלטפורמה: 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>) אם הנקודות כבר כלולות ברשימה).

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

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

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

      

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

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

התאמה אישית של קו מרובה נקודות

יש כמה דרכים להתאים אישית את המראה של קווים מרובים:

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

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

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

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

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

      

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

      

יצירת Polyline הדרגתי

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

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

      

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

      

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

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

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

      

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

      

אירועים של Polyline

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

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

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

פוליגונים

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

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

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

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

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

      

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)

      

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

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

השלמה אוטומטית של מצולע

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

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

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

      

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

      

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

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

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

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

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

      

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

      

הפוליגון החלול מופיע במפה כפי שמוצג למטה:

אירועי מצולע

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

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

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

עיגולים

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

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

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

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

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

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

קטע הקוד הבא מוסיף מעגל למפה על ידי יצירת אובייקט CircleOptions וקריאה לפונקציה GoogleMap.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);

      

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)

      

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

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

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

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

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

      

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
}

      

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

התאמה אישית של המראֶה

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

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

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

      

Kotlin

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

      

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

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

צבע משיכה

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

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

צבע המילוי

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

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

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

רוחב משיכה

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

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

שבץ

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

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

Java

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

      

Kotlin

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

      

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

סוגי מפרקים

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

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

Java

polyline.setJointType(JointType.ROUND);

      

Kotlin

polyline.jointType = JointType.ROUND

      

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

רישיות

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

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

Java

polyline.setStartCap(new RoundCap());

      

Kotlin

polyline.startCap = RoundCap()

      

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

Java

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

      

Kotlin

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

      

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

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

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

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

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

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

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

אינדקס Z

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

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

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

חשיפה

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

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

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

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

הקוד שבהמשך מגדיר תג שרירותי (A) של ה-Polyline שצוין:

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

      

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"

      

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

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