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

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

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

  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 في محتوى الخريطة لإضافة علامة إلى الخريطة.

لمقارنة هذا المثال بمثال يضيف خريطة باستخدام "طرق العرض"، راجِع 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)
    }
  )
}

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