افزودن نقشه با نشانگر

این آموزش به شما نشان می‌دهد که چگونه یک نقشه Google را به برنامه Android خود اضافه کنید. نقشه شامل یک نشانگر، که پین نیز نامیده می‌شود، برای نشان دادن یک مکان خاص است.

برای ساختن برنامه Android بااستفاده از «کیت توسعه نرم‌افزار Maps برای Android»، آموزش گام‌به‌گام را دنبال کنید. محیط توسعه نرم‌افزار توصیه‌شده استودیو Android است.

دریافت کد

مخزن Google Maps Android API v2 Samples را از 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» را بارگیری و نصب کنید.
2. بسته خدمات Google Play را به Android Studio اضافه کنید.
3. اگر هنگام شروع خواندن این آموزش، مخزن نمونه‌های Google Maps Android API v2 را شبیه‌سازی یا بارگیری نکرده‌اید، این کار را انجام دهید.

4. پروژه را در «استودیو Android» باز کنید:

   • در «استودیو Android»، فایل > باز کردن را انتخاب کنید.
   • به مکانی که مخزن Google Maps Android API v2 Samples را پس‌از بارگیری ذخیره کرده‌اید بروید، دایرکتوری ریشه android-samples را انتخاب کنید، و روی باز کردن کلیک کنید. «استودیو Android» پروژه چندماژولی را بااستفاده از Gradle همگام‌سازی می‌کند.
   • در منو پیکربندی اجرای «استودیو Android» در نوارابزار، tutorials.java.MapWithMarker (منبع در tutorials/java/MapWithMarker) یا tutorials.kotlin.MapWithMarker (منبع در tutorials/kotlin/MapWithMarker) را انتخاب کنید.

میاناهای برنامه‌سازی کاربردی لازم را فعال کنید و کلید میانای برنامه‌سازی کاربردی دریافت کنید

برای تکمیل این آموزش، به پروژه Google Cloud با میاناهای برنامه‌سازی کاربردی لازم فعال‌شده و کلید میانای برنامه‌سازی کاربردی که برای استفاده از «کیت توسعه نرم‌افزار Maps برای Android» مجاز باشد نیاز دارید. برای جزئیات بیشتر، به اینجا مراجعه کنید:

• راه‌اندازی پروژه Google Cloud
• استفاده از کلید میانای برنامه‌سازی کاربردی

کلید میانای برنامه‌سازی کاربردی را به برنامه‌تان اضافه کنید

1. در دایرکتوری ریشه android-samples (همان پوشه local.defaults.properties)، فایل secrets.properties را باز یا ایجاد کنید. این فایل را در کنترل نسخه بررسی نکنید.

2. رشته زیر را به secrets.properties اضافه کنید و YOUR_API_KEY را با مقدار کلید میانای برنامه‌سازی کاربردی خود جایگزین کنید:

   MAPS_API_KEY=YOUR_API_KEY
   

   وقتی برنامه‌تان را می‌سازید، افزایه Secrets Gradle ویژه Android کلید API را کپی می‌کند و آن را به‌عنوان متغیر ساخت در مانیفست Android دردسترس قرار می‌دهد، همان‌طور که در بررسی مانیفست Android توضیح داده شده است.

برنامه‌تان را بسازید و اجرا کنید

برای ساختن و اجرای برنامه:

1. دستگاه Android را به رایانه وصل کنید. دستورالعمل‌ها را دنبال کنید تا گزینه‌های توسعه‌دهنده را در دستگاه Android خود فعال کنید و سیستم خود را برای شناسایی دستگاه پیکربندی کنید.

   یا می‌توانید از مدیر دستگاه در Android Studio برای پیکربندی دستگاه مجازی استفاده کنید. هنگام انتخاب شبیه‌ساز، نمایه دستگاهی را انتخاب کنید که نماد Google Play را در ستون Play داشته باشد تا تصویر سیستم شامل Google API باشد. برای جزئیات بیشتر، راه‌اندازی پروژه Android Studio را ببینید.

2. در Android Studio، مطمئن شوید که tutorials.java.MapWithMarker یا tutorials.kotlin.MapWithMarker در منو پیکربندی اجرا انتخاب شده باشد، سپس روی اجرا کلیک کنید و دستگاهی را طبق درخواست انتخاب کنید.

   همچنین می‌توانید آموزش گام‌به‌گام را از دایرکتوری ریشه android-samples در خط فرمان بسازید:

   ./gradlew :tutorials:java:MapWithMarker:assembleDebug
   ./gradlew :tutorials:kotlin:MapWithMarker:assembleDebug
   

Android Studio برای ساختن برنامه، Gradle را فراخوانی می‌کند و سپس برنامه را در دستگاه یا شبیه‌ساز اجرا می‌کند. باید نقشه‌ای با نشانگری که به سیدنی در ساحل شرقی استرالیا اشاره می‌کند ببینید، مشابه تصویر موجود در این صفحه.

عیب‌یابی:

• اگر نقشه‌ای نمی‌بینید، بررسی کنید که کلید میانای برنامه‌سازی کاربردی (API) را دریافت کرده باشید و آن را به secrets.properties اضافه کرده باشید، همان‌طور که در فعال کردن میاناهای برنامه‌سازی کاربردی (API) لازم و دریافت کلید میانای برنامه‌سازی کاربردی (API) شرح داده شده است. برای پیام‌های خطا درباره کلید میانای برنامه‌سازی کاربردی، Logcat را در Android Studio بررسی کنید.
• از ابزارهای اشکال‌زدایی «استودیو Android» برای مشاهده گزارش‌ها و اشکال‌زدایی برنامه استفاده کنید.

درک کردن کد

این بخش از آموزش مهم‌ترین بخش‌های برنامه MapWithMarker را توضیح می‌دهد تا به شما کمک کند نحوه ساختن برنامه‌ای مشابه را درک کنید.

بررسی مانیفست 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 اضافه کنید که کلید میانای برنامه‌سازی کاربردی شما را مشخص کند. نمونه همراه این آموزش مقدار کلید میانای برنامه‌سازی کاربردی را به متغیر ساخت مطابق با نام کلیدی که قبلاً تعریف کرده‌اید، MAPS_API_KEY، نگاشت می‌کند. وقتی برنامه‌تان را می‌سازید، افزایه Secrets Gradle ویژه Android کلیدهای موجود در فایل secrets.properties را به‌عنوان متغیرهای ساخت مانیفست دردسترس قرار می‌دهد.

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

  در فایل build.gradle.kts سطح ماژول، افزایه com.google.android.libraries.mapsplatform.secrets-gradle-plugin و بلوک secrets زیر افزایه Secrets Gradle را پیکربندی می‌کنند تا کلید میانای برنامه‌سازی کاربردی شما را از secrets.properties (با local.defaults.properties به‌عنوان جایگزین) بخواند و آن را به مانیفست Android شما ارسال کند:

  secrets {
      // To add your Maps API key to this project:
      // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
      // 2. Add this line, where YOUR_API_KEY is your API key:
      //        MAPS_API_KEY=YOUR_API_KEY
      propertiesFileName = "secrets.properties"
  
      // A properties file containing default secret values. This file can be
      // checked in version control.
      defaultPropertiesFileName = "local.defaults.properties"
  }
  build.gradle.kts

مثال زیر مانیفست کاملی را نشان می‌دهد:

<?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">

    <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>

افزودن نقشه

نمایش نقشه بااستفاده از کیت توسعه نرم‌افزار Google Maps برای Android.

1. عنصر <fragment> را به فایل چیدمان فعالیتتان اضافه کنید، activity_maps.xml. این عنصر SupportMapFragment را تعریف می‌کند تا به‌عنوان محفظه‌ای برای نقشه عمل کند و دسترسی به شیء GoogleMap را فراهم کند. این آموزش از نسخه AndroidX قطعه نقشه استفاده می‌کند تا سازگاری با نسخه‌های قدیمی‌تر چارچوب 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 برای ثبت‌نام در فراخوانی نقشه استفاده کنید:

   جاوا

   @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 دردسترس است، نقشه را راه‌اندازی کنید:

   جاوا

   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

به‌طور پیش‌فرض، وقتی کاربر روی نشانگر تک‌ضرب می‌زند، «کیت توسعه نرم‌افزار Google Maps برای Android» محتوای پنجره اطلاعات را نمایش می‌دهد. اگر می‌خواهید از رفتار پیش‌فرض استفاده کنید، نیازی به افزودن شنونده کلیک برای نشانگر نیست.

تبریک می‌گوییم! برنامه Android ساخته‌اید که نقشه Google را با نشانگری برای نشان دادن مکان خاصی نمایش می‌دهد. همچنین یاد گرفته‌اید که چگونه از کیت توسعه نرم‌افزار Google Maps برای Android استفاده کنید.

مراحل بعدی

درباره شیء نقشه و کارهایی که می‌توانید با نشانگرها انجام دهید بیشتر بدانید.