הוספת מפה

בחירת פלטפורמה: Android iOS JavaScript

בנושא הזה מוסבר איך להוסיף מפה בסיסית לאפליקציה ל-Android אחרי שמגדירים את הפרויקט לשימוש ב-SDK של מפות ל-Android. אחרי שמוסיפים מפה, אפשר לשנות את סוג המפה והתכונות שלה.

סקירה כללית

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

הממשק והמחלקות העיקריים לטיפול במפות:

  • ‫GoogleMap — נקודת הכניסה לניהול התכונות והנתונים של המפה. האפליקציה יכולה לגשת לאובייקט GoogleMap רק אחרי שהוא אוחזר מאובייקט SupportMapFragment או MapView.

  • ‫SupportMapFragment – קטע לניהול מחזור החיים של אובייקט GoogleMap.

  • ‫MapView – תצוגה לניהול מחזור החיים של אובייקט GoogleMap.

  • ‫OnMapReadyCallback — ממשק קריאה חוזרת שמטפל באירועים ובאינטראקציות של המשתמשים באובייקט GoogleMap.

אובייקט GoogleMap מבצע את הפעולות הבאות באופן אוטומטי:

  • מתבצעת התחברות לשירות מפות Google.
  • הורדת משבצות המפה.
  • הצגת משבצות במסך המכשיר.
  • הצגת אמצעי בקרה שונים, כמו הזזה ושינוי מרחק התצוגה.
  • תגובה לתנועות של הזזה ושינוי מרחק התצוגה על ידי הזזת המפה והגדלה או הקטנה של התצוגה.

כדי להשתמש באובייקט GoogleMap באפליקציה, צריך להשתמש באובייקט SupportMapFragment או MapView בתור אובייקט מאגר למפה, ואז לאחזר את האובייקט GoogleMap מהמאגר. מכיוון שמחלקות הקונטיינר נגזרות מ-fragment או מ-view של Android, הן מספקות למפה את יכולות ניהול מחזור החיים וממשק המשתמש של מחלקות הבסיס שלהן ב-Android. הכיתה SupportMapFragment היא הקונטיינר המודרני והנפוץ יותר לאובייקט GoogleMap.

הצגת הקוד

הקוד הבא הוא מפעילות Java המלאה שמשמשת בנושא הזה כשמוסיפים מקטע באופן סטטי. פרויקט Android נוצר מהתבנית Empty project, ואז עודכן על סמך המדריך הגדרת הפרויקט. אחרי שתבצעו את השלבים שמפורטים כאן, יכול להיות שהקוד שלכם יהיה שונה בהתאם לתבנית הפרויקט.

  package com.example.mapsetup;

  import androidx.appcompat.app.AppCompatActivity;

  import android.os.Bundle;

  import com.google.android.gms.maps.GoogleMap;
  import com.google.android.gms.maps.OnMapReadyCallback;
  import com.google.android.gms.maps.SupportMapFragment;
  import com.google.android.gms.maps.model.LatLng;
  import com.google.android.gms.maps.model.MarkerOptions;

  // Implement OnMapReadyCallback.
  public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          // Set the layout file as the content view.
          setContentView(R.layout.activity_main);

          // Get a handle to the fragment and register the callback.
          SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                  .findFragmentById(R.id.map);
          mapFragment.getMapAsync(this);

      }

      // Get a handle to the GoogleMap object and display marker.
      @Override
      public void onMapReady(GoogleMap googleMap) {
          googleMap.addMarker(new MarkerOptions()
                  .position(new LatLng(0, 0))
                  .title("Marker"));
      }
  }

כדי להוסיף מפה:

בקטע הזה מוסבר איך להוסיף מפה בסיסית באמצעות קטע כקונטיינר של מפה, אבל אפשר גם להשתמש בתצוגה. לדוגמה, ראו RawMapViewDemoActivity ב-GitHub.

השלבים הבסיסיים:

  1. כדי לקבל את ה-SDK, להשיג מפתח API ולהוסיף את ה-frameworks הנדרשים, פועלים לפי השלבים הבאים:

    1. הגדרה במסוף Google Cloud

    2. שימוש במפתח API

    3. הגדרת פרויקט ב-Android Studio

  2. מוסיפים אובייקט SupportMapFragment לפעילות שתטפל במפה. אפשר להוסיף את החלק באופן סטטי או דינמי.

  3. מטמיעים את הממשק OnMapReadyCallback.

  4. מגדירים את קובץ הפריסה כתצוגת התוכן.

  5. אם הוספתם את המקטע באופן סטטי, צריך לקבל נקודת אחיזה למקטע.

  6. רושמים את הקריאה החוזרת (callback).

  7. מקבלים נקודת אחיזה לאובייקט GoogleMap.

הוספת אובייקט SupportMapFragment

אפשר להוסיף אובייקט SupportMapFragment לאפליקציה באופן סטטי או דינמי. הדרך הפשוטה ביותר היא להוסיף אותו באופן סטטי. אם מוסיפים את ה-fragment באופן דינמי, אפשר לבצע פעולות נוספות ב-fragment, כמו הסרה והחלפה שלו בזמן הריצה.

כדי להוסיף מקטע באופן סטטי

בקובץ הפריסה של הפעילות שתטפל במפה:

  1. מוסיפים רכיב fragment.
  2. מוסיפים את הצהרת השם xmlns:map="http://schemas.android.com/apk/res-auto". כך אפשר להשתמש בmaps מאפייני XML מותאמים אישית.
  3. באלמנט fragment, מגדירים את המאפיין android:name לערך com.google.android.gms.maps.SupportMapFragment.
  4. ברכיב fragment, מוסיפים את המאפיין android:id ומגדירים אותו למזהה המשאב R.id.map‏ (@+id/map).

לדוגמה, הנה קובץ פריסה מלא שכולל רכיב fragment:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

כדי להוסיף קטע באופן דינמי

בפעילות:

  1. יוצרים מכונה של SupportMapFragment.
  2. מבצעים טרנזקציה שמוסיפה את הפרגמנט לפעילות. מידע נוסף זמין במאמר Fragment Transactions.

לדוגמה:

Kotlin

val mapFragment = SupportMapFragment.newInstance()
supportFragmentManager
    .beginTransaction()
    .add(R.id.map_container, mapFragment)
    .commit()

Java

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
FragmentTransaction fragmentTransaction =
        getSupportFragmentManager().beginTransaction();
fragmentTransaction.add(R.id.map_container, mapFragment);
fragmentTransaction.commit();

מטמיעים את הממשק OnMapReadyCallback

מעדכנים את הצהרת הפעילות באופן הבא:

Kotlin

class MainActivity :
    AppCompatActivity(),
    OnMapReadyCallback {

    // ...
}

Java

class MainActivity extends AppCompatActivity implements OnMapReadyCallback {
    // ...
}

הגדרת תצוגת התוכן

ב-method onCreate של הפעילות, מפעילים את ה-method setContentView ומגדירים את קובץ הפריסה כתצוגת התוכן.

לדוגמה, אם שם קובץ הפריסה הוא main.xml:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)
}

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
}

מקבלים נקודת אחיזה ל-fragment ורושמים את הקריאה החוזרת (callback)

  1. כדי לקבל נקודת אחיזה למקטע, צריך לבצע קריאה ל-method‏ FragmentManager.findFragmentById ולהעביר לה את מזהה המשאב של המקטע בקובץ הפריסה. אם הוספתם את המקטע באופן דינמי, דלגו על השלב הזה כי כבר אחזרתם את נקודת האחיזה.

  2. מפעילים את ה-method‏ getMapAsync כדי להגדיר את הקריאה החוזרת (callback) ב-fragment.

לדוגמה, אם הוספתם את הקטע באופן סטטי:

Kotlin

val mapFragment = supportFragmentManager
    .findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)

Java

SupportMapFragment mapFragment =
        (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

מקבלים נקודת אחיזה לאובייקט GoogleMap

משתמשים בשיטת הקריאה החוזרת onMapReady כדי לקבל נקודת אחיזה לאובייקט GoogleMap. הקריאה החוזרת מופעלת כשהמפה מוכנה לקבל קלט מהמשתמש. היא מספקת מופע שאינו null של המחלקה GoogleMap, שבו אפשר להשתמש כדי לעדכן את המפה.

בדוגמה הזו, פונקציית הקריאה החוזרת (callback) onMapReady מאחזרת נקודת אחיזה לאובייקט GoogleMap, ואז סמן מתווסף למפה:

Kotlin

override fun onMapReady(googleMap: GoogleMap) {
    googleMap.addMarker(
        MarkerOptions()
            .position(LatLng(0.0, 0.0))
            .title("Marker"),
    )
}

Java

@Override
public void onMapReady(GoogleMap googleMap) {
    googleMap.addMarker(new MarkerOptions().position(new LatLng(0, 0)).title("Marker"));
}

צילום מסך עם המפה והסמן במרכז Null Island.

אחרי שבונים ומריצים את האפליקציה, מוצגת מפה עם סמן ב-Null Island (אפס מעלות קו רוחב ואפס מעלות קו אורך).

הקוד של הפעילות המלאה:

לצפייה בפעילות המלאה

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

אחרי שמסיימים את השלבים האלה, אפשר לקבוע את הגדרות המפה.