شکل‌ها

پلاتفرم را انتخاب کنید: Android iOS JavaScript

Google Maps API برای Android چند روش ساده برای افزودن شکل به نقشه‌هایتان ارائه می‌دهد تا بتوانید آن‌ها را برای برنامه‌تان سفارشی‌سازی کنید.

• Polyline مجموعه‌ای از بخش‌های خطی متصل است که می‌تواند هر شکلی را که می‌خواهید ایجاد کند و می‌تواند برای علامت‌گذاری مسیرها و جاده‌ها روی نقشه استفاده شود.
• Polygon شکلی بسته است که می‌توان از آن برای علامت‌گذاری مناطق روی نقشه استفاده کرد.
• Circle تصویر جغرافیایی دقیقی از دایره‌ای روی سطح زمین است که روی نقشه ترسیم شده است.

برای همه این شکل‌ها، می‌توانید ظاهرشان را با تغییر دادن تعدادی از ویژگی‌ها سفارشی‌سازی کنید.

نمونه‌های کد

آموزش افزودن چندضلعی‌ها و چندخطی‌ها برای نمایش مناطق و مسیرها شامل همه کدهای یک برنامه Android ساده است.

علاوه‌براین، مخزن ApiDemos در GitHub شامل نمونه‌هایی است که استفاده از شکل‌ها و ویژگی‌های آن‌ها را نشان می‌دهد:

• CircleDemoActivity (Java / Kotlin): Circle
• PolygonDemoActivity (Java / Kotlin): Polygon
• PolylineDemoActivity (Java / Kotlin): Polyline

چندخطی‌ها

کلاس 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)

      

جاوا

// 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 یا جدیدتر «کیت توسعه نرم‌افزار Google Maps برای Android» استفاده کنید و از جدیدترین پردازنده «کیت توسعه نرم‌افزار Google Maps برای 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)),
)

      

جاوا

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) یک گرادیان تعریف کنید تا رنگ‌های شروع و پایان خط را مشخص کنید. این ویژگی را با فراخوانی 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(),
            ),
        ),
)

      

جاوا

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

      

جاوا

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) را فراخوانی کنید. وقتی کاربر روی چندخطی کلیک می‌کند، فراخوانی برگشتی onPolylineClick(Polyline) دریافت خواهید کرد.

توجه: اگر چند هم‌پوشانی یا شکل (نشانگر، چندخطی، چندضلعی، دایره، و/یا هم‌پوشانی زمین) روی هم قرار گرفته باشند، رویداد کلیک ابتدا در خوشه نشانگرها می‌چرخد، سپس برای سایر هم‌پوشانی‌ها یا شکل‌های قابل‌کلیک براساس مقادیر z-index آن‌ها راه‌اندازی می‌شود. با هر کلیک حداکثر یک رویداد راه‌اندازی می‌شود. به عبارت دیگر، کلیک به هم‌پوشانی‌ها یا شکل‌های دارای مقادیر z-index پایین‌تر منتقل نمی‌شود. درباره شاخص z نشانگر و رویدادهای کلیک بیشتر بخوانید.

چندضلعی‌ها

اشیاء 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)

      

جاوا

// 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() برای هرکدام از آن‌ها هر ۴ نقطه را برمی‌گرداند.

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

      

جاوا

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) را فراخوانی کنید. وقتی کاربر روی چندضلعی کلیک می‌کند، فراخوانی برگشتی onPolygonClick(Polygon) دریافت خواهید کرد.

توجه: اگر چند هم‌پوشانی یا شکل (نشانگر، چندخطی، چندضلعی، دایره، و/یا هم‌پوشانی زمین) روی هم قرار گرفته باشند، رویداد کلیک ابتدا در خوشه نشانگرها می‌چرخد، سپس برای سایر هم‌پوشانی‌ها یا شکل‌های قابل‌کلیک براساس مقادیر z-index آن‌ها راه‌اندازی می‌شود. با هر کلیک حداکثر یک رویداد راه‌اندازی می‌شود. به عبارت دیگر، کلیک به هم‌پوشانی‌ها یا شکل‌های دارای مقادیر z-index پایین‌تر منتقل نمی‌شود. درباره شاخص z نشانگر و رویدادهای کلیک بیشتر بخوانید.

حلقه

علاوه‌بر کلاس عمومی 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)

      

جاوا

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

      

جاوا

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

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

      

توجه: اگر چند هم‌پوشانی یا شکل (نشانگر، چندخطی، چندضلعی، دایره، و/یا هم‌پوشانی زمین) روی هم قرار گرفته باشند، رویداد کلیک ابتدا در خوشه نشانگرها می‌چرخد، سپس برای سایر هم‌پوشانی‌ها یا شکل‌های قابل‌کلیک براساس مقادیر z-index آن‌ها راه‌اندازی می‌شود. با هر کلیک حداکثر یک رویداد راه‌اندازی می‌شود. به عبارت دیگر، کلیک به هم‌پوشانی‌ها یا شکل‌های دارای مقادیر z-index پایین‌تر منتقل نمی‌شود. درباره شاخص z نشانگر و رویدادهای کلیک بیشتر بخوانید.

سفارشی‌سازی ظاهر

می‌توانید ظاهر شکل را هم قبل‌از اضافه شدن به نقشه (با مشخص کردن ویژگی موردنظر در شیء گزینه‌ها) و هم بعداز اضافه شدن به نقشه تغییر دهید. همچنین، برای همه ویژگی‌ها گیرنده ارائه شده است تا بتوانید به‌راحتی به وضعیت فعلی شکل دسترسی داشته باشید.

قطعه کد زیر یک چندخطی آبی ضخیم با بخش‌های ژئودزیک از ملبورن به پرت اضافه می‌کند. بخش‌های زیر این ویژگی‌ها را با جزئیات بیشتر توضیح می‌دهند.

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

      

نقشه به‌صورت زیر نشان داده می‌شود:

توجه: اگرچه اکثر این موارد را می‌توان برای هریک از شکل‌های شرح‌داده‌شده اعمال کرد، برخی‌از این ویژگی‌ها ممکن است برای شکل‌های خاصی منطقی نباشد (برای مثال، «چندخطی» نمی‌تواند رنگ پرکننده داشته باشد زیرا فضای داخلی ندارد).

رنگ ضرب‌قلم

رنگ خط حاشیه یک عدد صحیح ۳۲ بیتی آلفا-قرمز-سبز-آبی (ARGB) است که کدری و رنگ خط حاشیه شکل را مشخص می‌کند. این ویژگی را با فراخوانی *Options.strokeColor() (یا PolylineOptions.color() در مورد چندخطی) در شیء گزینه‌های شکل تنظیم کنید. اگر مشخص نشده باشد، رنگ پیش‌فرض ضرب‌قلم سیاه (Color.BLACK) است.

پس‌از افزودن شکل به نقشه، با فراخوانی getStrokeColor() (یا getColor() برای چندخطی) می‌توان به رنگ خط دسترسی پیدا کرد و با فراخوانی setStrokeColor() (setColor() for a polyline) می‌توان آن را تغییر داد.

رنگ پرکننده

رنگ پرکننده فقط برای چندضلعی‌ها و دایره‌ها اعمال می‌شود. این ویژگی برای چندخطی‌ها اعمال نمی‌شود زیرا آن‌ها فضای داخلی تعریف‌شده‌ای ندارند. برای چندضلعی، مناطق داخل حفره‌های آن بخشی از داخل چندضلعی نیستند و اگر رنگ پرکننده تنظیم شده باشد، رنگ‌آمیزی نخواهند شد.

رنگ پرکننده یک عدد صحیح ۳۲ بیتی آلفا-قرمز-سبز-آبی (ARGB) است که کدری و رنگ داخل شکل را مشخص می‌کند. این ویژگی را با فراخوانی *Options.fillColor() در شیء گزینه‌های شکل تنظیم کنید. اگر مشخص نشده باشد، رنگ پیش‌فرض ضرب‌قلم شفاف (Color.TRANSPARENT) است.

پس‌از اینکه شکل به نقشه اضافه شد، با فراخوانی getFillColor() می‌توان به رنگ پرکننده دسترسی پیدا کرد و با فراخوانی setFillColor() می‌توان آن را تغییر داد.

ضخامت خط

عرض خط، به‌صورت عدد اعشاری در پیکسل (px). وقتی نقشه بزرگ‌نمایی می‌شود، عرض مقیاس‌بندی نمی‌شود (یعنی شکل در همه سطوح بزرگ‌نمایی عرض قلم‌ضربه یکسانی خواهد داشت). این ویژگی را با فراخوانی *Options.strokeWidth() (یا PolylineOptions.width() برای چندخطی) در شیء گزینه شکل تنظیم کنید. اگر مشخص نشده باشد، عرض پیش‌فرض خط ۱۰ پیکسل است.

پس‌از افزودن شکل به نقشه، با فراخوانی getStrokeWidth() (یا getWidth() برای چندخطی) می‌توان به پهنای خط دسترسی پیدا کرد و با فراخوانی setStrokeWidth() (setWidth() for a polyline) می‌توان آن را تغییر داد.

الگوی خط پیرامونی

الگوی پیش‌فرض قلم برای چندخطی‌ها و برای طرح‌های کلی چندضلعی‌ها و دایره‌ها، خط ممتد است. می‌توانید الگوی قلم‌ضربه سفارشی از اشیاء PatternItem را مشخص کنید، که در آن هر مورد یک خط تیره، یک نقطه، یا یک فاصله است.

نمونه زیر الگوی چندخطی را روی دنباله تکراری نقطه، به‌دنبال آن فاصله‌ای به‌طول ۲۰ پیکسل، خط تیره به‌طول ۳۰ پیکسل، و فاصله ۲۰ پیکسلی دیگری تنظیم می‌کند.

Kotlin

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 را برای جایگزینی نوع اتصال فارسی ثابت پیش‌فرض مشخص کنید.

نمونه زیر نوع اتصال گرد را به چندخطی اعمال می‌کند:

Kotlin

polyline?.jointType = JointType.ROUND

      

جاوا

polyline.setJointType(JointType.ROUND);

      

نوع اتصال بر خمیدگی‌های داخلی خط تأثیر می‌گذارد. اگر خط دارای الگوی خطی باشد که شامل خط تیره است، نوع اتصال زمانی اعمال می‌شود که خط تیره روی اتصال قرار گیرد. انواع اتصال بر نقطه‌ها تأثیر نمی‌گذارد، زیرا نقطه‌ها همیشه دایره‌ای هستند.

سر خط

می‌توانید برای هر انتهای چندخطی، سبک Cap مشخص کنید. گزینه‌ها عبارت‌اند از: butt (پیش‌فرض)، square،‏ round، یا bitmap سفارشی. سبک را در PolylineOptions.startCap و PolylineOptions.endCap تنظیم کنید، یا از روش‌های مناسب گیرنده و تنظیم‌کننده استفاده کنید.

قطعه کد زیر یک کلاهک گرد را در ابتدای چندخطی مشخص می‌کند.

Kotlin

polyline?.startCap = RoundCap()

      

جاوا

polyline.setStartCap(new RoundCap());

      

قطعه کد زیر یک نقشه بیتی سفارشی برای کلاهک انتهایی مشخص می‌کند:

Kotlin

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

      

جاوا

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

      

وقتی از بیت‌مپ سفارشی استفاده می‌کنید، باید پهنای قلم‌ضربه مرجع را برحسب پیکسل مشخص کنید. میانای برنامه‌سازی کاربردی بیت‌مپ را براین‌اساس مقیاس‌بندی می‌کند. عرض خط مرجع، عرض خطی است که هنگام طراحی تصویر بیت‌مپ برای کلاهک در ابعاد اصلی تصویر استفاده کرده‌اید. عرض پیش‌فرض خط مرجع ۱۰ پیکسل است. نکته: برای تعیین پهنای خط مرجع، تصویر بیت‌مپ خود را با بزرگ‌نمایی ۱۰۰٪ در ویرایشگر تصویر باز کنید و پهنای خط موردنظر را نسبت‌به تصویر رسم کنید.

اگر از BitmapDescriptorFactory.fromResource() برای ایجاد نقشه بیتی استفاده می‌کنید، مطمئن شوید که از منبع مستقل از تراکم (nodpi) استفاده می‌کنید.

بخش‌های ژئودزیک

تنظیم ژئودزیک فقط برای چندخطی‌ها و چندضلعی‌ها اعمال می‌شود. این موضوع برای دایره‌ها اعمال نمی‌شود چون دایره‌ها به‌عنوان مجموعه‌ای از بخش‌ها تعریف نشده‌اند.

تنظیمات ژئودزیک تعیین می‌کند که پاره‌خط‌های بین رأس‌های متوالی چندخطی/ چندضلعی چگونه ترسیم شوند. بخش‌های ژئودزیک بخش‌هایی هستند که کوتاه‌ترین مسیر را در امتداد سطح زمین (یک کره) دنبال می‌کنند و اغلب به‌صورت خطوط منحنی روی نقشه‌ای با تصویر مرکاتور ظاهر می‌شوند. بخش‌های غیرژئودزیک به‌صورت خطوط مستقیم روی نقشه کشیده می‌شوند.

این ویژگی را با فراخوانی *Options.geodesic() در شیء گزینه شکل تنظیم کنید، که در آن true نشان می‌دهد بخش‌ها باید به‌صورت ژئودزیک ترسیم شوند و false نشان می‌دهد بخش‌ها باید به‌صورت خطوط مستقیم ترسیم شوند. اگر مشخص نشده باشد، پیش‌فرض بخش‌های غیرژئودزیک (false) است.

پس‌از اضافه شدن شکل به نقشه، با فراخوانی isGeodesic() می‌توان به تنظیمات ژئودزیک دسترسی پیدا کرد و با فراخوانی setGeodesic() می‌توان آن را تغییر داد.

شاخص Z

شاخص z ترتیب پشته این شکل را نسبت به سایر هم‌پوشانی‌ها (شکل‌های دیگر، هم‌پوشانی‌های زمین، و هم‌پوشانی‌های کاشی) در نقشه مشخص می‌کند. یک هم‌پوشانی با شاخص z بالا، بالاتر از هم‌پوشانی‌های با شاخص z پایین‌تر ترسیم می‌شود. دو هم‌پوشانی با z-index یکسان به ترتیب دلخواه ترسیم می‌شوند.

توجه داشته باشید که نشانگرها همیشه بالای سایر هم‌پوشانی‌ها ترسیم می‌شوند، صرف‌نظر از شاخص z سایر هم‌پوشانی‌ها.

این ویژگی را با فراخوانی *Options.zIndex() در شیء گزینه‌های شکل تنظیم کنید. اگر مشخص نشده باشد، z-index پیش‌فرض 0 است. پس‌از افزودن شکل به نقشه، با فراخوانی getZIndex() می‌توان به z-index دسترسی پیدا کرد و با فراخوانی 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"

      

جاوا

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 برای شکل نشان دهد.