با استفاده از الگوی 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) که همراه اندروید استودیو ارائه می شود، یک دستگاه مجازی ایجاد کرده و شبیه ساز را نصب کنید.
یک پروژه Google Maps در Android Studio ایجاد کنید
رویه ایجاد یک پروژه Google Maps در Android Studio در Flamingo و نسخههای بعدی اندروید استودیو تغییر کرد. حتماً مراحل زیر را برای نسخه خاص Android Studio خود دنبال کنید.
Android Studio را باز کنید و روی Create New Project در پنجره Welcome to Android Studio کلیک کنید.
در پنجره پروژه جدید ، در زیر دسته تلفن و تبلت ، Empty Activity را انتخاب کنید و سپس روی Next کلیک کنید.
فرم فعالیت 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 به یادداشت های انتشار مراجعه کنید.
روی Finish کلیک کنید.
اندروید استودیو Gradle را راه اندازی کرده و پروژه را می سازد. ممکن است کمی وقت بگیرد.
پس از اتمام ساخت، Android Studio فایلهای
AndroidManifest.xml
وMapsActivity
را باز میکند. فعالیت شما ممکن است نام دیگری داشته باشد، اما نامی است که در حین راه اندازی پیکربندی کرده اید.افزودن فعالیت مشاهده نقشه های Google :
- روی بسته ای که می خواهید Google Maps Views Activity را در آن اضافه کنید کلیک راست کنید.
- New > Google > Google Maps Views Activity را انتخاب کنید.
برای اطلاعات بیشتر، به افزودن کد از یک الگو مراجعه کنید
فایل
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 و دستورات زیر بیشتر بخوانید:
گام 2
برای استفاده از پلتفرم نقشه های گوگل، باید API ها یا SDK هایی را که قصد دارید در پروژه خود استفاده کنید، فعال کنید.
کنسول
Cloud SDK
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
درباره Google Cloud SDK ، نصب Cloud SDK و دستورات زیر بیشتر بخوانید:
مرحله 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 و دستورات زیر بیشتر بخوانید:
کلید API را به برنامه خود اضافه کنید
این بخش نحوه ذخیره کلید API خود را توضیح می دهد تا بتواند به طور ایمن توسط برنامه شما ارجاع داده شود. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید، بنابراین توصیه می کنیم آن را در فایل
secrets.properties
که در فهرست اصلی پروژه شما قرار دارد، ذخیره کنید. برای اطلاعات بیشتر در مورد فایلsecrets.properties
، به فایلهای خصوصیات Gradle مراجعه کنید.برای سادهسازی این کار، توصیه میکنیم از افزونه Secrets Gradle برای اندروید استفاده کنید.
برای نصب افزونه Secrets Gradle برای اندروید در پروژه Google Maps:
- در 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") } }
- فایل
build.gradle
سطح ماژول خود را باز کنید و کد زیر را به عنصرplugins
اضافه کنید.شیار
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
کاتلین
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- فایل را ذخیره کنید و پروژه خود را با Gradle همگام کنید .
-
secrets.properties
را در دایرکتوری سطح پروژه خود باز کنید و کد زیر را اضافه کنید. کلید API خود را جایگزینYOUR_API_KEY
کنید.MAPS_API_KEY=YOUR_API_KEY
- فایل را ذخیره کنید.
- در فایل
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}" />
به صورت اختیاری، ویژگی های افزونه را ویرایش کنید تا یک فایل مخفی متفاوت یا ویژگی های دیگر را مشخص کنید. در 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، به نسخهسازی مراجعه کنید.
فایل طرح بندی 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" />
برنامه را اجرا و اجرا کنید
هنگامی که برنامه را با موفقیت اجرا می کنید، نقشه ای را نشان می دهد که در مرکز سیدنی استرالیا با یک نشانگر روی شهر است، همانطور که در تصویر زیر مشاهده می کنید.
برای استقرار و اجرای برنامه:
- در اندروید استودیو، روی گزینه منوی Run (یا نماد دکمه پخش) کلیک کنید تا برنامه خود اجرا شود.
- هنگامی که از شما خواسته می شود دستگاهی را انتخاب کنید، یکی از گزینه های زیر را انتخاب کنید:
- دستگاه Android متصل به رایانه شما را انتخاب کنید.
- همچنین، دکمه رادیویی Launch emulator را انتخاب کنید و دستگاه مجازی را که تنظیم کردهاید انتخاب کنید.
- روی OK کلیک کنید. اندروید استودیو Gradle را برای ساخت اپلیکیشن شما راه اندازی می کند و سپس نتایج را در دستگاه یا شبیه ساز شما نمایش می دهد. ممکن است چند دقیقه طول بکشد تا برنامه راه اندازی شود.
مراحل بعدی
تنظیم نقشه : این مبحث نحوه تنظیم تنظیمات اولیه و زمان اجرا را برای نقشه خود، مانند موقعیت دوربین، نوع نقشه، اجزای رابط کاربری، و ژستها شرح میدهد.
افزودن یک نقشه به برنامه اندرویدی خود (Kotlin) : این لبه کد شما را از طریق برنامه ای راهنمایی می کند که برخی از ویژگی های اضافی Maps SDK برای Android را نشان می دهد.
از کتابخانه Maps Android KTX استفاده کنید : این کتابخانه افزونه های Kotlin (KTX) به شما امکان می دهد از چندین ویژگی زبان Kotlin در حین استفاده از Maps SDK برای اندروید استفاده کنید.