הוספת מפה מעוצבת

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

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

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

העיצוב פועל רק בסוג המפה normal. העיצוב לא משפיע מפות פנים.

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

קבל את הקוד

שכפול או הורדה של מאגר הדוגמאות ל-Android API גרסה 2 של מפות Google מ-GitHub.

הגדרת פרויקט פיתוח

פועלים לפי השלבים הבאים כדי ליצור את פרויקט המדריך ב-Android Studio.

1. מורידים ומתקינים את Android Studio.
2. מוסיפים את חבילת Google Play Services ל-Android אולפן.
3. שכפול או הורדה של מאגר הדוגמאות ל-Android API גרסה 2 של מפות Google אם לא עשיתם זאת כשהתחלתם לקרוא את המדריך הזה.

4. מייבאים את פרויקט המדריך:

   • ב-Android Studio, בוחרים באפשרות File > חדש > ייבוא פרויקט.
   • מעבר למיקום שבו שמרת את הדוגמאות של גרסה 2 של ממשק ה-API של מפות Google ל-Android אחרי שמורידים אותו.
   • מוצאים את הפרויקט StyledMap במיקום הזה:
     PATH-TO-SAVED-REPO/android-samples/tutorials/StyledMap
   • בוחרים את ספריית הפרויקט ולוחצים על אישור. גרסת Android Studio כוללת עכשיו פיתוחים בפרויקט שלכם, באמצעות כלי ה-build של Gradle.

קבלת מפתח API והפעלת ממשקי ה-API הנדרשים

כדי להשלים את המדריך הזה, נדרש מפתח Google API מורשה להשתמש SDK של מפות ל-Android.

כדי לקבל מפתח ולהפעיל את ה-API, צריך ללחוץ על הלחצן שלמטה.

לקבלת מפתח

פרטים נוספים זמינים במדריך קבלת מפתח API.

הוספה של מפתח ה-API לאפליקציה

1. עורכים את קובץ gradle.properties של הפרויקט.

2. מדביקים את מפתח ה-API בערך של המאפיין GOOGLE_MAPS_API_KEY. מתי כשאתם מפתחים את האפליקציה, Gradle מעתיקה את מפתח ה-API ל-Android של האפליקציה .

   GOOGLE_MAPS_API_KEY=PASTE-YOUR-API-KEY-HERE
   

יצירה והפעלה של אפליקציה

1. מחברים מכשיר Android למחשב. פועלים לפי הוראות להפעלת אפשרויות למפתחים ב-Android את המכשיר ולהגדיר את המערכת לזהות אותו. (לחלופין, אפשר להשתמש ניהול מכשיר וירטואלי (AVD) של Android כדי להגדיר מכשיר וירטואלי במכשיר. כאשר בוחרים אמולטור, חשוב לבחור תמונה שכוללת ממשקי Google API. פרטים נוספים זמינים במאמר מדריך לתחילת העבודה).
2. ב-Android Studio, לוחצים על אפשרות התפריט הפעלה (או על סמל לחצן ההפעלה). בוחרים מכשיר בהתאם להנחיה.

Android Studio מפעיל את Gradle כדי ליצור את האפליקציה, ואז מריץ אותה במכשיר או באמולטור. אמורה להופיע מפה עם תמונה חשוכה (מצב לילה) בסגנון דומה לתמונה בדף הזה.

פתרון בעיות:

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

הסבר על הקוד

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

הוספת משאב שמכיל אובייקט בסגנון JSON

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

הערה: האפליקציה לדוגמה שהורדתם מ-GitHub משתמשת במשאב גולמי.

משאב גולמי

הגדרת משאב גולמי ב-/res/raw/style_json.json, שמכיל הצהרת הסגנון של JSON לשימוש במצב לילה:

הצגה/הסתרה של ה-JSON.

[
  {
    "featureType": "all",
    "elementType": "geometry",
    "stylers": [
      {
        "color": "#242f3e"
      }
    ]
  },
  {
    "featureType": "all",
    "elementType": "labels.text.stroke",
    "stylers": [
      {
        "lightness": -80
      }
    ]
  },
  {
    "featureType": "administrative",
    "elementType": "labels.text.fill",
    "stylers": [
      {
        "color": "#746855"
      }
    ]
  },
  {
    "featureType": "administrative.locality",
    "elementType": "labels.text.fill",
    "stylers": [
      {
        "color": "#d59563"
      }
    ]
  },
  {
    "featureType": "poi",
    "elementType": "labels.text.fill",
    "stylers": [
      {
        "color": "#d59563"
      }
    ]
  },
  {
    "featureType": "poi.park",
    "elementType": "geometry",
    "stylers": [
      {
        "color": "#263c3f"
      }
    ]
  },
  {
    "featureType": "poi.park",
    "elementType": "labels.text.fill",
    "stylers": [
      {
        "color": "#6b9a76"
      }
    ]
  },
  {
    "featureType": "road",
    "elementType": "geometry.fill",
    "stylers": [
      {
        "color": "#2b3544"
      }
    ]
  },
  {
    "featureType": "road",
    "elementType": "labels.text.fill",
    "stylers": [
      {
        "color": "#9ca5b3"
      }
    ]
  },
  {
    "featureType": "road.arterial",
    "elementType": "geometry.fill",
    "stylers": [
      {
        "color": "#38414e"
      }
    ]
  },
  {
    "featureType": "road.arterial",
    "elementType": "geometry.stroke",
    "stylers": [
      {
        "color": "#212a37"
      }
    ]
  },
  {
    "featureType": "road.highway",
    "elementType": "geometry.fill",
    "stylers": [
      {
        "color": "#746855"
      }
    ]
  },
  {
    "featureType": "road.highway",
    "elementType": "geometry.stroke",
    "stylers": [
      {
        "color": "#1f2835"
      }
    ]
  },
  {
    "featureType": "road.highway",
    "elementType": "labels.text.fill",
    "stylers": [
      {
        "color": "#f3d19c"
      }
    ]
  },
  {
    "featureType": "road.local",
    "elementType": "geometry.fill",
    "stylers": [
      {
        "color": "#38414e"
      }
    ]
  },
  {
    "featureType": "road.local",
    "elementType": "geometry.stroke",
    "stylers": [
      {
        "color": "#212a37"
      }
    ]
  },
  {
    "featureType": "transit",
    "elementType": "geometry",
    "stylers": [
      {
        "color": "#2f3948"
      }
    ]
  },
  {
    "featureType": "transit.station",
    "elementType": "labels.text.fill",
    "stylers": [
      {
        "color": "#d59563"
      }
    ]
  },
  {
    "featureType": "water",
    "elementType": "geometry",
    "stylers": [
      {
        "color": "#17263c"
      }
    ]
  },
  {
    "featureType": "water",
    "elementType": "labels.text.fill",
    "stylers": [
      {
        "color": "#515c6d"
      }
    ]
  },
  {
    "featureType": "water",
    "elementType": "labels.text.stroke",
    "stylers": [
      {
        "lightness": -20
      }
    ]
  }
]

משאב מחרוזות

מגדירים משאב מחרוזת ב-/res/values/style_strings.xml, שמכיל את ההצהרה של סגנון JSON לסגנון במצב לילה. הזה המדריך משתמש בשם המחרוזת style_json. לחשבון בקובץ הזה צריך להשתמש בקו נטוי הפוך כדי לסמן בתו בריחה (escape) את המירכאות:

הצגה/הסתרה של ה-JSON.

<resources>
  <string name="style_json">
  [
    {
      \"featureType\": \"all\",
      \"elementType\": \"geometry\",
      \"stylers\": [
        {
          \"color\": \"#242f3e\"
        }
      ]
    },
    {
      \"featureType\": \"all\",
      \"elementType\": \"labels.text.stroke\",
      \"stylers\": [
        {
          \"lightness\": -80
        }
      ]
    },
    {
      \"featureType\": \"administrative\",
      \"elementType\": \"labels.text.fill\",
      \"stylers\": [
        {
          \"color\": \"#746855\"
        }
      ]
    },
    {
      \"featureType\": \"administrative.locality\",
      \"elementType\": \"labels.text.fill\",
      \"stylers\": [
        {
          \"color\": \"#d59563\"
        }
      ]
    },
    {
      \"featureType\": \"poi\",
      \"elementType\": \"labels.text.fill\",
      \"stylers\": [
        {
          \"color\": \"#d59563\"
        }
      ]
    },
    {
      \"featureType\": \"poi.park\",
      \"elementType\": \"geometry\",
      \"stylers\": [
        {
          \"color\": \"#263c3f\"
        }
      ]
    },
    {
      \"featureType\": \"poi.park\",
      \"elementType\": \"labels.text.fill\",
      \"stylers\": [
        {
          \"color\": \"#6b9a76\"
        }
      ]
    },
    {
      \"featureType\": \"road\",
      \"elementType\": \"geometry.fill\",
      \"stylers\": [
        {
          \"color\": \"#2b3544\"
        }
      ]
    },
    {
      \"featureType\": \"road\",
      \"elementType\": \"labels.text.fill\",
      \"stylers\": [
        {
          \"color\": \"#9ca5b3\"
        }
      ]
    },
    {
      \"featureType\": \"road.arterial\",
      \"elementType\": \"geometry.fill\",
      \"stylers\": [
        {
          \"color\": \"#38414e\"
        }
      ]
    },
    {
      \"featureType\": \"road.arterial\",
      \"elementType\": \"geometry.stroke\",
      \"stylers\": [
        {
          \"color\": \"#212a37\"
        }
      ]
    },
    {
      \"featureType\": \"road.highway\",
      \"elementType\": \"geometry.fill\",
      \"stylers\": [
        {
          \"color\": \"#746855\"
        }
      ]
    },
    {
      \"featureType\": \"road.highway\",
      \"elementType\": \"geometry.stroke\",
      \"stylers\": [
        {
          \"color\": \"#1f2835\"
        }
      ]
    },
    {
      \"featureType\": \"road.highway\",
      \"elementType\": \"labels.text.fill\",
      \"stylers\": [
        {
          \"color\": \"#f3d19c\"
        }
      ]
    },
    {
      \"featureType\": \"road.local\",
      \"elementType\": \"geometry.fill\",
      \"stylers\": [
        {
          \"color\": \"#38414e\"
        }
      ]
    },
    {
      \"featureType\": \"road.local\",
      \"elementType\": \"geometry.stroke\",
      \"stylers\": [
        {
          \"color\": \"#212a37\"
        }
      ]
    },
    {
      \"featureType\": \"transit\",
      \"elementType\": \"geometry\",
      \"stylers\": [
        {
          \"color\": \"#2f3948\"
        }
      ]
    },
    {
      \"featureType\": \"transit.station\",
      \"elementType\": \"labels.text.fill\",
      \"stylers\": [
        {
          \"color\": \"#d59563\"
        }
      ]
    },
    {
      \"featureType\": \"water\",
      \"elementType\": \"geometry\",
      \"stylers\": [
        {
          \"color\": \"#17263c\"
        }
      ]
    },
    {
      \"featureType\": \"water\",
      \"elementType\": \"labels.text.fill\",
      \"stylers\": [
        {
          \"color\": \"#515c6d\"
        }
      ]
    },
    {
      \"featureType\": \"water\",
      \"elementType\": \"labels.text.stroke\",
      \"stylers\": [
        {
          \"lightness\": -20
        }
      ]
    }
  ]
  </string>
</resources>

העברת אובייקט בסגנון JSON למפה

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

משאב גולמי

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

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.example.styledmap;

import android.content.res.Resources;
import android.os.Bundle;
import android.util.Log;
import androidx.appcompat.app.AppCompatActivity;

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.MapStyleOptions;

/**
 * A styled map using JSON styles from a raw resource.
 */
public class MapsActivityRaw extends AppCompatActivity
        implements OnMapReadyCallback {

    private static final String TAG = MapsActivityRaw.class.getSimpleName();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps_raw);

        // Get the SupportMapFragment and register for the callback
        // when the map is ready for use.
        SupportMapFragment mapFragment =
                (SupportMapFragment) getSupportFragmentManager()
                        .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map when it's available.
     * The API invokes this callback when the map is ready for use.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {

        try {
            // Customise the styling of the base map using a JSON object defined
            // in a raw resource file.
            boolean success = googleMap.setMapStyle(
                    MapStyleOptions.loadRawResourceStyle(
                            this, R.raw.style_json));

            if (!success) {
                Log.e(TAG, "Style parsing failed.");
            }
        } catch (Resources.NotFoundException e) {
            Log.e(TAG, "Can't find style. Error: ", e);
        }
        // Position the map's camera near Sydney, Australia.
        googleMap.moveCamera(CameraUpdateFactory.newLatLng(new LatLng(-34, 151)));
    }
}

הפריסה (activity_maps_raw.xml) נראית כך:

הצגה/הסתרה של קובץ הפריסה.

<!--
 Copyright 2020 Google LLC

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<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:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context="com.example.styledmap.MapsActivityRaw"
    map:cameraZoom="10" />

משאב מחרוזות

דוגמת הקוד הבאה מבוססת על ההנחה שהפרויקט שלכם מכיל משאב מחרוזת בשם style_json:

package com.example.styledmap;

import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;
import android.util.Log;

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.MapStyleOptions;

/**
 * A styled map using JSON styles from a string resource.
 */
public class MapsActivityString extends AppCompatActivity
        implements OnMapReadyCallback {

    private static final String TAG = MapsActivityString.class.getSimpleName();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps_string);

        // Get the SupportMapFragment and register for the callback
        // when the map is ready for use.
        SupportMapFragment mapFragment =
                (SupportMapFragment) getSupportFragmentManager()
                        .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map when it's available.
     * The API invokes this callback when the map is ready for use.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {

        // Customise the styling of the base map using a JSON object defined
        // in a string resource file. First create a MapStyleOptions object
        // from the JSON styles string, then pass this to the setMapStyle
        // method of the GoogleMap object.
        boolean success = googleMap.setMapStyle(new MapStyleOptions(getResources()
                .getString(R.string.style_json)));

        if (!success) {
            Log.e(TAG, "Style parsing failed.");
        }
        // Position the map's camera near Sydney, Australia.
        googleMap.moveCamera(CameraUpdateFactory.newLatLng(new LatLng(-34, 151)));
    }
}

הפריסה (activity_maps_string.xml) נראית כך:

הצגה/הסתרה של קובץ הפריסה.

<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:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context="com.example.styledmap.MapsActivityString"
    map:cameraZoom="10" />

מידע נוסף על הצהרות בסגנון JSON

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

• סלקטורים מציינים את הרכיבים הגיאוגרפיים שאפשר להשתמש בהם סגנון המפה. למשל כבישים, פארקים, גופי מים נוספים, וגם את התוויות שלהן. הבוררים כוללים תכונות ורכיבים, שצוינו כ-featureType וגם elementType נכסים.
• סטיילרים הם מאפייני צבע וחשיפה שאפשר להשתמש בהם להחיל על רכיבי מפה. הם מגדירים את הצבע המוצג באמצעות שילוב של ערכי גוון, צבע ובהירות/גמא.

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

אשף העיצוב בפלטפורמה של מפות Google

יצירה סגנונות מותאמים אישית לממשקי ה-API של הפלטפורמה של מפות Google

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

השלב הבא

בקישור הבא מוסבר איך להסתיר תכונות במפה באמצעות עיצוב.