يصف هذا الموضوع كيفية إضافة خريطة أساسية إلى تطبيق 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"
. يتيح ذلك استخدام سمات XML المخصّصةmaps
. - في العنصر
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
لضبط معاودة الاتصال على الجزء.
على سبيل المثال، إذا أضفت الجزء بشكل ثابت:
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")); }
عند إنشاء وتشغيل التطبيق بنجاح، سيعرض خريطة تحتوي على محدِّد على جزيرة Null (خط الطول وخط العرض صفر درجة).
اعرض رمز النشاط الكامل:
الخطوات التالية
بعد إكمال هذه الخطوات، يمكنك ضبط إعدادات الخريطة.