یک نقشه اضافه کنید

پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، جاوا اسکریپت

این مبحث نحوه اضافه کردن یک نقشه اولیه به یک برنامه اندروید را پس از پیکربندی پروژه برای استفاده از Maps SDK برای اندروید شرح می‌دهد. پس از افزودن نقشه، می‌توانید نوع و ویژگی‌های نقشه را تغییر دهید.

نمای کلی

کیت توسعه نرم‌افزار نقشه‌ها برای اندروید (Maps SDK) چندین کلاس ارائه می‌دهد که برنامه شما می‌تواند از آنها برای مدیریت چرخه حیات، عملکرد و داده‌های یک نقشه استفاده کند. این کلاس‌ها از تعاملات کاربر بر اساس مدل رابط کاربری اندروید، مانند تنظیم وضعیت اولیه نقشه و پاسخ به ورودی ژست از کاربر در زمان اجرا، پشتیبانی می‌کنند.

رابط اصلی و کلاس‌ها برای مدیریت نقشه‌ها:

  • GoogleMap - نقطه ورود برای مدیریت ویژگی‌ها و داده‌های زیربنایی نقشه. برنامه شما فقط می‌تواند به یک شیء GoogleMap پس از بازیابی آن از یک شیء SupportMapFragment یا MapView دسترسی داشته باشد.

  • SupportMapFragment — قطعه‌ای برای مدیریت چرخه حیات یک شیء GoogleMap .

  • MapView - نمایی برای مدیریت چرخه حیات یک شیء GoogleMap .

  • OnMapReadyCallback — یک رابط فراخوانی که رویدادها و تعامل کاربر را برای شیء GoogleMap مدیریت می‌کند.

یک شیء GoogleMap به طور خودکار این عملیات را انجام می‌دهد:

  • اتصال به سرویس نقشه گوگل
  • دانلود کاشی‌های نقشه.
  • نمایش کاشی‌ها روی صفحه دستگاه.
  • نمایش کنترل‌های مختلف مانند حرکت افقی و عمودی و بزرگنمایی.
  • با حرکت دادن نقشه و بزرگنمایی یا کوچکنمایی، به حرکات حرکت افقی و عمودی پاسخ می‌دهد.

برای استفاده از یک شیء GoogleMap در برنامه خود، باید از یک شیء SupportMapFragment یا MapView به عنوان یک شیء کانتینر برای نقشه استفاده کنید و سپس شیء GoogleMap را از کانتینر بازیابی کنید. از آنجا که کلاس‌های کانتینر از یک fragment یا view اندروید مشتق می‌شوند، مدیریت چرخه حیات و قابلیت‌های رابط کاربری کلاس‌های پایه اندروید خود را به نقشه ارائه می‌دهند. کلاس SupportMapFragment کانتینر مدرن‌تر و رایج‌تری برای یک شیء GoogleMap است.

کد را مشاهده کنید

کد زیر از اکتیویتی کامل جاوا که در این مبحث هنگام اضافه کردن یک فرگمنت به صورت استاتیک استفاده شده است، گرفته شده است. پروژه اندروید از الگوی پروژه Empty ایجاد شده و سپس بر اساس راهنمای پیکربندی پروژه به‌روزرسانی شده است. پس از انجام مراحل این مبحث، کد شما ممکن است بر اساس الگوی پروژه متفاوت باشد.

  package com.example.mapsetup;

  import androidx.appcompat.app.AppCompatActivity;

  import android.os.Bundle;

  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;

  // Implement OnMapReadyCallback.
  public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          // Set the layout file as the content view.
          setContentView(R.layout.activity_main);

          // Get a handle to the fragment and register the callback.
          SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                  .findFragmentById(R.id.map);
          mapFragment.getMapAsync(this);

      }

      // Get a handle to the GoogleMap object and display marker.
      @Override
      public void onMapReady(GoogleMap googleMap) {
          googleMap.addMarker(new MarkerOptions()
                  .position(new LatLng(0, 0))
                  .title("Marker"));
      }
  }

برای اضافه کردن نقشه

این بخش نحوه‌ی افزودن یک نقشه‌ی پایه با استفاده از یک فرگمنت به عنوان ظرف نقشه را شرح می‌دهد؛ با این حال، می‌توانید به جای آن از یک نما (view) استفاده کنید. برای مثال، به RawMapViewDemoActivity در Github مراجعه کنید.

مراحل اساسی:

  1. برای دریافت SDK، دریافت کلید API و افزودن فریم‌ورک‌های مورد نیاز، مراحل زیر را دنبال کنید:

    1. در کنسول Google Cloud تنظیم کنید

    2. استفاده از کلید API

    3. راه اندازی پروژه اندروید استودیو

  2. یک شیء SupportMapFragment به اکتیویتی که نقشه را مدیریت می‌کند اضافه کنید. می‌توانید این قطعه را به صورت ایستا یا پویا اضافه کنید.

  3. رابط OnMapReadyCallback را پیاده‌سازی کنید.

  4. فایل طرح‌بندی را به عنوان نمای محتوا تنظیم کنید.

  5. اگر قطعه را به صورت ایستا اضافه کرده‌اید، یک هندل (دسته) برای قطعه دریافت کنید.

  6. تماس برگشتی را ثبت کنید.

  7. یک هندل (دسته) برای شیء GoogleMap دریافت کنید.

یک شیء SupportMapFragment اضافه کنید

شما می‌توانید یک شیء SupportMapFragment به صورت ایستا یا پویا به برنامه خود اضافه کنید. ساده‌ترین راه، اضافه کردن آن به صورت ایستا است. اگر فرگمنت را به صورت پویا اضافه کنید، می‌توانید اقدامات اضافی روی فرگمنت انجام دهید، مانند حذف و جایگزینی آن در زمان اجرا.

برای اضافه کردن یک قطعه به صورت استاتیک

در فایل طرح‌بندیِ فعالیتی که نقشه را مدیریت خواهد کرد:

  1. یک عنصر fragment اضافه کنید.
  2. اعلان نام را با استفاده xmlns:map="http://schemas.android.com/apk/res-auto" اضافه کنید. این کار امکان استفاده از ویژگی‌های XML سفارشی maps را فراهم می‌کند.
  3. در عنصر fragment ، ویژگی android:name را روی com.google.android.gms.maps.SupportMapFragment تنظیم کنید.
  4. در عنصر fragment ، ویژگی android:id را اضافه کنید و آن را روی شناسه منبع R.id.map ( @+id/map ) تنظیم کنید.

برای مثال، در اینجا یک فایل طرح‌بندی کامل وجود دارد که شامل یک عنصر fragment است:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:id="@+id/map"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

برای اضافه کردن یک قطعه به صورت پویا

در فعالیت:

  1. یک نمونه SupportMapFragment ایجاد کنید.
  2. یک تراکنش را انجام دهید که فرگمنت را به اکتیویتی اضافه کند. برای اطلاعات بیشتر، به بخش تراکنش‌های فرگمنت مراجعه کنید.

برای مثال:

کاتلین 

val mapFragment = SupportMapFragment.newInstance()
supportFragmentManager
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit()

جاوا 

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
getSupportFragmentManager()
    .beginTransaction()
    .add(R.id.my_container, mapFragment)
    .commit();

رابط OnMapReadyCallback را پیاده‌سازی کنید

اعلان فعالیت را به صورت زیر به‌روزرسانی کنید:

کاتلین 

class MainActivity : AppCompatActivity(), OnMapReadyCallback {

    // ...
}

جاوا 

class MainActivity extends AppCompatActivity implements OnMapReadyCallback {
    // ...
}

تنظیم نمای محتوا

در متد onCreate مربوط به activity خود، متد setContentView را فراخوانی کنید و فایل layout را به عنوان content view تنظیم کنید.

برای مثال، اگر فایل طرح‌بندی main.xml نام داشته باشد:

کاتلین 

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)
}

جاوا 

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
}

یک هندل برای قطعه دریافت کنید و callback را ثبت کنید

  1. برای دریافت یک هندل به فرگمنت، متد FragmentManager.findFragmentById را فراخوانی کنید و شناسه منبع فرگمنت را در فایل layout خود به آن ارسال کنید. اگر فرگمنت را به صورت پویا اضافه کرده‌اید ، از این مرحله صرف نظر کنید زیرا قبلاً هندل را بازیابی کرده‌اید.

  2. برای تنظیم فراخوانی برگشتی روی فرگمنت، متد getMapAsync را فراخوانی کنید.

برای مثال، اگر قطعه را به صورت ایستا اضافه کرده باشید:

کاتلین 

val mapFragment = supportFragmentManager
    .findFragmentById(R.id.map) as SupportMapFragment
mapFragment.getMapAsync(this)

جاوا 

SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
    .findFragmentById(R.id.map);
mapFragment.getMapAsync(this);

دریافت یک هندل (دسته) برای شیء GoogleMap

از متد فراخوانی onMapReady برای دریافت یک هندل به شیء GoogleMap استفاده کنید. این فراخوانی زمانی فعال می‌شود که نقشه آماده دریافت ورودی کاربر باشد. این متد یک نمونه غیر تهی (non-null) از کلاس GoogleMap را فراهم می‌کند که می‌توانید از آن برای به‌روزرسانی نقشه استفاده کنید.

در این مثال، تابع فراخوانی onMapReady یک هندل به شیء GoogleMap بازیابی می‌کند و سپس یک نشانگر به نقشه اضافه می‌شود:

کاتلین 

override fun onMapReady(googleMap: GoogleMap) {
    googleMap.addMarker(
        MarkerOptions()
            .position(LatLng(0.0, 0.0))
            .title("Marker")
    )
}

جاوا 

@Override
public void onMapReady(GoogleMap googleMap) {
    googleMap.addMarker(new MarkerOptions()
        .position(new LatLng(0, 0))
        .title("Marker"));
}

تصویر صفحه با نقشه و نشانگری که مرکز آن جزیره نول است.

وقتی برنامه را با موفقیت بسازید و اجرا کنید ، نقشه‌ای با نشانگر روی جزیره پوچ (صفر درجه عرض جغرافیایی و صفر درجه طول جغرافیایی) نمایش داده می‌شود.

کد مربوط به کل فعالیت را مشاهده کنید:

مشاهده فعالیت کامل

قدم بعدی چیست؟

پس از انجام این مراحل، می‌توانید تنظیمات نقشه را پیکربندی کنید .