Android Academy · درس

عرض خريطة

أضف Google Maps إلى تطبيقك

عرض خريطة درس مجاني في Android Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Android Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Android Academy 4 دروس في المجموع.

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

تحوّل الخرائط الإحداثيات الخام إلى شيء يستطيع المستخدمون رؤيته واستكشافه. ستضيفون في هذا الدرس Google Map تفاعلية إلى شاشة Jetpack Compose باستخدام المكتبة الرسمية maps-compose.

وبحلول النهاية، ستتمكنون من إضافة خريطة حقيقية قابلة للتحريك والتكبير إلى أي composable. لنضع اللبنات الأساسية في مكانها.

مكتبة Maps Compose

توفر Google غلافًا متوافقًا مع Compose يسمى maps-compose. وهو يعرض composable باسم GoogleMap، لذلك لن تضطروا إلى التعامل مباشرةً مع MapView القديم الخاص بـ XML.

أضيفوا هذه التبعيات إلى build.gradle.kts الخاص بالوحدة. ويُعد artifact play-services-maps هو SDK الأساسي، بينما تكيّفه maps-compose للعمل مع Compose.

// build.gradle.kts (module)
dependencies {
    implementation("com.google.maps.android:maps-compose:6.1.0")
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

الحصول على مفتاح API

يتطلب Google Maps مفتاح API. أنشئوا مفتاحًا في Google Cloud Console، وفعّلوا Maps SDK for Android، ثم ضعوا المفتاح في AndroidManifest.xml داخل وسم <application>.

لا تضعوا المفتاح مطلقًا بشكل مباشر في الشفرة المصدرية التي تنشرونها للعامة. خزّنوه في local.properties وأدرجوه عبر قيمة placeholder في البيان.

<!-- AndroidManifest.xml, inside <application> -->
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

أول GoogleMap لكم

أبسط خريطة هي composable واحدة من نوع GoogleMap. امنحوها Modifier.fillMaxSize()، وستحصلون فورًا على خريطة قابلة للتحريك والتكبير.

لا تحتاج إلى عناصر فرعية لعرضها؛ إذ تُرسم مربعات Google تلقائيًا بمجرد أن يصبح مفتاح API صالحًا.

import com.google.maps.android.compose.GoogleMap

@Composable
fun MapScreen() {
    GoogleMap(
        modifier = Modifier.fillMaxSize()
    )
}

التحكم في الكاميرا

تحدد الكاميرا المكان الذي تنظر إليه الخريطة ودرجة تكبيرها. وتوفرون لها CameraPositionState يتم الاحتفاظ به عبر عمليات إعادة التركيب.

أنشئوا CameraPosition من LatLng، أي خط العرض وخط الطول، بالإضافة إلى مستوى التكبير. وكلما ارتفع مستوى التكبير، اقترب العرض أكثر.

import com.google.android.gms.maps.model.CameraPosition
import com.google.android.gms.maps.model.LatLng
import com.google.maps.android.compose.rememberCameraPositionState

val sanFrancisco = LatLng(37.7749, -122.4194)
val cameraPositionState = rememberCameraPositionState {
    position = CameraPosition.fromLatLngZoom(sanFrancisco, 12f)
}

توصيل الكاميرا بالخريطة

مرّر cameraPositionState إلى GoogleMap لكي تُفتح الخريطة متمركزةً في الموضع الذي تريده. وبما أن الحالة محفوظة، فإن تحريك المستخدم للخريطة وتغيير مستوى التكبير يستمران بعد إعادة التركيب.

@Composable
fun CenteredMap() {
    val sf = LatLng(37.7749, -122.4194)
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(sf, 12f)
    }
    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        cameraPositionState = cameraPositionState
    )
}

خصائص الخريطة

يُستخدم MapProperties لإعداد ما تعرضه الخريطة. وتشمل الخيارات الشائعة نوع الخريطة (العادية أو القمر الصناعي أو التضاريس أو الهجينة)، وما إذا كانت نقطة my-location الزرقاء مفعّلة.

تذكّر كائن الخصائص حتى لا يُعاد إنشاؤه عند كل إعادة تركيب.

import com.google.maps.android.compose.MapProperties
import com.google.maps.android.compose.MapType

val properties = remember {
    MapProperties(
        mapType = MapType.NORMAL,
        isMyLocationEnabled = false
    )
}

إعدادات واجهة الخريطة

يتحكم MapUiSettings في عناصر التحكم الظاهرة على الشاشة: أزرار التكبير، والبوصلة، وزر my-location، والإيماءات.

عطّل عناصر التحكم التي لا تحتاج إليها للحصول على مظهر أكثر ترتيبًا — فعلى سبيل المثال، أخفِ أزرار التكبير مع إبقاء إيماءات التكبير بالضمّ مفعّلة.

import com.google.maps.android.compose.MapUiSettings

val uiSettings = remember {
    MapUiSettings(
        zoomControlsEnabled = false,
        compassEnabled = true,
        scrollGesturesEnabled = true,
        zoomGesturesEnabled = true
    )
}

جمع كل الأجزاء

اجمع الكاميرا والخصائص وإعدادات واجهة المستخدم في خريطة واحدة مُعدّة. هذا هو الشكل المعتاد لشاشة خريطة في تطبيق إنتاجي.

@Composable
fun ConfiguredMap() {
    val sf = LatLng(37.7749, -122.4194)
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(sf, 12f)
    }
    val properties = remember { MapProperties(mapType = MapType.NORMAL) }
    val uiSettings = remember { MapUiSettings(zoomControlsEnabled = false) }

    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        cameraPositionState = cameraPositionState,
        properties = properties,
        uiSettings = uiSettings
    )
}

التفاعل مع النقرات على الخريطة

يوفّر GoogleMap دوالًا لردّ النداء مثل onMapClick. استخدمها للاستجابة عندما ينقر المستخدم على الخريطة — مثلًا لالتقاط كائن LatLng اختاره المستخدم.

احتفظ بالنقطة التي نُقر عليها في الحالة، حتى تتمكن واجهة المستخدم من التفاعل معها.

@Composable
fun ClickableMap() {
    var picked by remember { mutableStateOf<LatLng?>(null) }
    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        onMapClick = { latLng -> picked = latLng }
    )
    picked?.let { p ->
        Text("Picked: ${p.latitude}, ${p.longitude}")
    }
}

تُدار دورة الحياة تلقائيًا

مع MapView التقليدي المستند إلى XML، كان عليك تمرير كل حدث من أحداث دورة الحياة يدويًا. أما مكتبة maps-compose فتربط الخريطة بدورة حياة التركيب تلقائيًا.

وهذا يعني عدم الحاجة إلى إعداد يدوي لـ onResume/onPause/onDestroy — وسببًا إضافيًا لتفضيل Compose API للشاشات الجديدة.

اختبار سريع

ما كائن حالة Compose الذي تتذكره وتمرّره إلى GoogleMap للتحكم في موضع تمركز الخريطة ومستوى تكبيرها؟

مراجعة

يمكنك الآن وضع خريطة Google حقيقية في Compose:

أضف maps-compose وplay-services-maps ومفتاح API في ملف manifest.
اعرض خريطة باستخدام المكوّن القابل للتركيب GoogleMap.
حدّد مركزها ومستوى تكبيرها باستخدام rememberCameraPositionState وCameraPosition.
خصّصها باستخدام MapProperties وMapUiSettings، وتفاعل مع النقرات باستخدام onMapClick.

التالي: الحصول على الموقع الفعلي للجهاز لتمركز الخريطة على المستخدم.

الأسئلة الشائعة

هل درس «عرض خريطة» مجاني؟

نعم — نص درس «عرض خريطة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Android Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Android Academy 4 دروس في المجموع.

ماذا ستتعلم في «عرض خريطة»؟

أضف Google Maps إلى تطبيقك تتمرن على Android Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Android Academy؟

لا تُشترط خبرة سابقة. Android Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «عرض خريطة»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Android Academy هذا؟

نعم. كل درس في Android Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Android Academy