يصف هذا الموضوع كيفية إضافة خريطة أساسية إلى تطبيق Android بعد ضبطت المشروع لاستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android. بعد إضافة خريطة، يمكنك تغيير نوع الخريطة وميزاتها.
نظرة عامة
توفر حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android العديد من الفئات التي يمكن لتطبيقك استخدامها. إدارة دورة حياة الخريطة ووظائفها وبياناتها. تتيح هذه الفئات تفاعلات المستخدِم استنادًا إلى نموذج واجهة مستخدِم Android، مثل ضبط الحالة الأولية للخريطة والاستجابة للإشارات التي يرسلها المستخدِم أثناء التشغيل.
الواجهة الرئيسية والفئات للتعامل مع الخرائط:
GoogleMap
: نقطة الدخول لإدارة الخريطة الأساسية الميزات والبيانات. لا يمكن لتطبيقك الوصول إلى عنصرGoogleMap
إلا بعد استرداده من عنصرSupportMapFragment
أوMapView
.
SupportMapFragment
: وحدة مقتطعة لإدارة دورة حياة عنصرGoogleMap
OnMapReadyCallback
— واجهة لمعاودة الاتصال تعالج الأحداث وتفاعلات المستخدم للعنصرGoogleMap
.
ينفِّذ عنصر GoogleMap
هذه العمليات تلقائيًا:
- جارٍ الاتصال بخدمة "خرائط Google".
- يتم تنزيل مربّعات الخريطة.
- عرض مربّعات المعلومات على شاشة الجهاز
- عرض عناصر تحكم متنوعة مثل العرض الشامل والتكبير/التصغير.
- الاستجابة لإيماءات التحريك والتكبير/التصغير من خلال تحريك الخريطة والتكبير أو التصغير.
لاستخدام كائن GoogleMap
في تطبيقك، يجب استخدام
كائن SupportMapFragment
أو MapView
ككائن حاوية للخريطة
ثم استرداد الكائن GoogleMap
من الحاوية. نظرًا لأن الحاوية
تنشأ الفئات إما من أحد أجزاء Android أو طريقة العرض، فإنها توفر خريطة
مع إدارة مراحل النشاط وإمكانات واجهة المستخدم لفئات Android الأساسية.
فئة SupportMapFragment
هي الحاوية الأكثر حداثة وشائعة للكائن
GoogleMap
.
عرض الرمز
الرمز التالي مأخوذ من نشاط Java الكامل المستخدم في هذا الموضوع عند إضافة جزء بشكل ثابت. تم إنشاء مشروع Android من المشروع "إفراغ". ثم تعديلها استنادًا إلى دليل ضبط المشروع. بعد تنفيذ الخطوات الواردة في هذا الموضوع، قد تختلف التعليمة البرمجية استنادًا إلى نموذج المشروع.
package com.example.mapsetup; import androidx.appcompat.app.AppCompatActivity; import android.os.Bundle; import com.google.android.gms.maps.GoogleMap; import com.google.android.gms.maps.OnMapReadyCallback; import com.google.android.gms.maps.SupportMapFragment; import com.google.android.gms.maps.model.LatLng; import com.google.android.gms.maps.model.MarkerOptions; // Implement OnMapReadyCallback. public class MainActivity extends AppCompatActivity implements OnMapReadyCallback { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // Set the layout file as the content view. setContentView(R.layout.activity_main); // Get a handle to the fragment and register the callback. SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager() .findFragmentById(R.id.map); mapFragment.getMapAsync(this); } // Get a handle to the GoogleMap object and display marker. @Override public void onMapReady(GoogleMap googleMap) { googleMap.addMarker(new MarkerOptions() .position(new LatLng(0, 0)) .title("Marker")); } }
لإضافة خريطة
يوضّح هذا القسم كيفية إضافة خريطة أساسية باستخدام جزء كحاوية للخريطة، ولكن يمكنك استخدام عرض بدلاً من ذلك. على سبيل المثال، راجع RawMapViewDemoActivity على جيت هب.
الخطوات الأساسية:
للحصول على حزمة SDK، احصل على مفتاح واجهة برمجة تطبيقات، ثم أضف أُطر العمل المطلوبة، اتبع الخطوات الواردة في:
أضِف كائن
SupportMapFragment
إلى النشاط الذي سيتعامل مع الخريطة. يمكنك إضافة المقتطف بشكل ثابت أو ديناميكي.نفِّذ واجهة
OnMapReadyCallback
.اضبط ملف التنسيق على أنّه عرض المحتوى.
إذا أضفت المقتطف بشكل ثابت، احصل على معرّف للمقتطف.
سجِّل طلب معاودة الاتصال.
الحصول على اسم معرِّف للعنصر
GoogleMap
إضافة عنصر SupportMapFragment
يمكنك إضافة عنصر SupportMapFragment
إلى تطبيقك بشكل ثابت أو ديناميكي.
وأبسط طريقة هي إضافتها بشكل ثابت. في حال إضافة المقتطف بشكل ديناميكي،
يمكنك تنفيذ إجراءات إضافية على المقتطف، مثل إزالته
واستبداله أثناء التشغيل.
لإضافة جزء بشكل ثابت
في ملف التنسيق للنشاط الذي سيعالج الخريطة:
- أضِف عنصر
fragment
. - إضافة بيان الاسم
xmlns:map="http://schemas.android.com/apk/res-auto"
يتيح ذلك استخدامmaps
سمات XML المخصّصة. - في العنصر
fragment
، اضبط السمةandroid:name
علىcom.google.android.gms.maps.SupportMapFragment
. - في العنصر
fragment
، أضِف سمةandroid:id
واضبطها على رقم تعريف المورد (@+id/map
) في R.id.map.
على سبيل المثال، في ما يلي ملف تنسيق كامل يتضمّن عنصر fragment
:
<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:map="http://schemas.android.com/apk/res-auto"
android:name="com.google.android.gms.maps.SupportMapFragment"
android:id="@+id/map"
android:layout_width="match_parent"
android:layout_height="match_parent"/>
لإضافة جزء بشكل ديناميكي
في النشاط:
- أنشئ مثيل
SupportMapFragment
. - إتمام معاملة تضيف الجزء إلى النشاط لمزيد من المعلومات، اطّلِع على تقسيم المعاملات.
على سبيل المثال:
Kotlin
val mapFragment = SupportMapFragment.newInstance() supportFragmentManager .beginTransaction() .add(R.id.my_container, mapFragment) .commit()
Java
SupportMapFragment mapFragment = SupportMapFragment.newInstance(); getSupportFragmentManager() .beginTransaction() .add(R.id.my_container, mapFragment) .commit();
تنفيذ واجهة OnMapReadyCallback
عدِّل بيان النشاط التجاري على النحو التالي:
Kotlin
class MainActivity : AppCompatActivity(), OnMapReadyCallback { // ... }
Java
class MainActivity extends AppCompatActivity implements OnMapReadyCallback { // ... }
ضبط طريقة عرض المحتوى
في طريقة onCreate
لنشاطك، اطلب
setContentView
وتعيين ملف التنسيق كطريقة عرض المحتوى.
على سبيل المثال، إذا كان ملف التنسيق باسم main.xml
:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.main) }
Java
@Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); }
الحصول على معرّف للجزء وتسجيل دالة الاستدعاء
للحصول على معرّف للعنصر، يمكنك استدعاء الأسلوب
FragmentManager.findFragmentById
ونقله رقم تعريف المورد للعنصر في ملف التنسيق. إذا أضفت الجزء بشكل ديناميكي، يمكنك تخطّي هذه الخطوة لأنّك سبق أن استرددت الاسم المعرِّف.استخدِم الطريقة
getMapAsync
لضبط دالة ردّ الاتصال في الfragment.
على سبيل المثال، إذا أضفت الجزء بشكل ثابت:
Kotlin
val mapFragment = supportFragmentManager .findFragmentById(R.id.map) as SupportMapFragment mapFragment.getMapAsync(this)
Java
SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager() .findFragmentById(R.id.map); mapFragment.getMapAsync(this);
الحصول على اسم معرِّف للكائن GoogleMap
استخدِم طريقة ردّ الاتصال onMapReady
للحصول على معرّف
GoogleMap
الكائن. يتم تشغيل عملية معاودة الاتصال عندما تكون الخريطة جاهزة للاستلام
البيانات التي أدخلها المستخدم وهي توفّر مثيلاً غير خالٍ من الفئة GoogleMap
التي
يمكنك استخدامها لتحديث الخريطة.
في هذا المثال، تسترد الدالة onMapReady
اسمًا معرِّفًا إلى GoogleMap
ثم تتم إضافة علامة إلى الخريطة:
Kotlin
override fun onMapReady(googleMap: GoogleMap) { googleMap.addMarker( MarkerOptions() .position(LatLng(0.0, 0.0)) .title("Marker") ) }
Java
@Override public void onMapReady(GoogleMap googleMap) { googleMap.addMarker(new MarkerOptions() .position(new LatLng(0, 0)) .title("Marker")); }
عند إنشاء التطبيق وتشغيله بنجاح، سيتم عرض خريطة بعلامة على جزيرة نول (خط عرض صفر درجة وخط طول صفر درجة).
عرض التعليمة البرمجية للنشاط بالكامل:
الخطوات التالية
بعد إكمال هذه الخطوات، يمكنك ضبط إعدادات الخريطة.