הגדרת מפה

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

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

סקירה כללית

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

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

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

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

תוך כדי זמן הריצה, אפשר להגדיר את ההגדרות האלה ואת הגדרות נוספות על ידי עדכון האובייקט GoogleMap ב-callback של 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);

    }
}

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

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

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

• מגדירים את הפרויקט באופן ידני עבור ה-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.

• mapColorScheme — מציין את ערכת הצבעים של מפה רגילה ומפה של פני השטח. הערכים כוללים את light (ברירת המחדל), dark ו-follow_system, כלומר שימוש בהגדרת המערכת הנוכחית על סמך הגדרת המכשיר עבור UI_NIGHT_MODE_MASK. מידע נוסף זמין במאמר סכמת הצבעים של המפה.

כדי להשתמש במאפיינים המותאמים אישית האלה בקובץ הפריסה, צריך לכלול בו את הצהרת מרחב השמות הבאה. אפשר לבחור כל מרחב שמות, הוא לא חייב להיות 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:mapColorScheme="dark"
  map:uiCompass="false"
  map:uiRotateGestures="true"
  map:uiScrollGestures="false"
  map:uiTiltGestures="true"
  map:uiZoomControls="false"
  map:uiZoomGestures="true"/>

הערה: אם אתם משתמשים ב-Maps SDK ל-Android עם רישיון לתוכנית Premium של הפלטפורמה של מפות 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, השתמשו ב-method הסטטי של המפעל SupportMapFragment.newInstance(GoogleMapOptions options) כדי ליצור את ה-fragment ולהעביר את ההגדרות.
• אם אתם משתמשים ב-MapView, השתמשו ב-constructor‏ MapView(Context, GoogleMapOptions) והעבירו את ההגדרות.

התאמת המפה לשוק המקומי (לוקליזציה)

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

defaultConfig {
    resConfigs "en", "fr", "es", "zh", "de", "ja", "ru", "ko", "pt", "in"
}

מידע נוסף על לוקליזציה של אפליקציות ל-Android

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

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

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

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

ערכת הצבעים של המפה

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

כברירת מחדל, המפה מוצגת במצב בהיר. ערך ההגדרה הנוכחי של המערכת מבוסס על ההגדרה של המכשיר עבור UI_NIGHT_MODE_MASK.

Kotlin

mapFragment = SupportMapFragment.newInstance(GoogleMapOptions().mapColorScheme(MapColorScheme.DARK).mapId(mapId2))

Java

mapFragment = SupportMapFragment.newInstance(new GoogleMapOptions().mapColorScheme(MapColorScheme.DARK).mapId(mapId2));

אפשר להחליף את ערכת הצבעים באמצעות ה-method‏ GoogleMap.setMapColorScheme() כדי להגדיר את הסגנון הנוכחי למצב כהה, למצב בהיר או בהתאם להגדרות המערכת.

Kotlin

googleMap.setMapColorScheme(MapColorScheme.DARK)
googleMap.setMapColorScheme(MapColorScheme.LIGHT)
googleMap.setMapColorScheme(MapColorScheme.FOLLOW_SYSTEM)

Java

googleMap.setMapColorScheme(MapColorScheme.DARK);
googleMap.setMapColorScheme(MapColorScheme.LIGHT);
googleMap.setMapColorScheme(MapColorScheme.FOLLOW_SYSTEM);

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

הגדרת צבע הרקע

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

Kotlin

private val googleMapOptions: GoogleMapOptions =
    GoogleMapOptions().backgroundColor(Color.argb(255, 255, 0, 0));

Java

private GoogleMapOptions options = new GoogleMapOptions().backgroundColor(Color.argb(255, 255, 0, 0));

הערה: אין תמיכה בערכים של אטימות ב'צבע רקע'.

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