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

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

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

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

این شروع سریع بااستفاده از استودیو Android Hedgehog و افزایه Android Gradle نسخه ۸.۲ توسعه داده شده است.

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

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

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

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

روال ایجاد پروژه Google Maps در «استودیو Android» در نسخه‌های Flamingo و نسخه‌های بعدی «استودیو Android» تغییر کرده است.

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

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

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

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

   • حداقل کیت توسعه نرم‌افزار را روی نسخه کیت توسعه نرم‌افزار سازگار با دستگاه آزمایشی‌تان تنظیم کنید. باید نسخه‌ای را انتخاب کنید که از حداقل نسخه موردنیاز «کیت توسعه نرم‌افزار Maps ویژه Android نسخه ۲۰.۰.x» بالاتر باشد. حداقل نسخه موردنیاز «کیت توسعه نرم‌افزار Maps ویژه Android نسخه ۲۰.۰.x» «سطح میانای برنامه کاربردی ۲۳» ‏(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 که در فهرستگان ریشه پروژه شما قرار دارد ذخیره کنید. برای اطلاعات بیشتر درباره فایل secrets.properties، به فایل‌های دارایی Gradle مراجعه کنید.

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

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

1. در Android Studio، فایل build.gradle سطح ریشه را باز کنید و کد زیر را به عنصر dependencies در buildscript اضافه کنید.

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

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

   Groovy

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

   Kotlin

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

3. اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با Gradle همگام‌سازی کنید.
4. فایل local.properties را در فهرست سطح پروژه باز کنید، و سپس کد زیر را اضافه کنید. YOUR_API_KEY را با کلید میانای برنامه‌سازی کاربردی خود جایگزین کنید.

   MAPS_API_KEY=YOUR_API_KEY

5. در فایل 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 نام فراداده توصیه‌شده برای کلید API است. از کلیدی با این نام می‌توان برای اصالت‌سنجی در چندین میانای برنامه‌سازی کاربردی مبتنی بر Google Maps در پلاتفرم Android، ازجمله Maps SDK برای Android، استفاده کرد. برای سازگاری با نسخه قدیمی، این میانای برنامه‌سازی کاربردی از نام com.google.android.maps.v2.API_KEY نیز پشتیبانی می‌کند. این نام قدیمی فقط اصالت‌سنجی را برای Android Maps API v2 امکان‌پذیر می‌کند. برنامه می‌تواند فقط یکی از نام‌های فراداده کلید API را مشخص کند. اگر هر دو مشخص شده باشند، میانای برنامه‌سازی کاربردی استثنایی را ایجاد می‌کند.

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

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

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

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

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

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

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

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

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

فایل Gradle واحد

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

dependencies {

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

برای کسب اطلاعات بیشتر درباره مدیریت وابستگی 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: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 بهره‌مند شوید.