المحدِّدات

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

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

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

إضافة علامة

يعرض المثال التالي كيفية إضافة علامة إلى خريطة. يتم إنشاء العلامة عند الإحداثيات -33.852,151.211 (سيدني، أستراليا)، وتعرض السلسلة "علامة في سيدني" في نافذة معلوماتية عند النقر عليها.

// 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(). يعرض المثال أدناه كيفية حساب عدد مرّات النقر على علامة باستخدام العلامات:

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-index للعلامة.

جعل العلامة قابلة للسحب

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

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

يضيف المقتطف أدناه علامة قابلة للسحب في بيرث، أستراليا.

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 للـ علامة. ويكون الإعداد التلقائي في منتصف أسفل الصورة.

إصدار أولي

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

العنوان

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

المقتطف

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

رمز

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

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

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

Visible

اضبط هذه السمة على false لجعل العلامة غير مرئية. القيمة التلقائية هي true.

الاتجاه المسطّح أو اتجاه لوحة الإعلانات

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

تدوير

اتجاه العلامة، محدّد بالدرجات في اتجاه عقارب الساعة يتغيّر الموضع التلقائي إذا كانت العلامة مسطّحة. الموضع التلقائي للعلامة المسطّحة هو الشمال. عندما لا تكون العلامة مسطّحة، يكون الموضع التلقائي متّجهًا للأعلى ويكون التدوير بحيث تكون العلامة دائمًا في مواجهة الكاميرا.

ينشئ المقتطف أدناه علامة بسيطة باستخدام الرمز التلقائي.

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، تمثّل نقاطًا على عجلة الألوان.

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

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)

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

ينشئ المقتطف أدناه علامة باستخدام رمز مخصّص.

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.

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 إلى تدوير العلامة حول مركزها بدلاً من قاعدتها.

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

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

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-index للعلامة من خلال استدعاء Marker.getZIndex()، ويمكنك تغييرها من خلال استدعاء Marker.setZIndex()

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

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

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