برنامه 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» خوش آمدید، روی پروژه جدید کلیک کنید.
در پنجره پروژه جدید، در دسته تلفن و رایانه لوحی، No Activity (بدون فعالیت) را انتخاب کنید و سپس روی Next (بعدی) کلیک کنید.
فرم پروژه جدید را تکمیل کنید:
زبان را روی 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 مختص محصول پیدا کنید.
کلید میانای برنامه‌سازی کاربردی شناسه یکتایی است که درخواست‌های مرتبط با پروژه شما را برای اهداف استفاده و صدور صورت‌حساب اصالت‌سنجی می‌کند. باید حداقل یک کلید میانای برنامه‌سازی کاربردی مرتبط با پروژه‌تان داشته باشید.
برای ایجاد کلید میانای API:
کنسول
-
به صفحه پلاتفرم Google Maps > اطلاعات کاربری بروید.
-
در صفحه اطلاعات کاربری، روی ایجاد اطلاعات کاربری > کلید میانای برنامه‌سازی کاربردی کلیک کنید.
کادر گفتگوی کلید میانای API ایجاد شد کلید میانای API جدیداً ایجادشده را نمایش می‌دهد. -
روی بستن کلیک کنید.
کلید میانای API جدید در صفحه اطلاعات کاربری در بخش کلیدهای میانای API فهرست شده است.
(به‌خاطر داشته باشید که قبل‌از استفاده از کلید میانای API در تولید، آن را محدود کنید.)
کیت توسعه نرم‌افزار Cloud
gcloud services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
درباره کیت توسعه نرم‌افزار Google Cloud ، نصب کیت توسعه نرم‌افزار Cloud ، و فرمان‌های زیر بیشتر بخوانید:
کلید میانای برنامه‌سازی کاربردی را به برنامه‌تان اضافه کنید
این بخش نحوه ذخیره کردن کلید میانای برنامه‌سازی کاربردی را شرح می‌دهد تا برنامه‌تان بتواند به‌طور ایمن به آن ارجاع دهد. نباید کلید میانای برنامه‌سازی کاربردی را در سیستم کنترل نسخه بررسی کنید، بنابراین توصیه می‌کنیم آن را در فایل 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نام فراداده توصیه‌شده برای کلید میانای برنامه‌سازی کاربردی است. از کلیدی با این نام می‌توان برای اصالت‌سنجی در چندین میانای برنامه‌سازی کاربردی مبتنی بر Google Maps در پلاتفرم Android، ازجمله کیت توسعه نرم‌افزار Maps برای Android، استفاده کرد. برای سازگاری با نسخه قدیمی، این میانای برنامه‌سازی کاربردی از نامcom.google.android.maps.v2.API_KEYنیز پشتیبانی می‌کند. این نام قدیمی فقط امکان اصالت‌سنجی در Android Maps API v2 را فراهم می‌کند. برنامه فقط می‌تواند یکی از نام‌های فراداده کلید میانای برنامه‌سازی کاربردی را مشخص کند. اگر هر دو مشخص شده باشند، میانای برنامه‌سازی کاربردی استثنایی را ایجاد می‌کند. -
در 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تنظیم می‌کند که نوع قطعه استفاده‌شده در فایل فعالیت 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" />
برنامه را مستقر و اجرا کنید
وقتی برنامه را با موفقیت اجرا می‌کنید، نقشه‌ای را نشان می‌دهد که مرکز آن سیدنی، استرالیا است و نشانگری روی شهر قرار دارد، همان‌طور که در نماگرفت نشان داده شده است.
برای استقرار و اجرای برنامه:
- در Android Studio، روی گزینه منو اجرا (یا نماد دکمه پخش) کلیک کنید تا برنامه‌تان اجرا شود.
- وقتی از شما خواسته شد دستگاهی را انتخاب کنید، یکی از گزینه‌های زیر را انتخاب کنید:
- دستگاه Android متصل به رایانه‌تان را انتخاب کنید.
- یا دکمه رادیویی راه‌اندازی شبیه‌ساز را انتخاب کنید و دستگاه مجازی‌ای را که راه‌اندازی کرده‌اید انتخاب کنید.
- روی تأیید کلیک کنید. Android Studio برای ساختن برنامه‌تان Gradle را راه‌اندازی می‌کند و سپس نتایج را در دستگاه یا شبیه‌سازتان نمایش می‌دهد. ممکن است چند دقیقه طول بکشد تا برنامه راه‌اندازی شود.
مراحل بعدی
راه‌اندازی نقشه: این سند نحوه راه‌اندازی تنظیمات اولیه و زمان اجرای نقشه را شرح می‌دهد، مانند موقعیت دوربین، نوع نقشه، مؤلفه‌های میانای کاربری، و اشاره‌ها.
افزودن نقشه به برنامه Android (Kotlin): این codelab شما را با برنامه‌ای آشنا می‌کند که برخی‌از ویژگی‌های اضافی کیت توسعه نرم‌افزار Google Maps برای Android را نشان می‌دهد.
از کتابخانه Maps Android KTX استفاده کنید: این کتابخانه افزونه‌های Kotlin (KTX) به شما امکان می‌دهد هنگام استفاده از «کیت توسعه نرم‌افزار Maps ویژه Android» از چندین ویژگی زبان Kotlin بهره ببرید.