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

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

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

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

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

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

المتطلبات

لاستخدام مكتبة Compose لحزمة تطوير برامج "خرائط Google" مع حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط 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.1.0")
}

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

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

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

val singapore = LatLng(1.35, 103.87)
val singaporeMarkerState = rememberMarkerState(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 في محتوى الخريطة لإضافة علامة إلى الخريطة.

لمقارنة هذا المثال بمثال يضيف خريطة باستخدام "المشاهدات"، اطّلِع على البدء السريع. لاحظ أنّ الوظائف القابلة للتجميع تتطلّب قدرًا أقل من الرموز البرمجية، ولا داعي للقلق بشأن دورة حياة الخريطة.

ضبط المواقع على خريطة

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

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

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

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