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

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

כדאי להיעזר במדריך כדי ליצור אפליקציה ל-Android בעזרת SDK של מפות ל-Android. סביבת הפיתוח המומלצת היא Android Studio.

קבל את הקוד

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

הצגת גרסת Java של הפעילות:

הצגה / הסתרה של קוד

    // 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.mapwithmarker;

import android.os.Bundle;
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.MarkerOptions;

/**
 * An activity that displays a Google map with a marker (pin) to indicate a particular location.
 */
public class MapsMarkerActivity extends AppCompatActivity
        implements OnMapReadyCallback {

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

        // Get the SupportMapFragment and request notification when the map is ready to be used.
        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 to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user receives a prompt to install
     * Play services inside the SupportMapFragment. The API invokes this method after the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        // Add a marker in Sydney, Australia,
        // and move the map's camera to the same location.
        LatLng sydney = new LatLng(-33.852, 151.211);
        googleMap.addMarker(new MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"));
        googleMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}
MapsMarkerActivity.java
    

הצגת גרסת הפעילות של Kotlin:

הצגה / הסתרה של קוד

    // 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.mapwithmarker

import android.os.Bundle
import android.widget.Toast
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.MarkerOptions

/**
 * An activity that displays a Google map with a marker (pin) to indicate a particular location.
 */
class MapsMarkerActivity : AppCompatActivity(), OnMapReadyCallback {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Retrieve the content view that renders the map.
        setContentView(R.layout.activity_maps)

        // Get the SupportMapFragment and request notification when the map is ready to be used.
        val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as? SupportMapFragment
        mapFragment?.getMapAsync(this)
    }

    override fun onMapReady(googleMap: GoogleMap) {
      val sydney = LatLng(-33.852, 151.211)
      googleMap.addMarker(
        MarkerOptions()
          .position(sydney)
          .title("Marker in Sydney")
      )
      googleMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}
MapsMarkerActivity.kt
    

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

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

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

4. ייבוא פרויקט ההדרכה:

   • ב-Android Studio, בוחרים באפשרות קובץ > חדש > ייבוא פרויקט.
   • עוברים אל המיקום שבו שמרתם את המאגר 'דוגמאות לגרסה 2 של Android Maps במפות Google' אחרי שהורדתם אותו.
   • מוצאים את הפרויקט MapsWithMarker במיקום הזה:
     PATH-TO-SAVED-REPO/android-samples/tutorials/java/MapWithMarker (Java) או
     PATH-TO-SAVED-REPO/android-samples/tutorials/kotlin/MapWithMarker (Kotlin)
   • בוחרים את ספריית הפרויקט ולוחצים על Open. מערכת Android Studio בונה עכשיו את הפרויקט באמצעות הכלי Gradle build.

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

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

• הגדרת פרויקט ב-Google Cloud
• שימוש במפתח API

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

1. פותחים את קובץ local.properties של הפרויקט.

2. מוסיפים את המחרוזת הבאה ואז מחליפים את YOUR_API_KEY בערך של מפתח ה-API:

   MAPS_API_KEY=YOUR_API_KEY
   

   כשיוצרים את האפליקציה, ה-Secret Gradle Plugin ל-Android יעתיק את מפתח ה-API ויהפוך אותו למשתנה של build במניפסט של Android, כפי שמוסבר בהמשך.

יוצרים ומפעילים את האפליקציה

כדי לבנות ולהפעיל את האפליקציה:

1. מחברים מכשיר Android למחשב. פועלים לפי ההוראות כדי להפעיל אפשרויות למפתחים במכשיר Android ולהגדיר את המערכת לזיהוי המכשיר.

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

2. ב-Android Studio, לוחצים על האפשרות 'תפריט' הפעלה (או על סמל לחצן ההפעלה). בוחרים מכשיר לפי הבקשה.

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

פתרון בעיות:

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

מבינים את הקוד

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

יש לבדוק את המניפסט של Android

יש לשים לב לרכיבים הבאים בקובץ AndroidManifest.xml של האפליקציה:

• יש להוסיף אלמנט meta-data כדי להטמיע את הגרסה של שירותי Google Play שבאמצעותה נוצרה האפליקציה.

  <meta-data
      android:name="com.google.android.gms.version"
      android:value="@integer/google_play_services_version" />
  

• מוסיפים רכיב meta-data שמציין את מפתח ה-API. במדריך המצורף מופיעה דוגמה לערך של מפתח ה-API, שממופה למשתנה של build שתואם לשם המפתח שהגדרתם קודם, MAPS_API_KEY. כשבונים את האפליקציה, ה-Secrets Gradle Plugin for Android הופך את המפתחות בקובץ local.properties לזמינים כמשתני build של מניפסט.

  <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
  

  בקובץ build.gradle, השורה הבאה מעבירה את מפתח ה-API לקובץ המניפסט של Android.

    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
  

הנה דוגמה למניפסט מלא:

<?xml version="1.0" encoding="utf-8"?>
<!--
 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.
-->

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.mapwithmarker">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />

        <!--
             The API key for Google Maps-based APIs.
        -->
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="${MAPS_API_KEY}" />

        <activity
            android:name=".MapsMarkerActivity"
            android:label="@string/title_activity_maps"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

הוספת מפה

הצגת מפה באמצעות ה-SDK של מפות Google ל-Android.

1. מוסיפים רכיב <fragment> לקובץ הפריסה של הפעילות, activity_maps.xml. הרכיב הזה מגדיר את הערך SupportMapFragment בתור קונטיינר למפה ומספק גישה לאובייקט GoogleMap. במדריך נשתמש בגרסה של מקטע המפה של תמיכת Android, כדי להבטיח תאימות לאחור לגרסאות קודמות של המסגרת של Android.

   <!--
    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: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.mapwithmarker.MapsMarkerActivity" />
   
   

2. בשיטה onCreate() של הפעילות, מגדירים את קובץ הפריסה כתצוגת התוכן. כדי לקבל כינוי למקטע המפה, צריך לבצע קריאה ל-FragmentManager.findFragmentById(). לאחר מכן, צריך להשתמש בשדה getMapAsync() כדי להירשם לשיחה החוזרת במפה:

   Java

   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       // Retrieve the content view that renders the map.
       setContentView(R.layout.activity_maps);
   
       // Get the SupportMapFragment and request notification when the map is ready to be used.
       SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
               .findFragmentById(R.id.map);
       mapFragment.getMapAsync(this);
   }
   MapsMarkerActivity.java
   

   Kotlin

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       // Retrieve the content view that renders the map.
       setContentView(R.layout.activity_maps)
   
       // Get the SupportMapFragment and request notification when the map is ready to be used.
       val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as? SupportMapFragment
       mapFragment?.getMapAsync(this)
   }
   MapsMarkerActivity.kt
   

3. מטמיעים את הממשק OnMapReadyCallback ומבטלים את השיטה onMapReady() כדי להגדיר את המפה כשהאובייקט GoogleMap זמין:

   Java

   public class MapsMarkerActivity extends AppCompatActivity
           implements OnMapReadyCallback {
   
       // ...
   
       @Override
       public void onMapReady(GoogleMap googleMap) {
           LatLng sydney = new LatLng(-33.852, 151.211);
           googleMap.addMarker(new MarkerOptions()
               .position(sydney)
               .title("Marker in Sydney"));
       }
   }
   MapsMarkerActivity.java
   

   Kotlin

   class MapsMarkerActivity : AppCompatActivity(), OnMapReadyCallback {
   
       // ...
   
       override fun onMapReady(googleMap: GoogleMap) {
         val sydney = LatLng(-33.852, 151.211)
         googleMap.addMarker(
           MarkerOptions()
             .position(sydney)
             .title("Marker in Sydney")
         )
       }
   }
   MapsMarkerActivity.kt
   

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

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

השלבים הבאים

מידע נוסף על אובייקט המפה והפעולות שניתן לבצע באמצעות סמנים