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

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

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

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

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

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

المتطلبات

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

  • نزِّل الإصدار Arctic Fox من "استوديو Android" وثبِّته.

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

    • نوع نموذج نشاط إنشاء فارغ يضيف هذا النموذج التبعيات اللازمة التي يتطلّبها Jetpack Compose.
    • يجب ضبط الحد الأدنى من حزمة تطوير البرامج (SDK) على المستوى 21 من واجهة برمجة التطبيقات: Android 5.0 (Lollipop) أو إصدار أحدث.
    • تم ضبط اللغة على 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)
    }
  )
}

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