مكتبة "الكتابة في الخرائط"

Jetpack Compose هي مجموعة أدوات تعريفية محلية لواجهة المستخدم تعمل على تبسيط تسريع عملية تطوير واجهة المستخدم. باستخدام Jetpack Compose، يمكنك وصف الشكل الذي تريده لتطبيقك، ثم السماح لـ Jetpack Compose بمعالجة الباقي.

‫مكتبة Compose لحزمة تطوير برامج "خرائط Google" لحزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android هي مجموعة من الدوال المركّبة مفتوحة المصدر وأنواع البيانات التي يمكنك استخدامها مع Jetpack Compose لإنشاء تطبيقك.

تحتوي مكتبة Compose لحزمة تطوير برامج "خرائط Google" على دوال مركّبة وأنواع بيانات تتيح لك تنفيذ العديد من المهام الشائعة. في ما يلي بعض الدوال المركّبة وأنواع البيانات الشائعة الاستخدام:

دالة مركّبة الوصف
Circle دالة مركّبة لإضافة دائرة إلى خريطة
GoogleMap دالة مركّبة لإضافة خريطة
GroundOverlay دالة مركّبة لإضافة طبقة أرضية إلى خريطة
MapProperties نوع بيانات للخصائص التي يمكن تعديلها على خريطة
MapUISettings نوع بيانات للإعدادات ذات الصلة بواجهة المستخدم على خريطة
Marker دالة مركّبة لإضافة محدِّد موقع إلى خريطة
Polygon دالة مركّبة لإضافة مضلّع إلى خريطة
Polyline دالة مركّبة لإضافة خط متعدّد الأضلاع إلى خريطة
TileOverlay دالة مركّبة لإضافة تراكب الصور إلى خريطة

للاطّلاع على قائمة كاملة بجميع الدوال المركّبة وأنواع البيانات، يُرجى الرجوع إلى مرجع مكتبة Compose لحزمة تطوير برامج "خرائط Google".

المتطلبات

لاستخدام مكتبة Compose لحزمة تطوير برامج "خرائط Google" مع حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google للتطبيقات المتوافقة مع Android، يجب تنفيذ ما يلي:

  • تنزيل "استوديو Android Arctic Fox" وتثبيته

  • إنشاء مشروع "خرائط Google" في "استوديو Android" باستخدام:

    • نوع نموذج نشاط Compose فارغ يضيف هذا النموذج التبعيات اللازمة التي يتطلبها Jetpack Compose.
    • الحد الأدنى من حزمة تطوير البرامج (SDK) الذي تم ضبطه على المستوى 23 من واجهة برمجة تطبيقات Android ‏("Marshmallow"؛ Android 6.0) أو إصدار أحدث
    • اللغة التي تم ضبطها على Kotlin

  • الحصول على مفتاح واجهة برمجة تطبيقات وإضافته إلى مشروعك.

  • ثبّت مكتبة Compose لحزمة تطوير برامج "خرائط Google" في المشروع كما هو موضّح في القسم التالي

تثبيت

لتثبيت مكتبة Compose لحزمة تطوير برامج "خرائط Google" في مشروع "خرائط Google":

  1. أضِف التبعيات التالية إلى ملف build.gradle.kts على مستوى الوحدة:

      dependencies {

    // Android Maps Compose composables for the Maps SDK for Android
    implementation("com.google.maps.android:maps-compose:6.12.0")
}

  2. أعِد إنشاء مشروعك في "استوديو Android" لمزامنة هذه التغييرات.

إضافة خريطة إلى تطبيقك

يوضّح المثال التالي كيفية استخدام الدالة المركّبة GoogleMap لإضافة خريطة. 

val singapore = LatLng(1.35, 103.87)
val singaporeMarkerState = rememberUpdatedMarkerState(position = singapore)
val cameraPositionState = rememberCameraPositionState {
  position = CameraPosition.fromLatLngZoom(singapore, 10f)
}
GoogleMap(
  modifier = Modifier.fillMaxSize(),
  cameraPositionState = cameraPositionState
) {
  Marker(
    state = singaporeMarkerState,
    title = "Singapore",
    snippet = "Marker in Singapore"
  )
}

في هذا المثال، تشغل الخريطة الحد الأقصى للمساحة المسموح بها ويتم توسيط الكاميرا حول سنغافورة. يتم أيضًا إنشاء CameraPositionState وتوفيره في cameraPositionState لضبط موضع الكاميرا.

بعد ذلك، يستدعي المثال الدالة المركّبة Marker في محتوى الخريطة لإضافة محدِّد موقع إلى الخريطة.

لمقارنة هذا المثال بمثال يضيف خريطة باستخدام طرق العرض، يُرجى الاطّلاع على دليل البدء السريع QuickStart. لاحظ كيف تتطلب الدوال المركّبة تعليمات برمجية أقل، ولا داعي للقلق بشأن مراحل نشاط الخريطة.

ضبط خصائص على خريطة

يمكنك ضبط الخصائص على الخريطة من خلال توفير عنصر MapProperties أو عنصر MapUiSettings للخصائص ذات الصلة بواجهة المستخدم. يمكنك تعديل هذه العناصر لتفعيل إعادة تركيب الخريطة.

في المثال أدناه، استخدِم مفتاح تبديل، وهو أحد مكوّنات التصميم المتعدد الأبعاد، لتبديل عناصر التحكّم في التكبير/التصغير على الخريطة.

var uiSettings by remember { mutableStateOf(MapUiSettings()) }
var properties by remember {
  mutableStateOf(MapProperties(mapType = MapType.SATELLITE))
}

Box(Modifier.fillMaxSize()) {
  GoogleMap(
    modifier = Modifier.matchParentSize(),
    properties = properties,
    uiSettings = uiSettings
  )
  Switch(
    checked = uiSettings.zoomControlsEnabled,
    onCheckedChange = {
      uiSettings = uiSettings.copy(zoomControlsEnabled = it)
    }
  )
}

الخطوات التالية