يوضّح هذا الموضوع كيفية إعداد خريطة تمت إضافتها إلى تطبيق Android باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android
نظرة عامة
بعد إضافة خريطة إلى تطبيقك، يمكنك ضبط إعدادات بيئة التشغيل المبدئية.
إعدادات الخريطة. يجب تهيئة الإعدادات الأولية استنادًا إلى ما إذا كان
أضفت حاوية الخريطة (
SupportMapFragment
أو
MapView
) بشكل ثابت أو ديناميكي إذا كانت حاوية الخريطة
بشكل ثابت، يمكنك تهيئة إعدادات الخريطة الأولية في ملف التخطيط.
إذا تمت إضافته ديناميكيًا، يمكنك ضبط الإعدادات الأولية في
معاودة الاتصال على OnCreate
مع GoogleMapOptions
الخاص بك.
للحصول على تفاصيل حول إضافة حاوية خريطة، راجع إضافة خريطة.
تشمل إعدادات الخريطة الأولية ما يلي:
- موضع الكاميرا، بما في ذلك: الموقع الجغرافي والتكبير/التصغير والاتجاهات والإمالة راجِع الكاميرا والعرض للحصول على تفاصيل عن مكان الكاميرا.
- نوع الخريطة.
- مكونات واجهة المستخدم المطلوب عرضها، مثل التكبير/التصغير الأزرار والبوصلة.
- الإيماءات المطلوب تفعيلها.
- ما إذا كان الوضع البسيط مفعَّلاً.
في وقت التشغيل، يمكنك ضبط هذه الإعدادات وبعض إعدادات الإضافة من خلال
جارٍ تعديل الكائن GoogleMap
في onMapReady
معاودة الاتصال. ويتم ضبط الإعدادات الإضافية من خلال طرق
GoogleMap
، مثل تلك التي تهيئ
طبقة الزيارات والمساحة المتروكة على الخريطة.
مثال
في مثال الرمز أدناه ولقطة الشاشة أعلاه، تظهر الخريطة مع الإعدادات التالية.
يتم ضبط الإعدادات الأولية في ملف التنسيق:
- تفعيل عناصر التحكم في التكبير أو التصغير.
- يمكنك تفعيل عناصر التحكّم في الإيماءات.
- اضبط إمالة الخريطة على 30.
إعدادات بيئة التشغيل:
- اجعل الكاميرا في منتصف كيوتو في اليابان.
- تتيح هذه السياسة تفعيل نوع الخريطة المختلطة.
- شغّل طبقة حركة المرور.
الإعدادات الأولية
<?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" xmlns:tools="http://schemas.android.com/tools" android:name="com.google.android.gms.maps.SupportMapFragment" android:id="@+id/map" android:layout_width="match_parent" android:layout_height="match_parent" map:uiZoomControls="true" map:uiRotateGestures="true" map:cameraTilt="30" />
إعدادات بيئة التشغيل
package com.example.mapsetup; import androidx.appcompat.app.AppCompatActivity; import android.os.Bundle; import com.google.android.gms.maps.CameraUpdateFactory; 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; public class MainActivity extends AppCompatActivity implements OnMapReadyCallback { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager() .findFragmentById(R.id.map); mapFragment.getMapAsync(this); } // Update the map configuration at runtime. @Override public void onMapReady(GoogleMap googleMap) { // Set the map coordinates to Kyoto Japan. LatLng kyoto = new LatLng(35.00116, 135.7681); // Set the map type to Hybrid. googleMap.setMapType(GoogleMap.MAP_TYPE_HYBRID); // Add a marker on the map coordinates. googleMap.addMarker(new MarkerOptions() .position(kyoto) .title("Kyoto")); // Move the camera to the map coordinates and zoom in closer. googleMap.moveCamera(CameraUpdateFactory.newLatLng(kyoto)); googleMap.moveCamera(CameraUpdateFactory.zoomTo(15)); // Display traffic. googleMap.setTrafficEnabled(true); } }
قبل البدء
قبل أن تبدأ، يمكنك إعداد مشروع وإضافة خريطة أساسية من خلال الخيارات التالية:
يمكنك إنشاء تطبيق باستخدام نموذج "خرائط Google" في "استوديو Android". نموذج "خرائط Google" تقوم بتهيئة مشروعك تلقائيًا وتضيف خريطة أساسية. يتم استخدام جزء كحاوية الخريطة وتتم إضافتها بشكل ثابت. للحصول على التفاصيل، يمكنك مراجعة التشغيل السريع:
يمكنك ضبط مشروعك يدويًا لحزمة SDK إضافة خريطة أساسية. يتيح لك ذلك استخدام أي نموذج Android وإضافة لتطبيق حالي.
إعداد الخريطة بعد إضافتها بشكل ثابت
يصف هذا القسم كيفية تعيين الحالة الأولية للخريطة في حالة إضافتها بشكل ثابت إلى ملف التخطيط.
تُحدِّد حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android مجموعة من سمات XML المخصَّصة
SupportMapFragment
أو MapView
التي يمكنك استخدامها لضبط الإدخال الأولي
حالة الخريطة مباشرة من ملف التخطيط. السمات التالية
محددة حاليًا:
mapType
— نوع الخريطة التي سيتم عرضها تشمل القيم الصالحة ما يلي:none
، "normal
" و"hybrid
" و"satellite
" و"terrain
""
cameraTargetLat
" و"cameraTargetLng
" و"cameraZoom
" و"cameraBearing
"cameraTilt
— الموضع الأولي للكاميرا. يمكنك الاطّلاع على الكاميرا وطرق العرض للحصول على التفاصيل.uiZoomControls
،uiCompass
— لتحديد ما إذا كانت عناصر التحكّم في التكبير أو التصغير البوصلة. يمكنك الانتقال إلىUiSettings
للاطّلاع على التفاصيل.uiZoomGestures
وuiScrollGestures
وuiRotateGestures
وuiTiltGestures
— تحدِّد هذه السياسة ما إذا كانت إيماءات محدَّدة مفعَّلة. عرضUiSettings
للاطّلاع على التفاصيلzOrderOnTop
: يشير إلى ما إذا كان سطح عرض الخريطة سيُعرض على أعلى نافذة الخريطة وعناصر التحكم في الخريطة وأي كائن في النافذة. عرض SurfaceView.setZOrderOnTop(boolean) لمعرفة التفاصيل.useViewLifecycle
- صالحة فقط مع عنصرSupportMapFragment
. يتم التحديد ما إذا كان ينبغي ربط دورة حياة الخريطة بعرض الجزء أو الجزء نفسه. يمكنك الاطّلاع هنا على التفاصيل.liteMode
—true
لتفعيل الوضع البسيط؛ وإلاfalse
.mapColorScheme
: تحدّد هذه السياسة نظام الألوان للخريطة العادية والتضاريس. تتضمن القيمlight
(تلقائي) وdark
وfollow_system
مما يعني استخدام إعداد النظام الحالي استنادًا إلى إعداد الجهاز فيUI_NIGHT_MODE_MASK
. لمزيد من المعلومات، يُرجى الاطّلاع على مخطط ألوان الخريطة.
لاستخدام هذه السمات المخصصة ضمن ملف التنسيق، يجب
تضمين تعريف مساحة الاسم التالي. يمكنك اختيار أي مساحة اسم،
لا يلزم أن يكون map
:
xmlns:map="http://schemas.android.com/apk/res-auto"
يمكنك بعد ذلك إضافة السمات باستخدام بادئة map:
إلى ملف التنسيق.
يعمل ملف التنسيق التالي على إعداد كائن SupportMapFragment
باستخدام
محددة. يمكن تطبيق السمات نفسها على كائن MapView
مثل
أيضًا.
<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"
map:cameraBearing="112.5"
map:cameraTargetLat="-33.796923"
map:cameraTargetLng="150.922433"
map:cameraTilt="30"
map:cameraZoom="13"
map:mapType="normal"
map:mapColorScheme="dark"
map:uiCompass="false"
map:uiRotateGestures="true"
map:uiScrollGestures="false"
map:uiTiltGestures="true"
map:uiZoomControls="false"
map:uiZoomGestures="true"/>
إعداد الخريطة بعد إضافتها بشكل ديناميكي
يصف هذا القسم كيفية تعيين الحالة الأولية للخريطة في حالة إضافتها إلى تطبيقك ديناميكيًا
إذا أضفت SupportMapFragment
أو MapView
بشكل ديناميكي، يمكنك عندئذٍ
لضبط الحالة الأولية للخريطة في كائن GoogleMapOptions
. تشير رسالة الأشكال البيانية
والخيارات المتوفرة هي نفس الخيارات المتوفرة في ملف التخطيط.
يمكنك إنشاء GoogleMapOptions
على النحو التالي:
Kotlin
val options = GoogleMapOptions()
Java
GoogleMapOptions options = new GoogleMapOptions();
ثم اضبطه على النحو التالي:
Kotlin
options.mapType(GoogleMap.MAP_TYPE_SATELLITE) .compassEnabled(false) .rotateGesturesEnabled(false) .tiltGesturesEnabled(false)
Java
options.mapType(GoogleMap.MAP_TYPE_SATELLITE) .compassEnabled(false) .rotateGesturesEnabled(false) .tiltGesturesEnabled(false);
لتطبيق هذه الخيارات عند إنشاء خريطة، يمكنك تنفيذ أحد الإجراءات التالية:
- في حال استخدام
SupportMapFragment
، عليك استخدامSupportMapFragment.newInstance(GoogleMapOptions options)
لإنشاء الجزء والتمرير في الإعدادات الخاصة بك. - في حال استخدام
MapView
، عليك استخدام طريقة إنشاءMapView(Context, GoogleMapOptions)
ومرره في الإعدادات الخاصة بك.
أقلمة الخريطة
عند إضافة MapView
أو SupportMapFragment
إلى تطبيقك، تظهر العناصر النصية
يتم عرضها على الخريطة باللغة المناسبة حسب جهاز المستخدم
الإعدادات والموقع الجغرافي. يمكنك حصر اللغات التي يستخدمها تطبيقك على
مجموعة فرعية من كل اللغات المتاحة، من خلال إضافة عنصر resConfigs
إلى Gradle
الملف. يفيد ذلك في إزالة اللغات غير المستخدمة، كما أنه يقلل من
الحجم الثنائي للتطبيق. على سبيل المثال:
defaultConfig {
resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}
تعرَّف على مزيد من المعلومات عن أقلمة تطبيق Android.
إعداد طبقة حركة المرور
يمكنك عرض بيانات حركة المرور على الخريطة عن طريق تمكين طبقة حركة المرور. يمكنك
لتمكين طبقة حركة المرور وتعطيلها من خلال استدعاء
setTrafficEnabled()
ويمكنك تحديد ما إذا كانت طبقة حركة المرور عليها حاليًا من خلال
واستدعاء
isTrafficEnabled()
. تعرض لقطة الشاشة التالية خريطة تم فيها تفعيل طبقة حركة المرور.
ضبط نوع الخريطة
لتحديد نوع الخريطة، اطلب طريقة setMapType
.
على سبيل المثال، لعرض خريطة القمر الصناعي:
Kotlin
// Sets the map type to be "hybrid" map.mapType = GoogleMap.MAP_TYPE_HYBRID
Java
// Sets the map type to be "hybrid" map.setMapType(GoogleMap.MAP_TYPE_HYBRID);
تقارن الصورة التالية بين أنواع الخرائط العادية والمختلطة وخرائط التضاريس:
![مقارنة بين ثلاثة أنواع من الخرائط مقارنة MapType](https://developers.google.cn/static/maps/documentation/android-sdk/images/map_types.png?authuser=8&hl=ar)
إعداد المباني الثلاثية الأبعاد
العديد من المدن، عندما يتم عرضها عن قرب، تظهر مبانٍ ثلاثية الأبعاد تكون قابلة للعرض.
في الصورة أدناه لمدينة فانكوفر، كندا. يمكنك إيقاف المباني الثلاثية الأبعاد من خلال
يتصل
GoogleMap.setBuildingsEnabled(false)
![خريطة فانكوفر، كندا](https://developers.google.cn/static/maps/documentation/android-sdk/images/vancouver.png?authuser=8&hl=ar)
ضبط إعدادات الخريطة الداخلية
في مستويات التكبير/التصغير العالية، تعرض الخريطة مخططات الطوابق
المساحات الداخلية مثل المطارات ومراكز التسوّق ومتاجر البيع بالتجزئة الكبيرة ووسائل النقل العام
المحطات. يتم عرض مخططات الطوابق هذه، المسماة بالخرائط الداخلية، "للمخططات العادية"
و"القمر الصناعي" أنواع الخرائط (GoogleMap.MAP_TYPE_NORMAL
وكذلك
GoogleMap.MAP_TYPE_SATELLITE
). ويتم تفعيلها تلقائيًا عندما ينقر المستخدم
وتصبح تدريجيًا تتلاشى عند تصغير الخريطة.
إشعار الإيقاف النهائي: في إصدار مستقبلي، داخلي
ستكون الخرائط متاحة فقط على نوع الخريطة normal
. من ذلك
الإصدار المستقبلي، لن تتوافق الخرائط الداخلية على satellite
،
خريطة terrain
أو hybrid
حتى الأماكن الداخلية ليست
متاح، سيستمر isIndoorEnabled()
في عرض القيمة
التي تم ضبطها عبر setIndoorEnabled()
، كما هي الحال الآن. من
الافتراضي، setIndoorEnabled
هو true
. تشير رسالة الأشكال البيانية
ملاحظات الإصدار
عندما يصبح الدعم الداخلي غير
متوفر على أنواع الخرائط هذه.
![مثال على خريطة داخلية مثال على الخريطة الداخلية](https://developers.google.cn/static/maps/documentation/android-sdk/images/indoor.png?authuser=8&hl=ar)
فيما يلي ملخص لوظائف الخرائط الداخلية في واجهة برمجة التطبيقات:
- يمكنك تعطيل الخرائط الداخلية من خلال الاتصال
GoogleMap.setIndoorEnabled(false)
يتم تفعيل الخرائط الداخلية افتراضيًا. يتم عرض الخرائط الداخلية على خريطة واحدة في في وقت معين. وبشكل افتراضي، هذه هي أول خريطة تتم إضافتها إلى تطبيقك. إلى عرض الخرائط الداخلية على خريطة مختلفة، ثم إيقافها على الخريطة الأولى الاتصال بـsetIndoorEnabled(true)
على الخريطة الثانية. - لإيقاف منتقي المستوى التلقائي (منتقي الطابق)، اتصل
GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false)
لمزيد من التفاصيل، راجِع التفاعل مع الخريطة. OnIndoorStateChangeListener
— يحدد المستمعين الذين التي ترصد عندما يكون التركيز على مبنى ما، أو عندما يتم تفعيل مستوى في مبنى. لمعرفة التفاصيل، يُرجى الاطّلاع على التفاعل مع الخريطة.getFocusedBuilding
: لاسترداد المبنى الموجود التركيز. يمكنك بعد ذلك العثور على مستوى النشاط من خلال الاتصالIndoorBuilding.getActiveLevelIndex()
- لا يؤثر تصميم الخريطة الأساسية على الخرائط الداخلية.
إعداد المساحة المتروكة للخريطة
يعرض هذا الفيديو مثالاً على المساحة المتروكة في الخريطة.
تم تصميم خريطة Google لملء المنطقة المحددة بواسطة حاويتها بالكامل
وهو عادةً MapView
أو SupportMapFragment
. يجب أن تتضمن الجوانب العديدة لكيفية
تظهر الخريطة وتتصرف من خلال أبعاد حاويتها:
- سيعكس هدف الكاميرا منتصف المنطقة المبطّنة.
- يتم وضع عناصر التحكم على الخريطة بالنسبة إلى حواف الخريطة.
- تظهر المعلومات القانونية، مثل بيانات حقوق الطبع والنشر أو شعار Google على طول الحافة السفلية للخريطة.
يمكنك إضافة مساحة متروكة حول حواف الخريطة باستخدام
GoogleMap
setPadding()
. ستضم الخريطة
الاستمرار في ملء الحاوية بالكامل، لكن النص والتحكم في تحديد الموضع،
والإيماءات وحركات الكاميرا كما لو تم وضعها في
مساحة أصغر. وينتج عن ذلك التغييرات التالية:
- حركات الكاميرا عبر طلبات بيانات من واجهة برمجة التطبيقات أو الضغطات على الأزرار (على سبيل المثال، البوصلة، "الموقع الجغرافي" وأزرار التكبير/التصغير) نسبية إلى المنطقة ذات المساحة المتروكة.
- تعرض الطريقة
getCameraPosition
مركز المنطقة المبطّنة. - تعرض الطريقتان
Projection
وgetVisibleRegion
المنطقة المغطاة. - تتم إزاحة عناصر تحكم واجهة المستخدم من حافة الحاوية بواسطة عدد البكسل.
يمكن أن تكون المساحة المتروكة مفيدة عند تصميم واجهات مستخدم تتداخل مع جزء من الخريطة. في الصورة التالية، أصبحت الخريطة محشوة بالأعلى الحواف اليمنى. سيتم عرض عناصر تحكم مرئية في الخريطة والنص القانوني على المنطقة المساحية، الموضحة باللون الأخضر، بينما ستستمر الخريطة في لملء الحاوية بالكامل، كما هو موضح باللون الأزرق. في هذا المثال، يمكنك عائمة القائمة على الجانب الأيمن من الخريطة بدون حجب عناصر التحكم في الخريطة.
نظام ألوان الخريطة
بالنسبة إلى الخرائط من النوع "العادي" و"التضاريس"، يمكنك ضبط ألوان الخريطة ديناميكيًا للتعتيم أو الإضاءة أو لاستخدام إعداد النظام الحالي. على سبيل المثال: يمكنك تعتيم أو تعتيم نظام ألوان الخريطة بناءً على الوقت من اليوم أو للاستخدام الداخلي أو الخارجي للجهاز.
تستخدم الخريطة الوضع الفاتح بشكل تلقائي. تستند قيمة إعداد النظام الحالي إلى
على إعدادات الجهاز في "UI_NIGHT_MODE_MASK
".
Kotlin
mapFragment = SupportMapFragment.newInstance(GoogleMapOptions().mapColorScheme(MapColorScheme.DARK).mapId(mapId2))
Java
mapFragment = SupportMapFragment.newInstance(new GoogleMapOptions().mapColorScheme(MapColorScheme.DARK).mapId(mapId2));
يمكنك تبديل نظام الألوان باستخدام
GoogleMap.setMapColorScheme()
لضبط النمط الحالي على الوضع الداكن أو الوضع الفاتح أو اتّباع النظام
الإعدادات.
Kotlin
googleMap.setMapColorScheme(MapColorScheme.DARK) googleMap.setMapColorScheme(MapColorScheme.LIGHT) googleMap.setMapColorScheme(MapColorScheme.FOLLOW_SYSTEM)
Java
googleMap.setMapColorScheme(MapColorScheme.DARK); googleMap.setMapColorScheme(MapColorScheme.LIGHT); googleMap.setMapColorScheme(MapColorScheme.FOLLOW_SYSTEM);