المحدِّدات

اختيار النظام الأساسي: Android‏ iOS‏ JavaScript‏

تحدّد العلامات المواقع الجغرافية على الخريطة. يستخدم المحدّد التلقائي رمزًا عاديًا، وهو شائع في مظهر "خرائط Google". يمكنك تغيير لون الرمز أو الصورة أو نقطة الارتساء من خلال واجهة برمجة التطبيقات. العلامات هي عناصر من النوع Marker، وتتم إضافتها إلى الخريطة باستخدام الطريقة GoogleMap.addMarker(markerOptions).

تم تصميم العلامات لتكون تفاعلية. وتتلقّى أحداث click تلقائيًا، وغالبًا ما يتم استخدامها مع متتبِّعات الأحداث لإظهار نوافذ المعلومات. يسمح ضبط السمة draggable لعلامة على true للمستخدم بتغيير موضع العلامة. استخدِم الضغط مع الاستمرار لتفعيل إمكانية تحريك محدِّد الموقع.

عندما ينقر المستخدم على علامة، يظهر شريط أدوات الخريطة تلقائيًا في أسفل يسار الخريطة، ما يتيح للمستخدم الوصول السريع إلى تطبيق "خرائط Google" للأجهزة الجوّالة. ويمكنك إيقاف شريط الأدوات. لمزيد من المعلومات، يُرجى الاطّلاع على دليل عناصر التحكّم.

إضافة علامة

يوضّح المثال التالي كيفية إضافة علامة إلى خريطة. يتم إنشاء العلامة عند الإحداثيات -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.

نقطة إرساء

النقطة على الصورة التي سيتم وضعها في موضع LatLng للعلامة. يتم ضبط هذا الخيار تلقائيًا على منتصف الجزء السفلي من الصورة.

إصدار أولي

يضبط مستوى تعتيم العلامة. القيمة التلقائية هي 1.0.

العنوان

سلسلة يتم عرضها في نافذة المعلومات عندما ينقر المستخدم على العلامة.

المقتطف

نص إضافي يظهر أسفل العنوان

رمز

صورة نقطية يتم عرضها بدلاً من صورة العلامة التلقائية.

عنصر قابل للسحب

اضبط القيمة على true إذا أردت السماح للمستخدم بنقل العلامة. القيمة التلقائية هي false.

Visible

اضبط القيمة على 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). تدرج اللون هو قيمة بين 0 و360، تمثل نقاطًا على عجلة الألوان.

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()‎. يجب تحديد قيمة ألفا كعدد عشري بين 0.0 و1.0، حيث يشير الرقم 0 إلى شفافية كاملة والرقم 1 إلى تعتيم كامل.

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)

تنشئ هذه الدالة محدّد موقع مخصّصًا باستخدام اسم صورة نقطية في مجلّد الموارد.

fromBitmap(Bitmap image)

تنشئ هذه الطريقة محدّد موقع مخصّصًا من صورة نقطية.

fromFile(String fileName)

يتم إنشاء رمز مخصّص باستخدام اسم ملف صورة نقطية في وحدة التخزين الداخلية.

fromPath(String absolutePath)

تنشئ هذه الدالة محدّد موقع مخصّصًا من مسار ملف مطلق لصورة نقطية.

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()) يتم قياس التدوير بالدرجات في اتجاه عقارب الساعة من الموضع التلقائي. عندما يكون محدّد الموقع مسطّحًا على الخريطة، يكون الموضع التلقائي هو الشمال. عندما لا تكون العلامة مسطّحة، يشير الموضع التلقائي إلى الأعلى ويكون الدوران بحيث تكون العلامة مواجهة للكاميرا دائمًا.

يؤدي المثال أدناه إلى تدوير العلامة بمقدار 90 درجة. يؤدي ضبط نقطة الارتساء على 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-index لعلامة

يحدّد الفهرس z ترتيب تكديس هذه العلامة بالنسبة إلى العلامات الأخرى على الخريطة. يتم رسم علامة ذات فهرس z مرتفع فوق العلامات ذات فهارس z المنخفضة. القيمة التلقائية لـ z-index هي 0.

اضبط z-index في عنصر خيارات العلامة من خلال استدعاء MarkerOptions.zIndex()، كما هو موضّح في مقتطف الرمز التالي:

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

      

يمكنك الوصول إلى فهرس z الخاص بالعلامة من خلال استدعاء Marker.getZIndex()، ويمكنك تغييره من خلال استدعاء Marker.setZIndex().

يتم دائمًا رسم العلامات فوق طبقات المربّعات والتراكبات الأخرى غير العلامات (التراكبات الأرضية والخطوط المتعدّدة والمضلّعات والأشكال الأخرى) بغض النظر عن مؤشر z للتراكبات الأخرى. تُعتبر العلامات فعليًا في مجموعة مؤشر z منفصلة مقارنةً بالعناصر المركّبة الأخرى.

يمكنك الاطّلاع على تأثير z-index في الأحداث الناتجة عن النقر أدناه.

التعامل مع أحداث العلامات

تتيح لك واجهة برمجة التطبيقات Maps API الاستماع إلى أحداث العلامات والاستجابة لها. للاستماع إلى هذه الأحداث، يجب ضبط المستمع المقابل على كائن GoogleMap الذي تنتمي إليه العلامات. عند وقوع الحدث على إحدى العلامات على الخريطة، سيتم استدعاء دالة الاستدعاء الخاصة بالمستمع مع تمرير كائن Marker المقابل كمَعلمة. لمقارنة عنصر Marker هذا بمرجعك الخاص لعنصر Marker، يجب استخدام equals() وليس ==.

يمكنك الاستماع إلى الأحداث التالية:

• أحداث النقر على العلامات
• أحداث سحب العلامات
• أحداث النقر على نافذة المعلومات

الأحداث الناتجة عن النقر على العلامات

يمكنك استخدام OnMarkerClickListener للاستماع إلى الأحداث الناتجة عن النقر على العلامة. لضبط هذا المستمع على الخريطة، يمكنك استدعاء GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). عندما ينقر المستخدم على علامة، سيتم استدعاء onMarkerClick(Marker) وسيتم تمرير العلامة كوسيطة. تعرض هذه الطريقة قيمة منطقية تشير إلى ما إذا كنت قد استهلكت الحدث (أي أنّك تريد منع السلوك التلقائي). إذا عرضت القيمة false، سيتم تنفيذ الإجراء التلقائي بالإضافة إلى الإجراء المخصّص. يتمثّل السلوك التلقائي لحدث النقر على العلامة في عرض نافذة المعلومات (إذا كانت متاحة) وتحريك الكاميرا بحيث تكون العلامة في منتصف الخريطة.

تأثير z-index في الأحداث الناتجة عن النقر:

• عندما ينقر مستخدم على مجموعة من العلامات، يتم تشغيل حدث ناتج عن النقر للعلامة التي تحتوي على أعلى مؤشر z.
• يتم بدء حدث واحد على الأكثر لكل نقرة. بمعنى آخر، لا يتم تمرير النقرة إلى العلامات أو العناصر المركّبة الأخرى التي لها قيم z-index أقل.
• يؤدي النقر على مجموعة من العلامات إلى تكرار النقرات اللاحقة خلال المجموعة، واختيار كل منها بدوره. يتم تحديد ترتيب الدورة أولاً حسب قيمة z-index، ثم حسب مدى القرب من نقطة النقر.
• إذا نقر المستخدم خارج نطاق المجموعة، تعيد واجهة برمجة التطبيقات احتساب المجموعة وتعيد ضبط حالة دورة النقر لتبدأ من البداية.
• تُعتبر العلامات فعليًا في مجموعة مؤشر Z منفصلة مقارنةً بالتراكبات أو الأشكال الأخرى (الخطوط المتعدّدة و/أو المضلّعات و/أو الدوائر و/أو التراكبات الأرضية)، بغض النظر عن مؤشر Z للتراكبات الأخرى. في حال تراكب عدة علامات أو تراكبات أو أشكال فوق بعضها، يتم تدوير الحدث الناتج عن النقر من خلال مجموعة العلامات أولاً.

أحداث سحب العلامات

يمكنك استخدام OnMarkerDragListener للاستماع إلى أحداث السحب على علامة. لضبط هذا المستمع على الخريطة، يمكنك استدعاء GoogleMap.setOnMarkerDragListener. لسحب علامة، يجب أن يضغط المستخدم مع الاستمرار على العلامة. عندما يرفع المستخدم إصبعه عن الشاشة، ستبقى العلامة في هذا الموضع. عند سحب علامة، يتم استدعاء onMarkerDragStart(Marker) في البداية. أثناء سحب العلامة، يتم استدعاء onMarkerDrag(Marker) باستمرار. في نهاية عملية السحب، يتم استدعاء onMarkerDragEnd(Marker). يمكنك الحصول على موضع العلامة في أي وقت من خلال استدعاء Marker.getPosition().

ملاحظة: لا يمكن سحب العلامة تلقائيًا. يجب ضبط العلامة بشكل صريح لتكون قابلة للسحب قبل أن يتمكّن المستخدم من سحبها. ويمكن إجراء ذلك إما باستخدام MarkerOptions.draggable(boolean) قبل إضافته إلى الخريطة، أو Marker.setDraggable(boolean) بعد إضافته إلى الخريطة.