این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

Maps SDK برای Android Quick Start

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

این شروع سریع برای توسعه دهندگانی است که با توسعه پایه اندروید با جاوا یا کاتلین آشنا هستند.

محیط توسعه را تنظیم کنید

Android Studio Arctic Fox یا جدیدتر مورد نیاز است. اگر قبلا این کار را نکرده اید، آن را دانلود و نصب کنید .
مطمئن شوید که از افزونه Android Gradle نسخه 7.0 یا بالاتر در Android Studio استفاده می کنید.
یک دستگاه اندرویدی راه اندازی کنید
برای اجرای برنامه‌ای که از Maps SDK برای Android استفاده می‌کند، باید آن را در دستگاه Android یا شبیه‌ساز Android که مبتنی بر Android نسخه 4.0 یا بالاتر است و شامل APIهای Google است، مستقر کنید.
- برای استفاده از دستگاه Android، دستورالعمل‌های موجود در اجرای برنامه‌ها در دستگاه سخت‌افزاری را دنبال کنید.
- برای استفاده از شبیه ساز اندروید، می توانید با استفاده از مدیریت دستگاه مجازی اندروید (AVD) که همراه اندروید استودیو ارائه می شود، یک دستگاه مجازی ایجاد کرده و شبیه ساز را نصب کنید.
  توجه: اگر می خواهید از شبیه ساز اندروید استفاده کنید، مطمئن شوید که دستگاهی را با نماد Play انتخاب کرده اید، ، در زیر ستون Play Store نمایش داده می شود. این نماد نشان می‌دهد که این نمایه‌ها کاملاً با CTS سازگار هستند و ممکن است از تصاویر سیستمی استفاده کنند که شامل برنامه Play Store می‌شود:
یک پروژه Google Maps در Android Studio ایجاد کنید
رویه ایجاد یک پروژه Google Maps در Android Studio در Flamingo و نسخه‌های بعدی اندروید استودیو تغییر کرد. حتماً مراحل زیر را برای نسخه خاص Android Studio خود دنبال کنید.
1. Android Studio را باز کنید و روی Create New Project در پنجره Welcome to Android Studio کلیک کنید.
2. در پنجره پروژه جدید ، در زیر دسته تلفن و تبلت ، Empty Activity را انتخاب کنید و سپس روی Next کلیک کنید.
  توجه: اگر از Android Studio Electric Eel یا نسخه قبلی استفاده می کنید ، گزینه Google Maps Activity را انتخاب کنید.
3. فرم فعالیت Google Maps را تکمیل کنید:
  - Language را روی Java یا Kotlin قرار دهید. هر دو زبان به طور کامل توسط Maps SDK برای اندروید پشتیبانی می شوند. برای کسب اطلاعات بیشتر در مورد Kotlin، به توسعه برنامه‌های Android با Kotlin مراجعه کنید.
  - حداقل SDK را روی یک نسخه SDK سازگار با دستگاه آزمایشی خود تنظیم کنید. شما باید نسخه ای بزرگتر از حداقل نسخه مورد نیاز Maps SDK برای نسخه Android 18.0.x را انتخاب کنید، که Android API سطح 19 (Android 4.4، KitKat) یا بالاتر است. برای آخرین اطلاعات در مورد الزامات نسخه SDK به یادداشت های انتشار مراجعه کنید.
    توجه: اگر مطمئن نیستید که چه نسخه SDK را انتخاب کنید، پیوند کمک به من را انتخاب کنید تا اطلاعات توزیع برای کیت‌های توسعه نرم‌افزار پشتیبانی‌شده Android نمایش داده شود. به عنوان مثال، اگر API 19: Android 4.4 (KitKat) را انتخاب کنید، برنامه شما باید در بیش از 99٪ از دستگاه های Android اجرا شود.
4. روی Finish کلیک کنید.
  اندروید استودیو Gradle را راه اندازی کرده و پروژه را می سازد. ممکن است کمی وقت بگیرد.
5. پس از اتمام ساخت، Android Studio فایل‌های AndroidManifest.xml و MapsActivity را باز می‌کند. فعالیت شما ممکن است نام دیگری داشته باشد، اما نامی است که در حین راه اندازی پیکربندی کرده اید.
6. افزودن فعالیت مشاهده نقشه های Google :
  توجه: اگر از Android Studio Electric Eel یا قبل از آن استفاده می کنید، از این مرحله صرفنظر کنید زیرا در مرحله 2 فعالیت نقشه های Google را انتخاب کرده اید.
  1. روی بسته ای که می خواهید Google Maps Views Activity را در آن اضافه کنید کلیک راست کنید.
  2. New > Google > Google Maps Views Activity را انتخاب کنید.
  برای اطلاعات بیشتر، به افزودن کد از یک الگو مراجعه کنید
7. فایل AndroidManifest.xml حاوی دستورالعمل‌هایی برای دریافت کلید API Google Maps و سپس افزودن آن به فایل local.properties است. کلید API خود را به فایل AndroidManifest.xml اضافه نکنید. با انجام این کار، کلید API شما با امنیت کمتری ذخیره می شود. در عوض، دستورالعمل‌های بخش‌های بعدی را برای ایجاد یک پروژه Cloud و پیکربندی یک کلید API دنبال کنید.
پروژه Google Cloud خود را راه اندازی کنید
مراحل تنظیم Cloud Console مورد نیاز را با کلیک کردن روی برگه‌های زیر تکمیل کنید:
مرحله 1
کنسول
در Google Cloud Console، در صفحه انتخاب پروژه، روی Create Project کلیک کنید تا ایجاد یک پروژه Cloud جدید شروع شود.
به صفحه انتخاب پروژه بروید
مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. تأیید کنید که صورتحساب برای پروژه شما فعال است .
Google Cloud یک شارژ آزمایشی 0.00 دلاری ارائه می دهد. دوره آزمایشی در پایان 90 روز یا پس از جمع‌آوری هزینه‌های 300 دلاری حساب، هر کدام که زودتر اتفاق بیفتد، منقضی می‌شود. هر زمان خواستید لغو کنید. پلتفرم نقشه های گوگل دارای اعتبار ماهیانه 200 دلاری است. برای اطلاعات بیشتر، اعتبارات حساب صورت‌حساب و صورت‌حساب را ببینید.
Cloud SDK

gcloud projects create "PROJECT"
درباره Google Cloud SDK ، نصب Cloud SDK و دستورات زیر بیشتر بخوانید:
gcloud projects create
توجه : اگر قصد ندارید منابعی را که ایجاد می کنید در یک تمرین یادگیری حفظ کنید، به جای انتخاب پروژه موجود، یک پروژه ایجاد کنید. پس از اتمام تمرین، می توانید پروژه را حذف کنید و تمام منابع مرتبط با پروژه را حذف کنید.
گام 2
برای استفاده از پلتفرم نقشه های گوگل، باید API ها یا SDK هایی را که قصد دارید در پروژه خود استفاده کنید، فعال کنید.
کنسول
Maps SDK برای اندروید را فعال کنید
Cloud SDK

gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
درباره Google Cloud SDK ، نصب Cloud SDK و دستورات زیر بیشتر بخوانید:
gcloud services enable
gcloud services disable
مرحله 3
این مرحله فقط از طریق فرآیند ایجاد کلید API انجام می شود. اگر از کلید API خود در تولید استفاده می کنید، اکیداً توصیه می کنیم که کلید API خود را محدود کنید. می توانید اطلاعات بیشتر را در صفحه استفاده از کلیدهای API مخصوص محصول بیابید.
کلید API یک شناسه منحصر به فرد است که درخواست های مرتبط با پروژه شما را برای اهداف استفاده و صورتحساب احراز هویت می کند. شما باید حداقل یک کلید API مرتبط با پروژه خود داشته باشید.
برای ایجاد یک کلید API:
کنسول
به صفحه پلتفرم نقشه های گوگل > اعتبارنامه بروید.
به صفحه اعتبارنامه بروید
در صفحه اعتبارنامه‌ها ، روی ایجاد اعتبارنامه > کلید API کلیک کنید.
گفتگوی ایجاد شده کلید API کلید API تازه ایجاد شده شما را نمایش می دهد.
روی Close کلیک کنید.
کلید API جدید در صفحه Credentials در زیر کلیدهای API فهرست شده است.
(به یاد داشته باشید که کلید API را قبل از استفاده از آن در تولید محدود کنید .)
Cloud SDK

gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
درباره Google Cloud SDK ، نصب Cloud SDK و دستورات زیر بیشتر بخوانید:
gcloud alpha services api-keys create
کلید API را به برنامه خود اضافه کنید
این بخش نحوه ذخیره کلید API خود را توضیح می دهد تا بتواند به طور ایمن توسط برنامه شما ارجاع داده شود. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می کنیم آن را در فایل secrets.properties که در فهرست اصلی پروژه شما قرار دارد، ذخیره کنید. برای اطلاعات بیشتر در مورد فایل secrets.properties ، به فایل‌های خصوصیات Gradle مراجعه کنید.
برای ساده‌سازی این کار، توصیه می‌کنیم از افزونه Secrets Gradle برای اندروید استفاده کنید.
توجه: برای اطلاع از آخرین مورد نیاز سیستم و دستورالعمل‌های نصب ، به مستندات Android Secrets Gradle Plugin در GitHub مراجعه کنید.
برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps:
1. در Android Studio، فایل build.gradle در سطح پروژه خود را باز کنید و کد زیر را به عنصر dependencies در زیر buildscript اضافه کنید.
  شیار
```
buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}
```
  کاتلین
```
buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}
```
2. فایل build.gradle سطح ماژول خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.
  شیار
```
plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
```
  کاتلین
```
plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
```
3. فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
4. secrets.properties را در دایرکتوری سطح پروژه خود باز کنید و کد زیر را اضافه کنید. کلید API خود را جایگزین YOUR_API_KEY کنید.
```
MAPS_API_KEY=YOUR_API_KEY 
```
5. فایل را ذخیره کنید.
6. در فایل AndroidManifest.xml خود، به com.google.android.geo.API_KEY بروید و android:value attribute به صورت زیر به روز کنید:
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
```
7. به صورت اختیاری، ویژگی های افزونه را ویرایش کنید تا یک فایل مخفی متفاوت یا ویژگی های دیگر را مشخص کنید. در Android Studio، فایل build.gradle در سطح پروژه خود را باز کنید و ویژگی secrets را ویرایش کنید:
```
secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = 'local.defaults.properties'

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}
```
توجه: همانطور که در بالا نشان داده شده است، com.google.android.geo.API_KEY نام ابرداده توصیه شده برای کلید API است. کلیدی با این نام می‌تواند برای احراز هویت چندین API مبتنی بر نقشه‌های Google در پلتفرم Android، از جمله Maps SDK برای Android استفاده شود. برای سازگاری به عقب، API از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می کند. این نام قدیمی فقط به Android Maps API نسخه 2 امکان احراز هویت را می دهد. یک برنامه کاربردی می تواند تنها یکی از نام های ابرداده کلید API را مشخص کند. اگر هر دو مشخص شده باشند، API یک استثنا ایجاد می کند.
به کد نگاه کنید
کد ارائه شده توسط الگو را بررسی کنید. به طور خاص، به فایل های زیر در پروژه Android Studio خود نگاه کنید.
فایل فعالیت نقشه ها
فایل فعالیت نقشه ها فعالیت اصلی برنامه است و حاوی کد مدیریت و نمایش نقشه است. به‌طور پیش‌فرض، فایلی که فعالیت را تعریف می‌کند MapsActivity.java نام دارد یا اگر Kotlin را به عنوان زبان برنامه خود تنظیم کنید، MapsActivity.kt .
عناصر اصلی فعالیت نقشه ها:
- شی SupportMapFragment چرخه زندگی نقشه را مدیریت می کند و عنصر اصلی رابط کاربری برنامه است.
- شی GoogleMap دسترسی به داده ها و نمای نقشه را فراهم می کند. این کلاس اصلی Maps SDK برای اندروید است. راهنمای Map Objects اشیاء SupportMapFragment و GoogleMap را با جزئیات بیشتری شرح می دهد.
- تابع moveCamera نقشه را در مختصات LatLng برای سیدنی استرالیا متمرکز می کند. اولین تنظیماتی که هنگام افزودن نقشه باید پیکربندی شود، معمولاً مکان نقشه و تنظیمات دوربین است. مانند زاویه دید، جهت نقشه و سطح زوم. برای جزئیات به راهنمای دوربین و مشاهده مراجعه کنید.
- تابع addMarker یک نشانگر به مختصات سیدنی اضافه می کند. برای جزئیات به راهنمای نشانگرها مراجعه کنید.
فایل فعالیت نقشه ها حاوی کد زیر است:
کاتلین
```
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

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered 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 will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}

      
```
جاوا
```
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;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered 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 will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      
```
فایل Gradle ماژول
فایل Module build.gradle شامل وابستگی نقشه های زیر است که توسط Maps SDK برای Android مورد نیاز است.
```
dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}
```
توجه: نسخه دقیق می‌تواند براساس نسخه فعلی Maps SDK برای Android تغییر کند.
برای کسب اطلاعات بیشتر در مورد مدیریت وابستگی Maps، به نسخه‌سازی مراجعه کنید.
فایل طرح بندی XML
فایل activity_maps.xml فایل طرح بندی XML است که ساختار رابط کاربری برنامه را تعریف می کند. فایل در دایرکتوری res/layout قرار دارد. فایل activity_maps.xml قطعه ای را اعلام می کند که شامل عناصر زیر است:
- tools:context فعالیت پیش‌فرض قطعه را روی MapsActivity تنظیم می‌کند که در فایل فعالیت نقشه‌ها تعریف شده است.
- android:name نام کلاس قطعه را روی SupportMapFragment تنظیم می‌کند، که نوع قطعه مورد استفاده در فایل فعالیت نقشه‌ها است.
فایل طرح بندی XML حاوی کد زیر است:
```
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />
```
برنامه را اجرا و اجرا کنید
هنگامی که برنامه را با موفقیت اجرا می کنید، نقشه ای را نشان می دهد که در مرکز سیدنی استرالیا با یک نشانگر روی شهر است، همانطور که در تصویر زیر مشاهده می کنید.
برای استقرار و اجرای برنامه:
1. در اندروید استودیو، روی گزینه منوی Run (یا نماد دکمه پخش) کلیک کنید تا برنامه خود اجرا شود.
2. هنگامی که از شما خواسته می شود دستگاهی را انتخاب کنید، یکی از گزینه های زیر را انتخاب کنید:
  - دستگاه Android متصل به رایانه شما را انتخاب کنید.
  - همچنین، دکمه رادیویی Launch emulator را انتخاب کنید و دستگاه مجازی را که تنظیم کرده‌اید انتخاب کنید.
3. روی OK کلیک کنید. اندروید استودیو Gradle را برای ساخت اپلیکیشن شما راه اندازی می کند و سپس نتایج را در دستگاه یا شبیه ساز شما نمایش می دهد. ممکن است چند دقیقه طول بکشد تا برنامه راه اندازی شود.
مراحل بعدی
- تنظیم نقشه : این مبحث نحوه تنظیم تنظیمات اولیه و زمان اجرا را برای نقشه خود، مانند موقعیت دوربین، نوع نقشه، اجزای رابط کاربری، و ژست‌ها شرح می‌دهد.
- افزودن یک نقشه به برنامه اندرویدی خود (Kotlin) : این لبه کد شما را از طریق برنامه ای راهنمایی می کند که برخی از ویژگی های اضافی Maps SDK برای Android را نشان می دهد.
- از کتابخانه Maps Android KTX استفاده کنید : این کتابخانه افزونه های Kotlin (KTX) به شما امکان می دهد از چندین ویژگی زبان Kotlin در حین استفاده از Maps SDK برای اندروید استفاده کنید.

Maps SDK برای Android Quick Start

محیط توسعه را تنظیم کنید

یک دستگاه اندرویدی راه اندازی کنید

یک پروژه Google Maps در Android Studio ایجاد کنید

پروژه Google Cloud خود را راه اندازی کنید

مرحله 1

کنسول

Cloud SDK

گام 2

کنسول

Cloud SDK

مرحله 3

کنسول

Cloud SDK

کلید API را به برنامه خود اضافه کنید

شیار

کاتلین

شیار

کاتلین

به کد نگاه کنید

فایل فعالیت نقشه ها

کاتلین

جاوا

فایل Gradle ماژول

فایل طرح بندی XML

برنامه را اجرا و اجرا کنید

مراحل بعدی