نشانگرها

پلاتفرم را انتخاب کنید: 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)
val marker = map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney")
)
marker?.let {
    val position = it.position
    val title = it.title
    val snippet = it.snippet
    val isDraggable = it.isDraggable
    val isFlat = it.isFlat
    val isVisible = it.isVisible
    val alpha = it.alpha
    val rotation = it.rotation
    val zIndex = it.zIndex
}
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);
Marker marker = 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)
)
map.moveCamera(com.google.android.gms.maps.CameraUpdateFactory.newLatLngZoom(perthLocation, 10f))

جاوا

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(
    new MarkerOptions()
        .position(perthLocation)
        .draggable(true));
map.moveCamera(com.google.android.gms.maps.CameraUpdateFactory.newLatLngZoom(perthLocation, 10f));

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

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

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

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

موقعیت (الزامی)
مقدار LatLng برای موقعیت نشانگر روی نقشه. این تنها ویژگی الزامی برای شیء Marker است.
لنگر
نقطه‌ای در تصویر که در موقعیت LatLng نشانگر قرار می‌گیرد. این گزینه به‌طور پیش‌فرض در وسط پایین تصویر قرار دارد.
آلفا
ماتی نشانگر را تنظیم می‌کند. پیش‌فرض ۱.۰ است.
عنوان
رشته‌ای که وقتی کاربر روی نشانگر تک‌ضرب می‌زند در پنجره اطلاعات نمایش داده می‌شود.
کد آماده
نوشتار اضافی که زیر عنوان نمایش داده می‌شود.
نماد
بیت‌مپ که به‌جای تصویر نشانگر پیش‌فرض نمایش داده می‌شود.
کشیدنی
اگر می‌خواهید به کاربر اجازه دهید نشانگر را جابه‌جا کند، روی 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)
نشانگر سفارشی از مسیر فایل مطلق تصویر «بیت‌مپ» ایجاد می‌کند.
fromResource(int resourceId)
بااستفاده از شناسه منبع تصویر «بیت‌مپ»، نشانگر سفارشی ایجاد می‌کند.

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

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» به شما امکان می‌دهد به رویدادهای نشانگر گوش دهید و به آن‌ها پاسخ دهید. برای گوش دادن به این رویدادها، باید شنونده مربوطه را روی شیء GoogleMap که نشانگرها به آن تعلق دارند تنظیم کنید. وقتی رویداد در یکی از نشانگرهای روی نقشه رخ می‌دهد، فراخوانی برگشتی شنونده با شیء Marker مربوطه که به‌عنوان پارامتر ارسال شده است فراخوانی می‌شود. برای مقایسه این شیء Marker با مرجع خودتان به شیء Marker، باید از equals() استفاده کنید نه ==.

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

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

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

تأثیر شاخص z بر رویدادهای کلیک:

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

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

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