הוספת מפה

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

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

סקירה כללית

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

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

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

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

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

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

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

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

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

הצגת הקוד

הקוד הבא הוא מתוך פעילות Java מלאה שמשמשת בנושא הזה כשמוסיפים fragment באופן סטטי. פרויקט 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"));
      }
  }

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

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

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

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

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

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

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

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

  3. הטמעה של הממשק OnMapReadyCallback.

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

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

  6. רושמים את הפונקציה להתקשרות חזרה.

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

לדוגמה:

Kotlin

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

Java

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

הטמעה של הממשק OnMapReadyCallback

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

Kotlin

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

Java

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

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

בשיטה onCreate של הפעילות, קוראים לשיטה 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 ורושמים את הקריאה החוזרת

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

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

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

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 שאפשר להשתמש בה כדי לעדכן את המפה.

בדוגמה הזו, הקריאה החוזרת 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 (אפס מעלות רוחב ואפס מעלות אורך).

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

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

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

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