نشانگرها

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

نشانگرها مکان‌ها را روی نقشه مشخص می‌کنند. نشانگر پیش‌فرض از نماد استانداردی استفاده می‌کند که در ظاهر و حس Google Maps رایج است. می‌توان رنگ، تصویر، یا نقطه لنگر نماد را ازطریق API تغییر داد. نشانگرها اشیایی از نوع Marker هستند و با روش GoogleMap.addMarker(markerOptions) به نقشه اضافه می‌شوند.

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

به‌طور پیش‌فرض، وقتی کاربر روی نشانگری تک‌ضرب می‌زند، نوارابزار نقشه در پایین سمت چپ نقشه ظاهر می‌شود و به کاربر امکان می‌دهد سریعاً به برنامه تلفن همراه Google Maps دسترسی پیدا کند. می‌توانید نوارابزار را غیرفعال کنید. برای اطلاعات بیشتر، راهنمای کنترل‌ها را ببینید.

نشانگر اضافه کنید

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

Kotlin

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
val sydney = LatLng(-33.852, 151.211)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

جاوا

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
LatLng sydney = new LatLng(-33.852, 151.211);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

نمایش اطلاعات تکمیلی درباره نشانگر

یک نیاز رایج این است که وقتی کاربر روی نشانگری در نقشه تک‌ضرب می‌زند، اطلاعات بیشتری درباره مکان یا موقعیت نشان داده شود. راهنمای پنجره‌های اطلاعات را ببینید.

مرتبط کردن داده‌ها با نشانگر

می‌توانید شیء داده دلخواهی را بااستفاده از Marker.setTag() با نشانگر ذخیره کنید، و شیء داده را بااستفاده از Marker.getTag() بازیابی کنید. نمونه زیر نشان می‌دهد که چگونه می‌توانید تعداد دفعاتی را که روی یک نشانگر کلیک شده است بااستفاده از برچسب‌ها بشمارید:

Kotlin

val PERTH = LatLng(-31.952854, 115.857342)
val SYDNEY = LatLng(-33.87365, 151.20689)
val BRISBANE = LatLng(-27.47093, 153.0235)

val markerPerth = map.addMarker(
    MarkerOptions()
        .position(PERTH)
        .title("Perth"),
)
markerPerth?.tag = 0

val markerSydney = map.addMarker(
    MarkerOptions()
        .position(SYDNEY)
        .title("Sydney"),
)
markerSydney?.tag = 0

val markerBrisbane = map.addMarker(
    MarkerOptions()
        .position(BRISBANE)
        .title("Brisbane"),
)
markerBrisbane?.tag = 0

// Set a listener for marker click.
map.setOnMarkerClickListener { marker ->
    // Retrieve the data from the marker.
    val clickCount = marker.tag as? Int

    // Check if a click count was set, then display the click count.
    clickCount?.let {
        val newClickCount = it + 1
        marker.tag = newClickCount
        Toast.makeText(
            context,
            "${marker.title} has been clicked $newClickCount times.",
            Toast.LENGTH_SHORT,
        ).show()
    }

    // Return false to indicate default behavior.
    false
}

      

جاوا

final LatLng PERTH = new LatLng(-31.952854, 115.857342);
final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

Marker markerPerth = map.addMarker(new MarkerOptions().position(PERTH).title("Perth"));
markerPerth.setTag(0);

Marker markerSydney = map.addMarker(new MarkerOptions().position(SYDNEY).title("Sydney"));
markerSydney.setTag(0);

Marker markerBrisbane =
        map.addMarker(new MarkerOptions().position(BRISBANE).title("Brisbane"));
markerBrisbane.setTag(0);

// Set a listener for marker click.
map.setOnMarkerClickListener(
        new GoogleMap.OnMarkerClickListener() {
            @Override
            public boolean onMarkerClick(final Marker marker) {
                // Retrieve the data from the marker.
                Integer clickCount = (Integer) marker.getTag();

                // Check if a click count was set, then display the click count.
                if (clickCount != null) {
                    clickCount = clickCount + 1;
                    marker.setTag(clickCount);
                    Toast.makeText(
                                    context,
                                    marker.getTitle()
                                            + " has been clicked "
                                            + clickCount
                                            + " times.",
                                    Toast.LENGTH_SHORT)
                            .show();
                }

                // Return false to indicate default behavior should occur.
                return false;
            }
        });

      

در اینجا چند نمونه از سناریوهایی آورده شده است که در آن‌ها ذخیره و بازیابی داده‌ها با نشانگرها مفید است:

• برنامه شما ممکن است انواع مختلفی از نشانگرها را ارائه دهد و شما بخواهید هنگام کلیک کردن کاربر روی آن‌ها، رفتار متفاوتی با آن‌ها داشته باشید. برای انجام این کار، می‌توانید String را با نشانگری که نوع را نشان می‌دهد ذخیره کنید.
• ممکن است با سیستمی سروکار داشته باشید که شناسه‌های رکورد یکتا دارد، که در آن نشانگرها نشان‌دهنده رکوردهای خاصی در آن سیستم هستند.
• داده‌های نشانگر ممکن است اولویتی را نشان دهد که هنگام تصمیم‌گیری درباره شاخص z نشانگر استفاده می‌شود.

کشیدنی کردن نشانگر

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

نشانگرها به‌طور پیش‌فرض کشیدنی نیستند. باید صریحاً نشانگر را با MarkerOptions.draggable(boolean) قبل‌از افزودن آن به نقشه یا با Marker.setDraggable(boolean) پس‌از افزودن آن به نقشه، به‌عنوان کشیدنی تنظیم کنید. همان‌طور که در رویدادهای کشیدن نشانگر شرح داده شده است، می‌توانید رویدادهای کشیدن را در نشانگر گوش دهید.

قطعه کد زیر یک نشانگر کشیدنی در پرت، استرالیا اضافه می‌کند.

Kotlin

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .draggable(true),
)

      

جاوا

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(new MarkerOptions().position(perthLocation).draggable(true));

      

سفارشی‌سازی نشانگر

این ویدیو روش‌های استفاده از نشانگرها را برای دیداری‌سازی مکان‌ها روی نقشه نشان می‌دهد.

نشانگرها می‌توانند تصویر سفارشی‌ای را برای نمایش به‌جای نماد پیش‌فرض تعریف کنند. تعریف نماد شامل تنظیم تعدادی ویژگی است که بر رفتار بصری نشانگر تأثیر می‌گذارد.

نشانگرها از سفارشی‌سازی ازطریق ویژگی‌های زیر پشتیبانی می‌کنند:

موقعیت (الزامی)

مقدار LatLng برای موقعیت نشانگر روی نقشه. این تنها ویژگی الزامی برای شیء Marker است.

لنگر

نقطه‌ای روی تصویر که در موقعیت طول و عرض جغرافیایی نشانگر قرار خواهد گرفت. این گزینه به‌طور پیش‌فرض در وسط پایین تصویر قرار دارد.

آلفا

ماتی نشانگر را تنظیم می‌کند. پیش‌فرض ۱.۰ است.

عنوان

رشته‌ای که وقتی کاربر روی نشانگر تک‌ضرب می‌زند در پنجره اطلاعات نمایش داده می‌شود.

کد آماده

نوشتار اضافی که زیر عنوان نمایش داده می‌شود.

نماد

نگاشت بیتی که به‌جای تصویر نشانگر پیش‌فرض نمایش داده می‌شود.

کشیدنی

اگر می‌خواهید به کاربر اجازه دهید نشانگر را جابه‌جا کند، روی true تنظیم کنید. پیش‌فرض‌ها به false.

قابل مشاهده

برای نامرئی کردن نشانگر، روی false تنظیم کنید. پیش‌فرض‌ها به true.

جهت تخت یا بیلبورد

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

چرخش

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

قطعه کد زیر یک نشانگر ساده با نماد پیش‌فرض ایجاد می‌کند.

Kotlin

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation),
)

      

جاوا

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(new MarkerOptions().position(melbourneLocation));

      

سفارشی‌سازی رنگ نشانگر

می‌توانید رنگ تصویر نشانگر پیش‌فرض را با ارسال شیء BitmapDescriptor به روش icon()‎ سفارشی‌سازی کنید. می‌توانید از مجموعه‌ای از رنگ‌های ازپیش‌تعریف‌شده در شیء BitmapDescriptorFactory استفاده کنید یا بااستفاده از روش BitmapDescriptorFactory.defaultMarker(float hue)، رنگ نشانگر سفارشی تنظیم کنید. فام مقداری بین ۰ تا ۳۶۰ است که نقاط روی چرخه رنگ را نشان می‌دهد.

Kotlin

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)),
)

      

جاوا

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(
                new MarkerOptions()
                        .position(melbourneLocation)
                        .icon(
                                BitmapDescriptorFactory.defaultMarker(
                                        BitmapDescriptorFactory.HUE_AZURE)));

      

سفارشی‌سازی کردن میزان ماتی نشانگر

می‌توانید میزان شفافیت نشانگر را با روش MarkerOptions.alpha()‎ کنترل کنید. آلفا باید به‌صورت عدد اعشاری بین ۰٫۰ و ۱٫۰ مشخص شود، که ۰ کاملاً شفاف و ۱ کاملاً مات است.

Kotlin

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .alpha(0.7f),
)

      

جاوا

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(new MarkerOptions().position(melbourneLocation).alpha(0.7f));

      

سفارشی‌سازی کردن تصویر نشانگر

می‌توانید تصویر نشانگر پیش‌فرض را با تصویر نشانگر سفارشی که اغلب نماد نامیده می‌شود جایگزین کنید. نمادهای سفارشی همیشه به‌عنوان BitmapDescriptor تنظیم می‌شوند و بااستفاده از یکی از روش‌های موجود در کلاس BitmapDescriptorFactory تعریف می‌شوند.

fromAsset(String assetName)

نشانگر سفارشی را بااستفاده از نام تصویر Bitmap در پوشه دارایی‌ها ایجاد می‌کند.

fromBitmap(Bitmap image)

نشانگر سفارشی از تصویر Bitmap ایجاد می‌کند.

fromFile(String fileName)

نماد سفارشی‌ای بااستفاده از نام فایل تصویری Bitmap واقع در حافظه داخلی ایجاد می‌کند.

fromPath(String absolutePath)

نشانگر سفارشی را از مسیر فایل مطلق تصویر Bitmap ایجاد می‌کند.

fromResource(int resourceId)

نشانگر سفارشی را بااستفاده از شناسه منبع تصویر Bitmap ایجاد می‌کند.

قطعه کد زیر نشانگری با نماد سفارشی ایجاد می‌کند.

Kotlin

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .title("Melbourne")
        .snippet("Population: 4,137,400")
        .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)),
)

      

جاوا

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(
                new MarkerOptions()
                        .position(melbourneLocation)
                        .title("Melbourne")
                        .snippet("Population: 4,137,400")
                        .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

      

مسطح کردن نشانگر

نمادهای نشانگر معمولاً نسبت به صفحه ترسیم می‌شوند؛ چرخاندن، کج کردن، یا بزرگ‌نمایی نقشه جهت نشانگر را تغییر نمی‌دهد. می‌توانید جهت نشانگر را به‌صورت تخت روی زمین تنظیم کنید. نشانگرهایی که به این روش جهت‌گیری شده‌اند، هنگام چرخش نقشه می‌چرخند و هنگام کج شدن نقشه، پرسپکتیو را تغییر می‌دهند. نشانگرهای تخت هنگام بزرگ‌نمایی یا کوچک‌نمایی نقشه، اندازه خود را حفظ می‌کنند.

برای تغییر جهت نشانگر، ویژگی flat نشانگر را روی true تنظیم کنید.

Kotlin

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .flat(true),
)

      

جاوا

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(new MarkerOptions().position(perthLocation).flat(true));

      

چرخاندن نشانگر

می‌توانید نشانگر را با Marker دور نقطه لنگر آن بچرخانید.روش setRotation(). چرخش با درجه ساعت‌گرد از موقعیت پیش‌فرض اندازه‌گیری می‌شود. وقتی نشانگر روی نقشه صاف است، موقعیت پیش‌فرض شمال است. وقتی نشانگر تخت نباشد، موقعیت پیش‌فرض آن رو به بالا است و چرخش آن به‌گونه‌ای است که نشانگر همیشه رو به دوربین است.

مثال زیر نشانگر را ۹۰ درجه می‌چرخاند. تنظیم نقطه اتکا روی 0.5,0.5 باعث می‌شود نشانگر به‌جای پایه، حول مرکزش بچرخد.

Kotlin

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .anchor(0.5f, 0.5f)
        .rotation(90.0f),
)

      

جاوا

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth =
        map.addMarker(
                new MarkerOptions()
                        .position(perthLocation)
                        .anchor(0.5f, 0.5f)
                        .rotation(90.0f));

      

شاخص z نشانگر

شاخص z ترتیب پشته این نشانگر را نسبت به نشانگرهای دیگر روی نقشه مشخص می‌کند. نشانگر با شاخص z بالا روی نشانگرهای با شاخص z پایین‌تر ترسیم می‌شود. مقدار پیش‌فرض z-index برابر با 0 است.

با فراخوانی MarkerOptions.zIndex()، شاخص z را در شیء گزینه‌های نشانگر تنظیم کنید، همان‌طور که در تکه‌کد زیر نشان داده شده است:

Kotlin

map.addMarker(
    MarkerOptions()
        .position(LatLng(10.0, 10.0))
        .title("Marker z1")
        .zIndex(1.0f),
)

      

جاوا

map.addMarker(
        new MarkerOptions().position(new LatLng(10, 10)).title("Marker z1").zIndex(1.0f));

      

با فراخوانی Marker.getZIndex() می‌توانید به شاخص z نشانگر دسترسی پیدا کنید و با فراخوانی Marker.setZIndex() می‌توانید آن را تغییر دهید.

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

درباره تأثیر z-index بر رویدادهای کلیک در زیر بخوانید.

رسیدگی به رویدادهای نشانگر

Maps API به شما امکان می‌دهد به رویدادهای نشانگر گوش دهید و به آن‌ها پاسخ دهید. برای گوش دادن به این رویدادها، باید شنونده مربوطه را روی شیء GoogleMap که نشانگرها به آن تعلق دارند تنظیم کنید. وقتی رویداد در یکی از نشانگرهای روی نقشه رخ می‌دهد، فراخوانی برگشتی شنونده با شیء Marker مربوطه که به‌عنوان پارامتر ارسال شده است فراخوانی می‌شود. برای مقایسه این شیء Marker با مرجع خودتان به شیء Marker، باید از equals() استفاده کنید نه ==.

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

• رویدادهای کلیک نشانگر
• رویدادهای کشیدن نشانگر
• رویدادهای کلیک پنجره اطلاعات

رویدادهای کلیک نشانگر

می‌توانید از OnMarkerClickListener برای گوش دادن به رویدادهای کلیک روی نشانگر استفاده کنید. برای تنظیم این شنونده در نقشه، GoogleMap.setOnMarkerClickListener(OnMarkerClickListener) را فراخوانی کنید. وقتی کاربر روی نشانگری کلیک می‌کند، onMarkerClick(Marker) فراخوانی می‌شود و نشانگر به‌عنوان آرگومان ارسال می‌شود. این روش یک مقدار بولی برمی‌گرداند که نشان می‌دهد آیا رویداد را مصرف کرده‌اید (یعنی می‌خواهید رفتار پیش‌فرض را سرکوب کنید). اگر false را برگرداند، علاوه‌بر رفتار سفارشی شما، رفتار پیش‌فرض نیز رخ خواهد داد. رفتار پیش‌فرض برای رویداد کلیک روی نشانگر، نمایش پنجره اطلاعات آن (درصورت وجود) و حرکت دادن دوربین به‌گونه‌ای است که نشانگر در مرکز نقشه قرار گیرد.

تأثیر z-index بر رویدادهای کلیک:

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

رویدادهای کشیدن نشانگر

می‌توانید از OnMarkerDragListener برای گوش دادن به رویدادهای کشیدن روی نشانگر استفاده کنید. برای تنظیم این شنونده در نقشه، GoogleMap.setOnMarkerDragListener را فراخوانی کنید. برای کشیدن نشانگر، کاربر باید روی نشانگر فشار طولانی دهد. وقتی کاربر انگشتش را از روی صفحه برمی‌دارد، نشانگر در همان موقعیت باقی می‌ماند. وقتی نشانگری کشیده می‌شود، onMarkerDragStart(Marker) در ابتدا فراخوانی می‌شود. وقتی نشانگر کشیده می‌شود، onMarkerDrag(Marker) به‌طور مداوم فراخوانی می‌شود. در پایان کشیدن، onMarkerDragEnd(Marker) فراخوانی می‌شود. هرزمان بخواهید می‌توانید با فراخوانی Marker.getPosition()، موقعیت نشانگر را دریافت کنید.

توجه: به‌طور پیش‌فرض، نشانگر کشیدنی نیست. نشانگر باید صریحاً تنظیم شود تا کشیدنی باشد و کاربر بتواند آن را بکشد. این کار را می‌توان با MarkerOptions.draggable(boolean) قبل‌از افزودن آن به نقشه، یا Marker.setDraggable(boolean) پس‌از افزودن آن به نقشه انجام داد.