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

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

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

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

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

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

المتطلبات

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

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

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

  • نوع نموذج نشاط Compose فارغ يضيف هذا النموذج التبعيات اللازمة التي تتطلبها Jetpack Compose.
  ملاحظة: لا تنشئ مشروعًا من النوع نشاط "خرائط Google" عند استخدام 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)
    }
  )
}

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

• الاطّلاع على صفحة مشروع مكتبة Compose لحزمة تطوير برامج "خرائط Google" Maps Compose على GitHub.
• الاطّلاع على مستندات Jetpack Compose.