הוספת מפה

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

סקירה כללית

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

הממשק והכיתות הראשיים לטיפול במפות:

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

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

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

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

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

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

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

הצגת הקוד

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

  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 ולהוסיף את המסגרות הנדרשות, פועלים לפי השלבים המפורטים במאמרים הבאים:

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

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

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

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

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

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

5. אם הוספתם את ה-fragment באופן סטטי, צריך לקבל את ה-handle של ה-fragment.

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

7. מקבלים אחיזה (handle) לאובייקט GoogleMap.

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

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

הוספת קטע באופן סטטי

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

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 ומגדירים אותו ל-מזהה המשאב (@+id/map) של R.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. מבצעים טרנזקציה שמוסיפה את הקטע לפעילות. למידע נוסף, ראו טרנזקציות מקוטעות.

לדוגמה:

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

      

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
getSupportFragmentManager()
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit();

      

הטמעת הממשק OnMapReadyCallback

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

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

      

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

      

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

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

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

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

      

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

      

אחזור של ה-handle ל-fragment ורישום של פונקציית הקריאה החוזרת

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

2. קוראים לשיטה getMapAsync כדי להגדיר את פונקציית ה-callback ב-fragment.

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

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

      

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

      

אחזור של אחיזה (handle) לאובייקט GoogleMap

משתמשים בשיטת ה-callback‏ onMapReady כדי לקבל אחיזה (handle) לאובייקט GoogleMap. הקריאה החוזרת מופעלת כשהמפה מוכנה לקבל קלט מהמשתמש. הוא מספק מופע שאינו null של הכיתה GoogleMap שאפשר להשתמש בו כדי לעדכן את המפה.

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

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

      

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

      

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

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

arrow_upwardהצגת פעילות שהושלמו

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

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