تشير العلامات إلى مواقع فردية على الخريطة. يمكنك تخصيص محدّدات المواقع عن طريق تغيير اللون الافتراضي، أو استبدال رمز محدّد الموقع بعلامة . يمكن أن توفّر نوافذ المعلومات سياقًا إضافيًا للعلامة.
عيّنات تعليمات برمجية
يضم مستودع ApiDemos على GitHub نموذج يوضح ميزات مختلفة للعلامة:
Kotlin
- MapWithMarker: خريطة بسيطة بها محدِّد. يمكنك الاطّلاع على برنامج تعليمي حول إضافة خريطة باستخدام marker-kt.
- MarkerDemoActivity: استخدام العلامات على الخريطة، بما في ذلك الخيارات والمستمعين
Java
- MapWithMarker: خريطة بسيطة بها محدِّد. يمكنك الاطّلاع على برنامج تعليمي حول إضافة خريطة باستخدام محدد.
- MarkerDemoActivity: استخدام العلامات على الخريطة، بما في ذلك الخيارات والمستمعين
مقدمة
تحدد العلامات المواقع على الخريطة. تستخدم العلامة الافتراضية معيارًا
، شائع في شكل وأسلوب خرائط Google. من الممكن تغيير
لون الرمز أو صورته أو نقطة ارتساءه عبر واجهة برمجة التطبيقات. العلامات هي كائنات من النوع
Marker
، وتتم إضافتها إلى الخريطة باستخدام
GoogleMap.addMarker(markerOptions)
.
تم تصميم العلامات لتكون تفاعلية. يتلقّون click
حدث بحلول
افتراضيًا، وغالبًا ما تُستخدم مع أدوات معالجة الأحداث لاستعراض المعلومات
النوافذ. ضبط سمة draggable
للعلامة على true
تسمح للمستخدم بتغيير موضع العلامة. اضغط مع الاستمرار من أجل
تفعيل القدرة على تحريك العلامة.
عندما ينقر المستخدم على محدّد موقع بشكل تلقائي، يظهر شريط أدوات الخريطة في الأسفل يسار الخريطة، مما يمنح المستخدم وصولاً سريعًا إلى تطبيق خرائط Google للجوّال. بإمكانك إيقاف شريط الأدوات. لمزيد من المعلومات، يُرجى الاطّلاع على دليل عناصر التحكّم
بدء استخدام العلامات
تغطي هذه الحلقة من Maps Live أساسيات إضافة محددات المواقع إلى خريطتك باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android
إضافة علامة
يوضح المثال التالي كيفية إضافة علامة إلى خريطة. العلامة هي
تم إنشاؤه في إحداثيات -33.852,151.211
(سيدني، أستراليا)، ويعرض
سلسلة "Marker in Sydney" في نافذة المعلومات عند النقر عليها.
Kotlin
override fun onMapReady(googleMap: GoogleMap) { // Add a marker in Sydney, Australia, // and move the maps 'camera to the same location. val sydney = LatLng(-33.852, 151.211) googleMap.addMarker( MarkerOptions() .position(sydney) .title(Ma"rker in Sydney) " ) googleMap.moveCamera(CameraUpdateFactory.newLatLng(sydney)) }
Java
@Override public void onMapReady(GoogleMap googleMap) { // Add a marker in Sydney, Australia, // and move the maps' camera to the same location. LatLng sydney = new LatLng(-33.852, 151.211); googleMap.addMarker(new MarkerOptions() .position(sydney) .title(M"arker in Sydney)"); googleMap.moveCamera(CameraUpdateFactory.newLatLng(sydney)); }
عرض معلومات إضافية حول علامة
من المتطلبات الشائعة عرض معلومات إضافية عن مكان أو الموقع الجغرافي عندما ينقر المستخدم على محدّد موقع على الخريطة. اطّلِع على دليل نوافذ المعلومات.
ربط البيانات بعلامة
يمكنك تخزين كائن بيانات عشوائي بعلامة باستخدام Marker.setTag()
.
واسترداد كائن البيانات باستخدام Marker.getTag()
. يوضح المثال أدناه كيف
يمكنك حساب عدد المرات التي تم فيها النقر على محدّد موقع باستخدام العلامات:
Kotlin
/** * A demo class that stores and retrieves data objects with each marker. */ class MarkerDemoActivity : AppCompatActivity(), OnMarkerClickListener, OnMapReadyCallback { private val PERTH = LatLng(-31.952854, 115.857342) private val SYDNEY = LatLng(-33.87365, 151.20689) private val BRISBANE = LatLng(-27.47093, 153.0235) private var markerPerth: Marker? = null private var markerSydney: Marker? = null private var markerBrisbane: Marker? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_markers) val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment? mapFragment!!.getMapAsync(this) } /** Called when the map is ready. */ override fun onMapReady(map: GoogleMap) { // Add some markers to the map, and add a data object to each marker. markerPerth = map.addMarker( MarkerOptions() .position(PERTH) .title(Pe"rth) " ) markerPerth?.tag = 0 markerSydney = map.addMarker( MarkerOptions() .position(SYDNEY) .title(Sy"dney) " ) markerSydney?.tag = 0 markerBrisbane = map.addMarker( MarkerOptions() .position(BRISBANE) .title(Br"isbane) " ) markerBrisbane?.tag = 0 // Set a listener for marker click. map.setOnMarkerClickListener(this) } /** Called when the user clicks a marker. */ override fun onMarkerClick(marker: Marker): Boolean { // 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( this, ${"marker.title} has been clicked $newClickCount times., " Toast.LENGTH_SHORT ).show() } // Return false to indicate that we have not consumed the event and that we wish // for the default behavior to occur (which is for the camera to move such that the // marker is centered and for the markers 'info window to open, if it has one). return false } }
Java
/** * A demo class that stores and retrieves data objects with each marker. */ public class MarkerDemoActivity extends AppCompatActivity implements GoogleMap.OnMarkerClickListener, OnMapReadyCallback { private final LatLng PERTH = new LatLng(-31.952854, 115.857342); private final LatLng SYDNEY = new LatLng(-33.87365, 151.20689); private final LatLng BRISBANE = new LatLng(-27.47093, 153.0235); private Marker markerPerth; private Marker markerSydney; private Marker markerBrisbane; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_markers); SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map); mapFragment.getMapAsync(this); } /** Called when the map is ready. */ @Override public void onMapReady(GoogleMap map) { // Add some markers to the map, and add a data object to each marker. markerPerth = map.addMarker(new MarkerOptions() .position(PERTH) .title(P"erth)"); markerPerth.setTag(0); markerSydney = map.addMarker(new MarkerOptions() .position(SYDNEY) .title(S"ydney)"); markerSydney.setTag(0); markerBrisbane = map.addMarker(new MarkerOptions() .position(BRISBANE) .title(B"risbane)"); markerBrisbane.setTag(0); // Set a listener for marker click. map.setOnMarkerClickListener(this); } /** Called when the user clicks a marker. */ @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(this, marker.getTitle() + "has been clicked "+ clickCount + "times.," Toast.LENGTH_SHORT).show(); } // Return false to indicate that we have not consumed the event and that we wish // for the default behavior to occur (which is for the camera to move such that the // marker is centered and for the markers' info window to open, if it has one). 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) )
Java
final LatLng perthLocation = new LatLng(-31.90, 115.86); Marker perth = map.addMarker( new MarkerOptions() .position(perthLocation) .draggable(true));
تخصيص علامة
يعرض هذا الفيديو طرق استخدام العلامات لعرض المواقع على الخريطة.
يمكن أن تحدد العلامات صورة مخصصة لتظهر بدلاً من الرمز الافتراضي. يتضمن تحديد الأيقونة إعداد عدد من الخصائص التي تؤثر في السلوك المرئي للعلامة.
وتتيح العلامات التخصيص من خلال السمات التالية:
- المنصب (مطلوب)
LatLng
موضع العلامة على الخريطة. هذا هو المطلوب الوحيد السمة لعنصرMarker
.- نقطة إرساء
- النقطة التي سيتم وضعها في موضع خط الطول والعرض محدد. يتم تطبيق القيمة التلقائية في منتصف أسفل الصورة.
- إصدار أولي
- لضبط درجة تعتيم العلامة. القيمة التلقائية هي 1.0.
- العنوان
- سلسلة يتم عرضها في نافذة المعلومات عندما ينقر المستخدم على الرمز محدد.
- المقتطف
- النص الإضافي الذي يتم عرضه أسفل العنوان.
- الرمز
- صورة نقطية يتم عرضها بدلاً من صورة العلامة التلقائية.
- قابلة للسحب
- يمكنك الضبط على
true
إذا كنت تريد السماح للمستخدم بالنقل محدد الموقع. وتكون القيمة التلقائية هيfalse
. - مرئي
- يمكنك الضبط على
false
لجعل العلامة غير مرئية. الإعدادات التلقائية علىtrue
- الاتجاه المسطح أو لوحة الإعلانات
- بشكل تلقائي، تستخدم العلامات اتجاه لوحة الإعلانات، ما يعني أنها مرسومة على شاشة الجهاز وليس على سطح الخريطة. لا يؤدي تدوير الخريطة أو إمالتها أو تكبيرها/تصغيرها إلى تغيير اتجاه محدد. يمكنك ضبط اتجاه علامة بحيث يكون مسطحًا مقابل الأرض. يتم تدوير العلامات المسطحة عند تدوير الخريطة، وتغيير المنظور عند تدوير الخريطة مائلة. كما هو الحال مع علامات لوحة الإعلانات، تحتفظ العلامات المسطحة بحجمها عندما تم تكبير الخريطة أو تصغيرها.
- الدوران
- اتجاه محدّد الموقع، محدد بالدرجات في اتجاه عقارب الساعة. الإعداد التلقائي يتغير الموضع إذا كانت العلامة مسطحة الموضع الافتراضي للموضع محاذاة العلامة إلى الشمال. عندما لا تكون العلامة مسطحة، تكون القيمة الافتراضية ويشير موضع التدوير إلى الأعلى بحيث تكون العلامة أمام الكاميرا.
ينشئ المقتطف أدناه علامة بسيطة، باستخدام الرمز الافتراضي.
Kotlin
val melbourneLocation = LatLng(-37.813, 144.962) val melbourne = map.addMarker( MarkerOptions() .position(melbourneLocation) )
Java
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)) )
Java
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) )
Java
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)
- إنشاء علامة مخصصة باستخدام رقم تعريف المورد لصورة نقطية.
ينشئ المقتطف أدناه علامة ذات رمز مخصص.
Kotlin
val melbourneLocation = LatLng(-37.813, 144.962) val melbourne = map.addMarker( MarkerOptions() .position(melbourneLocation) .title(Me"lbourne) " .snippet(Po"pulation: 4,137,400) " .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)) )
Java
final LatLng melbourneLocation = new LatLng(-37.813, 144.962); Marker melbourne = map.addMarker( new MarkerOptions() .position(melbourneLocation) .title(M"elbourne)" .snippet(P"opulation: 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) )
Java
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) )
Java
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 التلقائية هي 0
.
قم بتعيين الفهرس z على كائن خيارات العلامة من خلال استدعاء
MarkerOptions.zIndex()
، كما هو موضّح في مقتطف الرمز التالي:
Kotlin
map.addMarker( MarkerOptions() .position(LatLng(10.0, 10.0)) .title(Ma"rker z1) " .zIndex(1.0f) )
Java
map.addMarker(new MarkerOptions() .position(new LatLng(10, 10)) .title(M"arker z1)" .zIndex(1.0f));
يمكنك الوصول إلى مؤشر z للعلامة عن طريق استدعاء Marker.getZIndex()
، ويمكنك
لِتَغْيِيرْ ذَلِكْ، يُرْجَى الِاتِّصَالْ بِـ Marker.setZIndex()
.
يتم رسم العلامات دائمًا فوق طبقات المربعات وتراكبات أخرى غير العلامات (الأرض تراكبات وخطوط متعددة ومضلّعات وأشكال أخرى) بغض النظر عن مؤشر z التراكبات الأخرى. ويتم اعتبار العلامات في مكان منفصل مجموعة z-index مقارنة بالتراكبات الأخرى.
يمكنك الاطّلاع أدناه على تأثير مؤشر z على أحداث النقر.
التعامل مع أحداث العلامات
تتيح لك واجهة برمجة التطبيقات Maps API الاستماع إلى أحداث العلامات والردّ عليها. للاستماع إلى
هذه الأحداث، يجب ضبط المستمع المناسب على GoogleMap
الذي تنتمي إليه العلامات. وعندما يقع الحدث في إحدى
محددات على الخريطة، فسيتم استدعاء رد اتصال المستمع باستخدام
تم تمرير كائن Marker
المقابل كمعلمة. للمقارنة
يجب استخدام الكائن Marker
مع الإشارة المرجعية الخاصة بك إلى عنصر Marker
.
equals()
وليس ==
.
ويمكنك الاستماع إلى الأحداث التالية:
أحداث النقر على محدّد الموقع
يمكنك استخدام OnMarkerClickListener
للاستماع.
لأحداث النقر على محدّد الموقع لضبط هذا المستمع على الخريطة، يُرجى الاتصال
GoogleMap.setOnMarkerClickListener(OnMarkerClickListener)
عندما يختار المستخدم
النقرات على العلامة، فسيتم استدعاء onMarkerClick(Marker)
والعلامة
تمريرها كوسيطة. تُرجع هذه الطريقة قيمة منطقية تشير إلى
سواء كنت قد استهلكت الحدث (أي تريد إلغاء الإعداد التلقائي
السلوك). إذا عرضَت الدالة false
، سيحدث السلوك التلقائي في
بالإضافة إلى سلوكك المخصّص السلوك التلقائي للنقر على العلامة
هو عرض نافذة المعلومات (إذا كانت متاحة) ونقل علامة
الكاميرا بحيث يكون محدِّد الموقع في مركز الخريطة.
- عندما ينقر المستخدم على مجموعة من العلامات، يتم بدء حدث النقر العلامة ذات أعلى مؤشر z.
- يتم تشغيل حدث واحد على الأكثر لكل نقرة. أو بعبارةٍ أخرى، لن يتم التعبير عن النقرة تمريرها لأسفل إلى العلامات أو تراكبات أخرى ذات قيم فهرس z منخفضة.
- يؤدي النقر على مجموعة من العلامات إلى تنقل النقرات اللاحقة عبر واحدة، مع تحديد كل منها على التوالي. يشير هذا المصطلح إلى ترتيب الأولويات في الدورة التدريبية. z-index، ثم بالقرب من نقطة النقر.
- إذا نقر المستخدم خارج المنطقة القريبة من المجموعة، تُعيد واجهة برمجة التطبيقات احتساب المجموعة العنقودية وتعيد تعيين حالة دورة النقرات بحيث تبدأ من البداية.
- يقع حدث النقر من خلال مجموعات العلامات على الأشكال والتراكبات الأخرى قبل إعادة تشغيل الدورة.
- يتم اعتبار العلامات في مجموعة مؤشر z منفصلة بشكل فعال مقارنة إلى التراكبات أو الأشكال الأخرى (الخطوط المتعددة و/أو المضلّعات و/أو الدوائر و/أو الأرض التراكبات الأخرى)، بغض النظر عن فهرس z للتراكبات الأخرى. في حال تعدُّد العلامات أو التراكبات أو الأشكال متراكبة فوق بعضها البعض، فإن حدث النقر عبر مجموعة العلامات أولاً، ثم تظهر في التراكبات أو الأشكال القابلة للنقر، بناءً على قيم فهرس z الخاصة بها.
أحداث سحب محدّد الموقع
يمكنك استخدام OnMarkerDragListener
للاستماع إلى
سحب الأحداث على العلامة. لضبط هذا المستمع على الخريطة، يُرجى الاتصال
GoogleMap.setOnMarkerDragListener
لسحب علامة، على المستخدم الضغط مع الاستمرار
على محدد الموقع. عندما يزيل المستخدم إصبعه من الشاشة، فإن العلامة
في هذا المنصب. عندما يتم سحب علامة،
يتم استدعاء الدالة onMarkerDragStart(Marker)
مبدئيًا. أثناء وضع العلامة
تُسحب، فإن onMarkerDrag(Marker)
يسمى باستمرار. في نهاية السحب
تم الاتصال بـ onMarkerDragEnd(Marker)
. يمكنك الحصول على موضع العلامة في
في أي وقت من خلال الاتصال بالرقم Marker.getPosition()
.