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

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

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

تحتوي مكتبة Maps Compose على دوال قابلة للإنشاء وأنواع بيانات تتيح لك تنفيذ العديد من المهام الشائعة. في ما يلي بعض الدوال القابلة للإنشاء وأنواع البيانات الشائعة الاستخدام:

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

للحصول على قائمة كاملة بجميع الدوال القابلة للإنشاء وأنواع البيانات، راجِع مرجع مكتبة Maps Compose.

المتطلبات

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

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

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

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

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

  • ثبِّت مكتبة Maps Compose في المشروع كما هو موضّح في القسم التالي.

تثبيت

لتثبيت مكتبة Maps Compose في مشروع "خرائط 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 Studio لمزامنة هذه التغييرات.

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

يوضّح المثال التالي كيفية استخدام الدالة البرمجية القابلة للإنشاء 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 للخصائص ذات الصلة بواجهة المستخدم. يمكنك تعديل هذه العناصر لتفعيل إعادة إنشاء الخريطة.

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

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)
    }
  )
}

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