شروع سریع کیت توسعه نرم‌افزار Maps ویژه Android

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

این شروع سریع برای توسعه‌دهندگانی درنظر گرفته شده است که با اصول اولیه توسعه Android با Kotlin یا Java آشنا هستند.

درباره محیط توسعه نرم‌افزار

توصیه می‌کنیم از جدیدترین نسخه پایدار Android Studio و افزایه Android Gradle استفاده کنید.

راه‌اندازی دستگاه Android

برای اجرای برنامه‌ای که از «کیت توسعه نرم‌افزار Maps برای Android» استفاده می‌کند، باید آن را در دستگاه Android یا شبیه‌ساز Android که مبتنی بر Android نسخه ۶.۰ یا بالاتر است و Google APIs را دربرمی‌گیرد مستقر کنید.

• برای استفاده از دستگاه Android، دستورالعمل‌های اجرای برنامه‌ها در دستگاه سخت‌افزاری را دنبال کنید.
• برای استفاده از شبیه‌ساز Android، می‌توانید دستگاهی مجازی ایجاد کنید و شبیه‌ساز را بااستفاده از مدیر دستگاه که همراه با Android Studio ارائه می‌شود نصب کنید.

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

1. «استودیو Android» را باز کنید و در پنجره به «استودیو Android» خوش آمدید، روی پروژه جدید کلیک کنید.

2. در پنجره پروژه جدید، در دسته تلفن و رایانه لوحی، No Activity (بدون فعالیت) را انتخاب کنید و سپس روی Next (بعدی) کلیک کنید.

3. فرم پروژه جدید را تکمیل کنید:

   • زبان را روی Java یا Kotlin تنظیم کنید. هر دو زبان به‌طور کامل توسط کیت توسعه نرم‌افزار Google Maps برای Android پشتیبانی می‌شوند. برای کسب اطلاعات بیشتر درباره Kotlin، به توسعه برنامه‌های Android با Kotlin مراجعه کنید.

   • حداقل کیت توسعه نرم‌افزار را روی نسخه کیت توسعه نرم‌افزاری تنظیم کنید که با دستگاه آزمایشی شما سازگار باشد. باید نسخه‌ای را انتخاب کنید که از حداقل نسخه موردنیاز «کیت توسعه نرم‌افزار Maps برای Android» نسخه 20.0.x، یعنی سطح میانای برنامه‌سازی کاربردی Android نسخه ۲۳ («Marshmallow»؛ Android 6.0) یا بالاتر، جدیدتر باشد. برای دریافت جدیدترین اطلاعات درباره الزامات نسخه کیت توسعه نرم‌افزار، یادداشت‌های انتشار را ببینید.

   • زبان پیکربندی ساخت را روی Kotlin DSL یا Groovy DSL تنظیم کنید. تکه‌کد برای هر دو زبان پیکربندی ساخت در رویه‌های زیر نشان داده شده است.

4. روی تمام کلیک کنید؛

   ‫Android Studio شروع به کار با Gradle می‌کند و پروژه را می‌سازد. ممکن است این کار مدتی طول بکشد.

5. فعالیت بازدیدهای Google Maps را اضافه کنید:

   1. روی پوشه app در پروژه‌تان کلیک راست کنید.

   2. جدید > Google > فعالیت بازدیدهای Google Maps را انتخاب کنید.

      

   3. در چارگوش گفتگوی فعالیت جدید Android، چارگوش انتخاب فعالیت راه‌انداز را انتخاب کنید.

   4. پایان را انتخاب کنید.

      برای اطلاعات بیشتر، به افزودن کد از الگو مراجعه کنید

6. وقتی ساخت تمام شد، Android Studio فایل‌های AndroidManifest.xml و MapsActivity را باز می‌کند. فعالیتتان ممکن است نام دیگری داشته باشد، اما همان فعالیتی است که درطول راه‌اندازی پیکربندی کردید.

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

با کلیک کردن روی برگه‌های زیر، مراحل راه‌اندازی الزامی «کنسول ابری» را تکمیل کنید:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

این بخش نحوه ذخیره کردن کلید API را به‌گونه‌ای که بتواند به‌طور ایمن توسط برنامه شما ارجاع داده شود توضیح می‌دهد. نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می‌کنیم آن را در فایل secrets.properties در فهرست اصلی پروژه خود ذخیره کنید و آن فایل را از کنترل نسخه حذف کنید. برای اطلاعات بیشتر درباره فایل‌های ویژگی Gradle، به فایل‌های ویژگی Gradle مراجعه کنید.

برای ساده کردن این کار، توصیه می‌کنیم از افزایه Secrets Gradle ویژه Android استفاده کنید.

برای نصب افزایه Secrets Gradle ویژه Android و ذخیره کلید میانای برنامه‌سازی کاربردی:

1. در Android Studio، فایل سطح بالای build.gradle.kts یا build.gradle را باز کنید و کد زیر را به بلوک plugins اضافه کنید.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. فایل build.gradle.kts یا build.gradle در سطح ماژول را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با Gradle همگام‌سازی کنید.
4. فایل secrets.properties را در دایرکتوری سطح بالا باز کنید، سپس کد زیر را اضافه کنید. YOUR_API_KEY را با کلید میانای API خودتان جایگزین کنید. حتماً secrets.properties را به فایل .gitignore خود اضافه کنید (یا به‌نحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامه‌سازی کاربردی خود را در کنترل نسخه بررسی نکنید.

   MAPS_API_KEY=YOUR_API_KEY

5. فایل local.defaults.properties را در دایرکتوری سطح بالا، همان پوشه فایل secrets.properties، ایجاد کنید و سپس کد زیر را اضافه کنید.

   MAPS_API_KEY=DEFAULT_API_KEY

   هدف این فایل ارائه مکان پشتیبان‌گیری برای کلید میانای برنامه‌سازی کاربردی است تا اگر فایل secrets.properties پیدا نشد، ساخت‌ها ناموفق نباشند. این مشکل زمانی رخ می‌دهد که برنامه را از سیستم کنترل نسخه‌ای شبیه‌سازی کنید که secrets.properties را حذف می‌کند و هنوز فایل secrets.properties را به‌صورت محلی برای ارائه کلید میانای برنامه‌سازی کاربردی خود ایجاد نکرده‌اید.

6. در فایل AndroidManifest.xml، به com.google.android.geo.API_KEY بروید و مشخصه android:value را به‌صورت زیر به‌روز کنید:

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

   توجه: com.google.android.geo.API_KEY نام فراداده توصیه‌شده برای کلید میانای برنامه‌سازی کاربردی است. از کلیدی با این نام می‌توان برای اصالت‌سنجی در چندین میانای برنامه‌سازی کاربردی مبتنی بر Google Maps در پلاتفرم Android، ازجمله Maps SDK برای Android، استفاده کرد. برای سازگاری با نسخه قدیمی، این میانای برنامه‌سازی کاربردی از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی فقط امکان اصالت‌سنجی در Android Maps API v2 را فراهم می‌کند. برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شده باشند، میانای برنامه‌سازی کاربردی استثنایی را ایجاد می‌کند.

7. در Android Studio، فایل build.gradle.kts یا build.gradle سطح ماژول را باز کنید و ویژگی secrets را ویرایش کنید. اگر دارایی secrets وجود ندارد، آن را اضافه کنید.

   خصوصیات افزایه را ویرایش کنید تا propertiesFileName را روی "secrets.properties" تنظیم کنید، defaultPropertiesFileName را روی "local.defaults.properties" تنظیم کنید، و هر خصوصیت دیگری را تنظیم کنید.

   Kotlin

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

   Groovy

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

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

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

فایل فعالیت‌های Maps

فایل فعالیت نقشه‌ها فعالیت اصلی برنامه است و حاوی کد مدیریت و نمایش نقشه است. به‌طور پیش‌فرض، فایلی که فعالیت را تعریف می‌کند MapsActivity.java نامیده می‌شود یا اگر Kotlin را به‌عنوان زبان برنامه‌تان تنظیم کنید، MapsActivity.kt نامیده می‌شود.

عناصر اصلی فعالیت‌های Maps:

• شیء SupportMapFragment چرخه حیات نقشه را مدیریت می‌کند و عنصر والد رابط کاربری برنامه است.

• شیء GoogleMap دسترسی به داده‌های نقشه و نمای آن را فراهم می‌کند. این کلاس اصلی «کیت توسعه نرم‌افزار Google Maps برای Android» است. راهنمای اشیاء نقشه اشیاء SupportMapFragment و GoogleMap را با جزئیات بیشتر شرح می‌دهد.

• تابع moveCamera نقشه را در مختصات LatLng برای سیدنی، استرالیا، در مرکز قرار می‌دهد. اولین تنظیماتی که هنگام افزودن نقشه باید پیکربندی کنید معمولاً مکان نقشه و تنظیمات دوربین، مانند زاویه دید، جهت نقشه، و سطح بزرگ‌نمایی است. برای جزئیات، راهنمای دوربین و نما را ببینید.

• تابع addMarker نشانگری را به مختصات سیدنی اضافه می‌کند. برای جزئیات، راهنمای نشانگرها را ببینید.

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

      

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

      

فایل Gradle واحد

فایل build.gradle.kts یا build.gradle در سطح ماژول شامل وابستگی Maps زیر است که برای «کیت توسعه نرم‌افزار Google Maps برای Android» لازم است.

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:20.0.0"
}

اگر پروژه‌تان از کاتالوگ نسخه Gradle (gradle/libs.versions.toml) استفاده می‌کند، وابستگی play-services-maps را در libs.versions.toml تعریف کنید:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

برای کسب اطلاعات بیشتر درباره مدیریت وابستگی Maps، به نسخه‌بندی مراجعه کنید.

فایل چیدمان XML

فایل activity_maps.xml فایل چیدمان XML است که ساختار میانای کاربری برنامه را تعریف می‌کند. فایل در فهرست راهنمای res/layout قرار دارد. فایل activity_maps.xml قطعه‌ای را اعلام می‌کند که شامل عناصر زیر است:

• tools:context فعالیت پیش‌فرض قطعه را روی MapsActivity تنظیم می‌کند که در فایل فعالیت Maps تعریف شده است.
• android:name نام کلاس قطعه را روی SupportMapFragment تنظیم می‌کند که نوع قطعه استفاده‌شده در فایل فعالیت Maps است.

فایل طرح‌بندی 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=".MapsActivity" />

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

وقتی برنامه را با موفقیت اجرا می‌کنید، نقشه‌ای را نشان می‌دهد که مرکز آن سیدنی، استرالیا است و نشانگری روی شهر قرار دارد، همان‌طور که در نماگرفت نشان داده شده است.

برای پیاده‌سازی و اجرای برنامه:

1. در Android Studio، روی گزینه منو اجرا (یا نماد دکمه پخش) کلیک کنید تا برنامه‌تان اجرا شود.
2. وقتی از شما خواسته شد دستگاهی را انتخاب کنید، یکی از گزینه‌های زیر را انتخاب کنید:
   • دستگاه Android متصل به رایانه را انتخاب کنید.
   • یا دکمه رادیویی راه‌اندازی شبیه‌ساز را انتخاب کنید و دستگاه مجازی‌ای را که راه‌اندازی کرده‌اید انتخاب کنید.
3. روی تأیید کلیک کنید. Android Studio برای ساختن برنامه‌تان Gradle را راه‌اندازی می‌کند و سپس نتایج را در دستگاه یا شبیه‌سازتان نمایش می‌دهد. ممکن است چند دقیقه طول بکشد تا برنامه راه‌اندازی شود.

مراحل بعدی

• راه‌اندازی نقشه: این سند نحوه راه‌اندازی تنظیمات اولیه و زمان اجرای نقشه را شرح می‌دهد، مانند موقعیت دوربین، نوع نقشه، مؤلفه‌های میانای کاربری، و اشاره‌ها.

• افزودن نقشه به برنامه Android (‏Kotlin): این codelab شما را با برنامه‌ای که برخی‌از ویژگی‌های اضافی «کیت توسعه نرم‌افزار Google Maps برای Android» را نشان می‌دهد آشنا می‌کند.

• استفاده از کتابخانه Maps Android KTX: این کتابخانه افزونه‌های Kotlin (KTX) به شما امکان می‌دهد هنگام استفاده از «کیت توسعه نرم‌افزار Maps ویژه Android» از چندین ویژگی زبان Kotlin بهره‌مند شوید.