شکل‌ها

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

«میانای برنامه‌سازی کاربردی Google Maps ویژه Android» روش‌های ساده‌ای برای افزودن شکل به نقشه‌ها دراختیارتان قرار می‌دهد تا بتوانید آن‌ها را برای برنامه‌تان سفارشی‌سازی کنید.

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

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

نمونه‌های کد

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

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

• CircleDemoActivity (Java / Kotlin): Circle
• PolygonDemoActivity (Java / Kotlin): چندضلعی
• PolylineDemoActivity (Java / Kotlin): چندضلعی

چندخطی‌ها

کلاس Polyline مجموعه‌ای از بخش‌های خط متصل را روی نقشه تعریف می‌کند. شیء Polyline از مجموعه‌ای از مکان‌های LatLng تشکیل شده است و مجموعه‌ای از بخش‌های خطی ایجاد می‌کند که این مکان‌ها را به‌صورت توالی مرتب‌شده به هم متصل می‌کند.

این ویدیو ایده‌هایی درباره نحوه کمک به کاربران برای رسیدن به مقصدشان ارائه می‌دهد، بااستفاده از چندخطی‌ها برای ترسیم مسیر روی نقشه.

برای ایجاد «چندخطی»، ابتدا PolylineOptions شیئی ایجاد کنید و نقطه‌هایی به آن اضافه کنید. نقطه‌ها نشان‌دهنده نقطه‌ای روی سطح زمین هستند، و به‌صورت شیء LatLng بیان می‌شوند. پاره‌خط‌ها بین نقاط براساس ترتیبی که آن‌ها را به شیء PolylineOptions اضافه می‌کنید رسم می‌شوند.

برای افزودن نقاط به شیء PolylineOptions، با PolylineOptions.add() تماس بگیرید. توجه داشته باشید که این روش تعداد متغیری از پارامترها را می‌گیرد، بنابراین می‌توانید چند نقطه را به‌طور هم‌زمان اضافه کنید (اگر نقاط ازقبل در فهرست باشند، می‌توانید PolylineOptions.addAll(Iterable<LatLng>) را نیز فراخوانی کنید).

سپس می‌توانید با فراخوانی GoogleMap.addPolyline(PolylineOptions)، چندخطی را به نقشه اضافه کنید. روش یک شیء Polyline برمی‌گرداند که با آن می‌توانید چندخطی را در زمان دیگری تغییر دهید.

تکه‌کد زیر نحوه افزودن مستطیل به نقشه را نشان می‌دهد:

Kotlin

// Instantiates a new Polyline object and adds points to define a rectangle
val polylineOptions = PolylineOptions()
    .add(LatLng(37.35, -122.0))
    .add(LatLng(37.45, -122.0)) // North of the previous point, but at the same longitude
    .add(LatLng(37.45, -122.2)) // Same latitude, and 30km to the west
    .add(LatLng(37.35, -122.2)) // Same longitude, and 16km to the south
    .add(LatLng(37.35, -122.0)) // Closes the polyline.

// Get back the mutable Polyline
val polyline = map.addPolyline(polylineOptions)
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
}

      

جاوا

// 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() را فراخوانی کنید و فهرست جدیدی از نقاط برای طرح کلی چندضلعی ارائه دهید.

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

تکمیل خودکار چندضلعی

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

دو چندضلعی زیر معادل هستند و فراخوانی 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)
)
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
}

      

جاوا

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 آن‌ها راه‌اندازی می‌شود. حداکثر یک رویداد در هر کلیک راه‌اندازی می‌شود. به عبارت دیگر، کلیک به هم‌پوشانی‌ها یا شکل‌های دارای مقادیر z-index پایین‌تر منتقل نمی‌شود. درباره شاخص z نشانگر و رویدادهای کلیک بیشتر بخوانید.

حلقه

علاوه‌بر کلاس عمومی Polygon، Maps API شامل کلاس‌های خاصی برای اشیاء Circle نیز می‌شود تا ساخت آن‌ها را ساده‌تر کند.

برای ساختن دایره، باید دو ویژگی زیر را مشخص کنید:

• ‫center به‌عنوان LatLng.
• radius به متر.

سپس دایره‌ای به‌عنوان مجموعه همه نقاط روی سطح زمین تعریف می‌شود که radius متر از center داده‌شده فاصله دارند. به‌دلیل نحوه تصویرسازی کروی در سطح صاف بااستفاده از طرح «مرکاتور» که در «میانای برنامه‌سازی کاربردی Maps» استفاده می‌شود، وقتی دایره نزدیک خط استوا باشد، در نقشه تقریباً به‌صورت دایره‌ای کامل نشان داده می‌شود، و هرچه دایره از خط استوا دورتر شود، شکل آن (در صفحه) بیشتر غیردایره‌ای می‌شود.

برای تغییر شکل دایره پس‌از اضافه شدن، می‌توانید 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
}

      

جاوا

// 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 مشخص کنید. گزینه‌ها عبارت‌اند از ته گرد (پیش‌فرض)، مربعی، گرد، یا بیت‌مپ سفارشی. سبک را در 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-index سایر هم‌پوشانی‌ها.

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