ספרייה ליצירה של מפות Google

‫Jetpack Compose היא ערכת כלים הצהרתית ונייטיבית לממשק משתמש שמפשטת ומאיצה את פיתוח ממשק המשתמש. עם Jetpack Compose, אתם מתארים איך אתם רוצים שהאפליקציה תיראה, ו-Jetpack Compose כבר ידאג לכל השאר.

‫ספריית Maps Compose ל-SDK של מפות ל-Android היא קבוצה של פונקציות קומפוזביליות וסוגי נתונים בקוד פתוח, שאפשר להשתמש בהם עם Jetpack Compose כדי ליצור את האפליקציה.

ספריית Maps Compose מכילה פונקציות וסוגי נתונים שניתן להרכיב מהם קוד, ומאפשרים לבצע משימות נפוצות רבות. דוגמאות לפונקציות קומפוזביליות ולסוגי נתונים נפוצים:

קומפוזביליות	תיאור
Circle	פונקציה קומפוזבילית להוספת עיגול למפה.
GoogleMap	פונקציה קומפוזבילית להוספת מפה.
GroundOverlay	פונקציה קומפוזבילית להוספת שכבת-על של קרקע למפה.
MapProperties	סוג הנתונים של מאפיינים שאפשר לשנות במפה.
MapUISettings	סוג הנתונים של הגדרות שקשורות לממשק משתמש במפה.
סמן	פונקציה קומפוזבילית להוספת סמן למפה.
Polygon	פונקציה קומפוזבילית להוספת פוליגון למפה.
קו פוליגוני	פונקציה קומפוזבילית להוספת קו פוליגוני למפה.
TileOverlay	פונקציה קומפוזבילית להוספת שכבה מעל קטעי המפה למפה.

רשימה מלאה של כל הפונקציות והטיפוסים של הנתונים שניתן להרכיב מופיעה במאמר חומר עזר בנושא ספריית Maps Compose.

דרישות

כדי להשתמש בספריית Maps Compose עם ה-SDK של מפות ל-Android, צריך:

• מורידים ומתקינים את Android Studio Arctic Fox.

• יוצרים פרויקט במפות Google ב-Android Studio עם:

  • סוג התבנית הוא Empty Compose Activity (פעילות ריקה של יצירת הודעה). התבנית הזו מוסיפה את התלות הנדרשת על ידי Jetpack Compose.
  הערה: כשמשתמשים ב-Jetpack Compose, אין ליצור פרויקט מסוג Google Maps Activity.
  • גרסת ה-SDK המינימלית מוגדרת לרמת Android API‏ 23 (Marshmallow;‏ Android 6.0) או לגרסה מתקדמת יותר.
  • השפה Kotlin מוגדרת.

• מקבלים מפתח API ומוסיפים אותו לפרויקט.

• מתקינים את ספריית Maps Compose בפרויקט כמו שמתואר בקטע הבא.

התקנה

כדי להתקין את ספריית Maps Compose בפרויקט של מפות Google:

1. מוסיפים את יחסי התלות הבאים לקובץ build.gradle.kts ברמת המודול:

     dependencies {
   
       // Modern Android projects use version catalogs to manage dependencies. To include the Maps Compose library,
       // first add the following to your gradle/libs.versions.toml file:
       //
       // [versions]
       // mapsCompose = "8.4.0"
       //
       // [libraries]
       // maps-compose = { module = "com.google.maps.android:maps-compose", version.ref = "mapsCompose" }
       //
       // Android Maps Compose composables for the Maps SDK for Android
       implementation(libs.maps.compose)
   
       // If your project does not use a version catalog, you can use the following dependency instead:
       //
       //    implementation("com.google.maps.android:maps-compose:8.4.0")
   }

2. כדי לסנכרן את השינויים האלה, צריך לבצע מחדש את ה-build של הפרויקט ב-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 כדי להגדיר את מיקום המצלמה.

בדוגמה הבאה מבוצעת קריאה לרכיב ה-Composable‏ Marker בתוכן של המפה כדי להוסיף סמן למפה.

כדי להשוות את הדוגמה הזו לדוגמה שמוסיפה מפה באמצעות Views, אפשר לעיין ב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)
    }
  )
}

המאמרים הבאים

• אפשר לעיין בדף הפרויקט של ספריית Maps Compose ב-GitHub.
• צפייה בתיעוד של Jetpack Compose.