הגדרת מפה

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

במאמר הזה נסביר איך להגדיר מפה שנוספה לאפליקציה ל-Android באמצעות ה-SDK של מפות Google ל-Android.

סקירה כללית

אחרי שמוסיפים מפה לאפליקציה, אפשר לקבוע את ההגדרות הראשוניות ואת זמן הריצה של המפה. יש לבחור את ההגדרות הראשוניות בהתאם לשיטה שבה הוספתם את מאגר המפה (SupportMapFragment או MapView) באופן סטטי או דינמי. אם הקונטיינר של המפה נוסף באופן סטטי, תוכלו לקבוע את ההגדרות הראשוניות של המפה בקובץ הפריסה. אם הוא נוסף באופן דינמי, אפשר לקבוע את ההגדרות הראשוניות בקריאה החוזרת (callback) של OnCreate עם אובייקט GoogleMapOptions.

לפרטים על הוספת מאגר מפה, ראה הוספת מפה.

ההגדרות הראשוניות של המפה כוללות את ההגדרות הבאות:

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

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

דוגמה

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

ההגדרות הראשוניות נקבעות בקובץ הפריסה:

• הפעלת אמצעי הבקרה לשינוי מרחק התצוגה.
• הפעלה של תנועות סיבוב הפקדים.
• מגדירים את הטיית המפה ל-30.

הגדרות זמן הריצה:

• מציבים את המצלמה בקיוטו יפן.
• הפעלת סוג המפה ההיברידית.
• הפעל את השכבה 'תנועה'.

הגדרות ראשוניות

<?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"
    xmlns:tools="http://schemas.android.com/tools"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    map:uiZoomControls="true"
    map:uiRotateGestures="true"
    map:cameraTilt="30" />
    

הגדרות זמן ריצה

package com.example.mapsetup;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.gms.maps.CameraUpdateFactory;
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;

public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

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

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

    }

    // Update the map configuration at runtime.
    @Override
    public void onMapReady(GoogleMap googleMap) {
        // Set the map coordinates to Kyoto Japan.
        LatLng kyoto = new LatLng(35.00116, 135.7681);
        // Set the map type to Hybrid.
        googleMap.setMapType(GoogleMap.MAP_TYPE_HYBRID);
        // Add a marker on the map coordinates.
        googleMap.addMarker(new MarkerOptions()
                .position(kyoto)
                .title("Kyoto"));
        // Move the camera to the map coordinates and zoom in closer.
        googleMap.moveCamera(CameraUpdateFactory.newLatLng(kyoto));
        googleMap.moveCamera(CameraUpdateFactory.zoomTo(15));
        // Display traffic.
        googleMap.setTrafficEnabled(true);

    }
}

לפני שמתחילים

לפני שתתחילו, תוכלו להגדיר פרויקט ולהוסיף מפה בסיסית באמצעות האפשרויות הבאות:

• יוצרים אפליקציה באמצעות התבנית 'מפות' ל-Android Studio. התבנית של מפות Google מגדירה את הפרויקט באופן אוטומטי ומוסיפה מפה בסיסית. מקטע משמש כמאגר של המפה ומתווסף באופן סטטי. לפרטים נוספים, ראו quickstart.

• תוכלו להגדיר את הפרויקט באופן ידני עבור ה-SDK ולהוסיף מפה בסיסית. כך תוכלו להשתמש בכל תבנית של Android ולהוסיף מפה לאפליקציה קיימת.

הגדרת מפה אחרי הוספה סטטית שלה

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

SDK של מפות ל-Android מגדיר קבוצה של מאפייני XML מותאמים אישית עבור SupportMapFragment או MapView, שניתן להשתמש בהם על מנת להגדיר את המצב הראשוני של המפה ישירות מקובץ הפריסה. המאפיינים הבאים מוגדרים כרגע:

• mapType — סוג המפה להצגה. הערכים החוקיים כוללים: none, normal, hybrid, satellite ו-terrain.

• cameraTargetLat, cameraTargetLng, cameraZoom, cameraBearing, cameraTilt – המיקום הראשוני של המצלמה. לפרטים נוספים, אפשר לעיין במדריך בנושא מצלמה ותצוגות.

• uiZoomControls, uiCompass — מציינת אם פקדי הזום והמצפן יוצגו. פרטים נוספים מופיעים בכתובת UiSettings.

• uiZoomGestures, uiScrollGestures, uiRotateGestures, uiTiltGestures — מציין אם תנועות מסוימות מופעלות. לפרטים נוספים, ראו UiSettings.

• zOrderOnTop – מציין אם פני השטח של תצוגת המפה מוצגים על גבי חלון המפה, פקדי המפה וכל אובייקט בחלון. אפשר לקרוא פרטים נוספים בכתובת SurfaceView.setZOrderOnTop(boolean).

• useViewLifecycle — חוקי רק עם אובייקט SupportMapFragment. מציין אם מחזור החיים של המפה צריך להיות מקושר לתצוגת המקטע או למקטע עצמו. כאן יש פרטים נוספים.

• liteMode — true כדי להפעיל מצב בסיסי. אחרת, false.

כדי להשתמש במאפיינים המותאמים אישית האלה בקובץ הפריסה, הוא צריך לכלול את הצהרת מרחב השמות הבאה. אפשר לבחור כל מרחב שמות, הוא לא חייב להיות map:

xmlns:map="http://schemas.android.com/apk/res-auto"

לאחר מכן אפשר להוסיף את המאפיינים עם הקידומת map: לקובץ הפריסה.

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

<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"
  map:cameraBearing="112.5"
  map:cameraTargetLat="-33.796923"
  map:cameraTargetLng="150.922433"
  map:cameraTilt="30"
  map:cameraZoom="13"
  map:mapType="normal"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

הערה: אם אתם משתמשים ב-SDK של מפות ל-Android עם רישיון לתוכנית פרימיום של הפלטפורמה של מפות Google, עליכם להוסיף לכל מאפיין את התחילית m4b_. לדוגמה, כשמציינים את מאפיין סוג המפה, צריך להשתמש ב-m4b_mapType במקום ב-mapType. כשמציינים אמצעי בקרה לשינוי מרחק התצוגה, צריך להשתמש ב-m4b_uiZoomControls במקום ב-uiZoomControls וכן הלאה.

הגדרת מפה אחרי שמוסיפים אותה באופן דינמי

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

במקרה שמוסיפים SupportMapFragment או MapView באופן דינמי, אפשר להגדיר את המצב הראשוני של המפה באובייקט GoogleMapOptions. האפשרויות הזמינות הן אותן האפשרויות שזמינות בקובץ הפריסה. אפשר ליצור GoogleMapOptions באופן הבא:

Kotlin

val options = GoogleMapOptions()

      

Java

GoogleMapOptions options = new GoogleMapOptions();

      

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

Kotlin

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false)

      

Java

options.mapType(GoogleMap.MAP_TYPE_SATELLITE)
    .compassEnabled(false)
    .rotateGesturesEnabled(false)
    .tiltGesturesEnabled(false);

      

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

• אם משתמשים ב-SupportMapFragment, צריך להשתמש בשיטת היצרן הסטטית SupportMapFragment.newInstance(GoogleMapOptions options) כדי ליצור את המקטע ולהעביר אותו בהגדרות.
• אם משתמשים ב-MapView, צריך להשתמש ב-constructor של MapView(Context, GoogleMapOptions) ולהעביר אותו בהגדרות.

הגדרה של שכבת התנועה

ניתן להציג נתוני תנועה במפה על ידי הפעלת שכבת התנועה. אפשר להפעיל ולהשבית את שכבת התנועה על ידי קריאה ל-method setTrafficEnabled(), ולבדוק אם שכבת התנועה פועלת כרגע על ידי קריאה לשיטה isTrafficEnabled(). בצילום המסך הבא מוצגת מפה שבה שכבת התנועה מופעלת.

הגדרת סוג המפה

כדי להגדיר את סוג המפה, קוראים לשיטה setMapType. לדוגמה, כדי להציג מפת לוויין:

Kotlin

// Sets the map type to be "hybrid"
map.mapType = GoogleMap.MAP_TYPE_HYBRID

      

Java

// Sets the map type to be "hybrid"
map.setMapType(GoogleMap.MAP_TYPE_HYBRID);

      

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

הגדרת בניינים בתלת ממד

בערים רבות, בעת צפייה מקרוב, הבניינים בתלת-ממד יהיו גלויים, כפי שניתן לראות בתמונה למטה של ונקובר, קנדה. אפשר להשבית את הבניינים התלת-ממדיים על ידי קריאה ל-GoogleMap.setBuildingsEnabled(false).

הגדרת הגדרות של מפת פנים

כשמגבים את מרחק התצוגה, המפה מציגה תוכניות קומה של מרחבים פנימיים כמו נמלי תעופה, קניונים, חנויות קמעונאיות גדולות ותחנות תחבורה ציבורית. תוכניות הקומה האלה, שנקראות 'מפות פנים', מוצגות עבור סוגי המפות 'רגיל' ו'לוויין' (GoogleMap.MAP_TYPE_NORMAL ו-GoogleMap.MAP_TYPE_SATELLITE). הן מופעלות באופן אוטומטי כשהמשתמש מגדיל את התצוגה, והן נעלמות כשהמפה מקטינה את התצוגה.

הודעה על הוצאה משימוש: בגרסה עתידית, מפות פנים יהיו זמינות רק בסוג המפה normal. החל מגרסה עתידית זו, לא תהיה תמיכה במפות פנים במפות satellite, terrain או hybrid. גם במקומות שבהם אין תמיכה בפנים, isIndoorEnabled() ימשיך להחזיר את הערך שהוגדר באמצעות setIndoorEnabled(), כמו שהוא עושה עכשיו. כברירת מחדל, setIndoorEnabled הוא true. נתוני הגרסה יודיעו לך כאשר התמיכה בתוך מבנים לא תהיה זמינה בסוגי המפות האלה.

לפניכם סיכום של הפונקציונליות של מפות הפנים ב-API:

• אפשר להשבית את מפות הפנים באמצעות GoogleMap.setIndoorEnabled(false). מפות פנים מופעלות כברירת מחדל. מפות פנים מוצגות במפה אחת בכל פעם. כברירת מחדל, זוהי המפה הראשונה שנוספה לאפליקציה. כדי להציג מפות פנים במפה אחרת, צריך להשבית אותן במפה הראשונה ולאחר מכן ללחוץ על setIndoorEnabled(true) במפה השנייה.
• כדי להשבית את בורר הקומות שמוגדר כברירת מחדל (בורר הרצפה), צריך להתקשר אל GoogleMap.getUiSettings().setIndoorLevelPickerEnabled(false). מידע נוסף זמין במאמר אינטראקציה עם המפה.
• OnIndoorStateChangeListener — מגדיר מאזינים שמזהים מתי בניין נכנס למוקד או מופעל שלב בבניין. מידע נוסף מופיע בקטע אינטראקציה עם המפה.
• getFocusedBuilding – מאחזר את הבניין שנמצא במיקוד. לאחר מכן אפשר למצוא את הרמה הפעילה על ידי התקשרות אל IndoorBuilding.getActiveLevelIndex().
• העיצוב של מפת הבסיס לא משפיע על מפות פנים.

הגדרת מרווח פנימי במפה

בסרטון הזה מוצגת דוגמה למרווח פנימי של מפה.

מפת Google תוכננה למלא את כל האזור המוגדר על ידי רכיב הקונטיינר שלו, בדרך כלל MapView או SupportMapFragment. כמה היבטים של האופן שבו המפה מוצגת וההתנהגות שלה מוגדרים בהתאם למידות של הקונטיינר שלה:

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

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

• תנועות המצלמה דרך קריאות ל-API או לחיצות לחצנים (לדוגמה, מצפן, המיקום שלי, לחצני מרחק מתצוגה) הן יחסיות לאזור המרופד.
• השיטה getCameraPosition מחזירה את המרכז של האזור המרופד.
• השיטות Projection ו-getVisibleRegion מחזירות את האזור המרווח.
• הפקדים של ממשק המשתמש מקוזזים מקצה הקונטיינר במספר הפיקסלים שצוין.

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

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