برنامه 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
«استودیو Android» را باز کنید و در پنجره به «استودیو Android» خوش آمدید، روی پروژه جدید کلیک کنید.
در پنجره پروژه جدید، در دسته تلفن و رایانه لوحی، بدون فعالیت را انتخاب کنید و سپس روی بعدی کلیک کنید.
فرم پروژه جدید را تکمیل کنید:
زبان را روی Java یا Kotlin تنظیم کنید. هر دو زبان به‌طور کامل توسط کیت توسعه نرم‌افزار Google Maps برای Android پشتیبانی می‌شوند. برای کسب اطلاعات بیشتر درباره Kotlin، توسعه برنامه‌های Android با Kotlin را ببینید.
حداقل کیت توسعه نرم‌افزار را روی نسخه کیت توسعه نرم‌افزار سازگار با دستگاه آزمایشی‌تان تنظیم کنید. باید نسخه‌ای را انتخاب کنید که از حداقل نسخه موردنیاز برای کیت توسعه نرم‌افزار Maps برای Android نسخه 20.0.x، که سطح میانای برنامه‌سازی کاربردی Android نسخه ۲۳ («Marshmallow»؛ Android 6.0) یا بالاتر است، بالاتر باشد. برای دریافت جدیدترین اطلاعات درباره الزامات نسخه کیت توسعه نرم‌افزار، یادداشت‌های انتشار را ببینید.
زبان پیکربندی ساخت را روی Kotlin DSL یا Groovy DSL تنظیم کنید. قطعه‌های مربوط به هر دو زبان پیکربندی ساخت در روال‌های زیر نشان داده شده است.
روی تمام کلیک کنید؛
«استودیو Android» Gradle را راه‌اندازی می‌کند و پروژه را می‌سازد. ممکن است این کار مدتی طول بکشد.
فعالیت بازدیدهای Google Maps را اضافه کنید:
- روی پوشه
appدر پروژه‌تان کلیک راست کنید. جدید > Google > فعالیت بازدیدهای Google Maps را انتخاب کنید:
افزودن فعالیت نماهای Google Maps از منوِ زمینه‌ای appدر Android Studio.در چارگوش گفتگوی New Android Activity، چارگوش انتخاب Launcher Activity را انتخاب کنید.
پایان را انتخاب کنید.
برای اطلاعات بیشتر، به افزودن کد از الگو مراجعه کنید.
- روی پوشه
وقتی ساخت تمام شد، Android Studio فایل‌های
AndroidManifest.xmlوMapsActivityرا باز می‌کند. فعالیت شما می‌تواند نام متفاوتی داشته باشد، بسته به آنچه درطول راه‌اندازی پیکربندی کرده‌اید.
راه‌اندازی پروژه Google Cloud
مراحل راه‌اندازی الزامی زیر را در کنسول Cloud تکمیل کنید:
مرحله ۱: راه‌اندازی پروژه
کنسول
-
در کنسول Google Cloud، در صفحه انتخابگر پروژه، روی ایجاد پروژه کلیک کنید تا ایجاد پروژه Cloud جدید شروع شود.
-
مطمئن شوید که صورت‌حساب برای پروژه Cloud شما فعال است. مطمئن شوید که صورت‌حساب برای پروژه‌تان فعال است.
Google Cloud دوره آزمایشی با هزینه ۰٫۰۰ دلار ارائه می‌دهد. دوره آزمایشی در پایان ۹۰ روز یا پس‌از اینکه حساب ۳۰۰ دلار هزینه جمع کرد، هرکدام زودتر باشد، منقضی می‌شود. هرزمان خواستید لغو کنید. برای اطلاعات بیشتر، اعتبارات حساب صورت‌حساب و صورت‌حساب را ببینید.
کیت توسعه نرم‌افزار Cloud
gcloud projects create "PROJECT"
درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:
مرحله ۲: فعال کردن میاناهای برنامه‌سازی کاربردی یا کیت‌های توسعه نرم‌افزار
برای استفاده از Google Maps Platform، باید میاناهای برنامه‌سازی کاربردی یا کیت‌های توسعه نرم‌افزاری را که قصد دارید با پروژه‌تان استفاده کنید فعال کنید.
کنسول
کیت توسعه نرم‌افزار Cloud
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:
مرحله ۳: دریافت کلید میانای برنامه‌سازی کاربردی
این مرحله فقط فرایند ایجاد کلید میانای برنامه‌سازی کاربردی را طی می‌کند. اگر از کلید میانای API خود در تولید استفاده می‌کنید، اکیداً توصیه می‌کنیم کلید میانای API خود را محدود کنید. می‌توانید اطلاعات بیشتری در صفحه استفاده از کلیدهای میانای API مختص محصول پیدا کنید.
کلید میانای برنامه‌سازی کاربردی شناسه یکتایی است که درخواست‌های مرتبط با پروژه شما را برای اهداف استفاده و صدور صورت‌حساب اصالت‌سنجی می‌کند. باید حداقل یک کلید میانای API مرتبط با پروژه‌تان داشته باشید. برای ایجاد کلید جدید یا افزودن میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار به کلید موجود، این دستورالعمل‌ها را دنبال کنید.
کنسول
-
به صفحه پلاتفرم Google Maps > کلیدها و اطلاعات کاربری بروید.
- اگر درخواست شد، پروژه‌تان را انتخاب کنید.
-
یکی از موارد زیر را انجام دهید:
-
ایجاد کلید جدید:
- روی ایجاد اطلاعات کاربری > کلید میانای API کلیک کنید.
- در پانل ایجاد کلید میانای API، فهرست انتخاب محدودیت‌های میانای API را باز کنید.
- هر میانای برنامه‌سازی کاربردی را که این کلید به آن نیاز ندارد پاک کنید و مطمئن شوید کیت توسعه نرم‌افزار Google Maps برای Android همچنان انتخاب شده باشد.
- روی ایجاد کردن کلیک کنید. پانل کلید میانای برنامه‌سازی کاربردی جدیدتان را نمایش می‌دهد.
-
استفاده از کلید موجود:
- روی نام کلید کلیک کنید.
- در فهرست انتخاب محدودیت‌های API، کیت توسعه نرم‌افزار Google Maps برای Android را انتخاب کنید.
- روی ذخیره کلیک کنید.
انتخاب کردن میانای برنامه‌سازی کاربردی در اینجا آن را فعال نمی‌کند. مطمئن شوید کیت توسعه نرم‌افزار Google Maps برای Android در صفحه کتابخانه میانای برنامه‌سازی کاربردی آن فعال باشد.
-
- برای دیدن رشته کلید در آینده، به صفحه کلیدها و اطلاعات کاربری بروید و روی نمایش کلید برای کلید کلیک کنید.
اگر کنسول با این مراحل متفاوت است، ایجاد کلید میانای برنامه‌سازی کاربردی و افزودن محدودیت‌های کلید میانای برنامه‌سازی کاربردی را در اسناد Google Cloud ببینید.
کیت توسعه نرم‌افزار Cloud
در فرمان‌های زیر، PROJECT_ID را با شناسه پروژه‌تان جایگزین کنید.
-
ایجاد کلید جدید: فرمان زیر را اجرا کنید و DISPLAY_NAME را با نامی برای کلید جایگزین کنید.
gcloud services api-keys create \ --project="PROJECT_ID" \ --display-name="DISPLAY_NAME" \ --api-target=service=maps-android-backend.googleapis.com
درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:
-
استفاده از کلید موجود: فرمان زیر را اجرا کنید و KEY_ID را با شناسه کلید جایگزین کنید. پرچم
--appendمیاناهای برنامه‌سازی کاربردی را که کلید ازقبل مجاز کرده است حفظ می‌کند. بدون آن، فرمان جایگزین آن‌ها می‌شود.gcloud services api-keys update KEY_ID \ --project="PROJECT_ID" \ --append \ --api-target=service=maps-android-backend.googleapis.com
درباره کیت توسعه نرم‌افزار Google Cloud، نصب کیت توسعه نرم‌افزار Cloud، و فرمان‌های زیر بیشتر بخوانید:
شناسه کلید، رشته کلید یا نام نمایشی نیست. برای پیدا کردن آن،
gcloud services api-keys list --project="PROJECT_ID"را اجرا کنید. شناسه بخش آخر فیلدnameاست:projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
برای دیدن رشته کلید،
gcloud services api-keys get-key-string KEY_ID
--project="PROJECT_ID" را اجرا کنید.
کلید میانای برنامه‌سازی کاربردی را به برنامه‌تان اضافه کنید
این بخش نحوه ذخیره کردن کلید میانای API را شرح می‌دهد تا برنامه‌تان بتواند به‌طور ایمن به آن ارجاع دهد. نباید کلید میانای API را در سیستم کنترل نسخه بررسی کنید، بنابراین توصیه می‌کنیم آن را در فایل secrets.properties در دایرکتوری ریشه پروژه‌تان ذخیره کنید و آن فایل را از کنترل نسخه مستثنی کنید. برای اطلاعات بیشتر درباره فایل‌های ویژگی‌های Gradle، به فایل‌های ویژگی‌های Gradle مراجعه کنید.
برای ساده کردن این کار، توصیه می‌کنیم از افزایه Secrets Gradle ویژه Android استفاده کنید.
برای نصب «افزایه Secrets Gradle ویژه Android» و ذخیره کردن کلید میانای برنامه‌سازی کاربردی:
-
در 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 }
-
فایل
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' }
- اگر از «استودیو Android» استفاده می‌کنید، پروژه‌تان را با Gradle همگام‌سازی کنید.
-
فایل
secrets.propertiesرا در دایرکتوری سطح بالا باز کنید، و سپس کد زیر را اضافه کنید.YOUR_API_KEYرا با کلید میانای API خودتان جایگزین کنید. حتماًsecrets.propertiesرا به فایل.gitignoreخود اضافه کنید (یا به‌نحوی آن را از سیستم کنترل نسخه خود حذف کنید) تا کلید میانای برنامه‌سازی کاربردی خود را در کنترل نسخه بررسی نکنید.MAPS_API_KEY=YOUR_API_KEY
-
فایل
local.defaults.propertiesرا در دایرکتوری سطح بالا، همان پوشه فایلsecrets.properties، ایجاد کنید و سپس کد زیر را اضافه کنید.MAPS_API_KEY=DEFAULT_API_KEY
هدف این فایل ارائه مکان پشتیبان‌گیری برای کلید میانای برنامه‌سازی کاربردی است تا اگر فایل
secrets.propertiesپیدا نشد، ساخت‌ها ناموفق نباشند. این مشکل زمانی رخ می‌دهد که برنامه را از سیستم کنترل نسخه‌ای شبیه‌سازی کنید کهsecrets.propertiesرا حذف می‌کند و هنوز فایلsecrets.propertiesرا به‌صورت محلی برای ارائه کلید میانای برنامه‌سازی کاربردی خود ایجاد نکرده‌اید. -
در فایل
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 برای Android، استفاده کرد. برای سازگاری با نسخه قدیمی، این میانای برنامه‌سازی کاربردی از نامcom.google.android.maps.v2.API_KEYنیز پشتیبانی می‌کند. این نام قدیمی فقط امکان اصالت‌سنجی در Android Maps API v2 را فراهم می‌کند. برنامه فقط می‌تواند یکی از نام‌های فراداده کلید میانای برنامه‌سازی کاربردی را مشخص کند. اگر هر دو مشخص شده باشند، API استثنایی را ایجاد می‌کند. -
در 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» خود نگاه کنید.
فایل فعالیت‌های Maps
فایل فعالیت نقشه‌ها فعالیت اصلی برنامه است و
حاوی کد مدیریت و نمایش نقشه است. به‌طور پیش‌فرض، فایلی که
فعالیت را تعریف می‌کند MapsActivity.java نام دارد یا اگر Kotlin را به‌عنوان
زبان برنامه‌تان تنظیم کرده باشید، MapsActivity.kt نام دارد.
عناصر اصلی فعالیت‌های Maps:
شیء
SupportMapFragmentچرخه حیات نقشه را مدیریت می‌کند و عنصر ولی واسط کاربر برنامه است.شیء
GoogleMapدسترسی به داده‌ها و نمای نقشه را فراهم می‌کند. این کلاس اصلی کیت توسعه نرم‌افزار Google Maps برای Android است. راهنمای اشیاء نقشه اشیاءSupportMapFragmentوGoogleMapرا با جزئیات بیشتر شرح می‌دهد.تابع
moveCameraنقشه را در مرکز مختصاتLatLngبرای سیدنی، استرالیا قرار می‌دهد. اولین تنظیماتی که هنگام افزودن نقشه پیکربندی می‌شود معمولاً تنظیمات مکان نقشه و دوربین است، مثل زاویه دید، جهت نقشه، و سطح بزرگ‌نمایی. برای جزئیات، راهنمای دوربین و نما را ببینید.تابع
addMarkerنشانگری را به مختصات سیدنی اضافه می‌کند. برای جزئیات، راهنمای نشانگرها را ببینید.
Kotlin
// 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» لازم است.
Kotlin
dependencies { // Maps SDK for Android implementation(libs.play.services.maps) }
Groovy
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تنظیم می‌کند که نوع قطعه استفاده‌شده در فایل فعالیت نقشه‌ها است.
فایل طرح‌بندی 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" />
برنامه را مستقر و اجرا کنید
وقتی برنامه را با موفقیت اجرا می‌کنید، نقشه‌ای را نشان می‌دهد که مرکز آن سیدنی، استرالیا است و نشانگری روی شهر قرار دارد، همان‌طور که در نماگرفت نشان داده شده است.
برای استقرار و اجرای برنامه:
- در Android Studio، روی گزینه منو اجرا (یا نماد دکمه پخش) کلیک کنید تا برنامه‌تان اجرا شود.
- وقتی از شما خواسته شد دستگاهی را انتخاب کنید، یکی از گزینه‌های زیر را انتخاب کنید:
- دستگاه Android متصل به رایانه‌تان را انتخاب کنید.
- یا دکمه رادیویی راه‌اندازی شبیه‌ساز را انتخاب کنید و دستگاه مجازی‌ای را که راه‌اندازی کرده‌اید انتخاب کنید.
- روی تأیید کلیک کنید. Android Studio برای ساختن برنامه‌تان Gradle را راه‌اندازی می‌کند و سپس نتایج را در دستگاه یا شبیه‌سازتان نمایش می‌دهد. ممکن است چند دقیقه طول بکشد تا برنامه راه‌اندازی شود.
مراحل بعدی
راه‌اندازی نقشه: این سند نحوه راه‌اندازی تنظیمات اولیه و زمان اجرای نقشه را شرح می‌دهد، مانند موقعیت دوربین، نوع نقشه، مؤلفه‌های میانای کاربری، و اشاره‌ها.
افزودن نقشه به برنامه Android (Kotlin): این codelab شما را با برنامه‌ای آشنا می‌کند که برخی‌از ویژگی‌های اضافی کیت توسعه نرم‌افزار Google Maps برای Android را نشان می‌دهد.
از کتابخانه Maps Android KTX استفاده کنید: این کتابخانه افزونه‌های Kotlin (KTX) به شما امکان می‌دهد هنگام استفاده از «کیت توسعه نرم‌افزار Maps برای Android» از چندین ویژگی زبان Kotlin بهره ببرید.