افزودن نقشه

پلاتفرم را انتخاب کنید: Android iOS JavaScript

این موضوع نحوه افزودن نقشه پایه به برنامه Android را پس‌از پیکربندی پروژه برای استفاده از «کیت توسعه نرم‌افزار Google Maps برای Android» شرح می‌دهد. پس‌از افزودن نقشه، می‌توانید نوع نقشه و ویژگی‌ها را تغییر دهید.

توجه: برای ایجاد سریع برنامه‌ای که ازقبل حاوی نقشه پایه است، می‌توانید از الگوی Google Maps در Android Studio استفاده کنید. برای جزئیات، به شروع سریع مراجعه کنید.

نمای کلی

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

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

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

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

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

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

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

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

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

مشاهده کد

کد زیر از فعالیت کامل Java است که در این موضوع هنگام افزودن قطعه به‌صورت پایا استفاده می‌شود. پروژه Android از الگوی پروژه «خالی» ایجاد شد و سپس براساس راهنمای پیکربندی پروژه به‌روز شد. پس‌از انجام مراحل این موضوع، ممکن است کد شما براساس الگوی پروژه متفاوت باشد.

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

  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"));
      }
  }

برای افزودن نقشه

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

مراحل اولیه:

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

   1. راه‌اندازی در کنسول Google Cloud

   2. استفاده از کلید میانای برنامه‌سازی کاربردی

   3. راه‌اندازی پروژه «استودیو Android»

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

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

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

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

6. پاسخ تماس را ثبت کنید.

7. دستگیره‌ای برای شیء GoogleMap دریافت کنید.

افزودن شیء SupportMapFragment

می‌توانید شیء SupportMapFragment را به‌صورت ایستا یا پویا به برنامه‌تان اضافه کنید. ساده‌ترین راه این است که آن را به‌صورت ایستا اضافه کنید. اگر قطعه را به‌صورت پویا اضافه کنید، می‌توانید اقدامات بیشتری روی قطعه انجام دهید، مثلاً برداشتن و جایگزین کردن آن در زمان اجرا.

برای افزودن قطعه به‌صورت ایستا

در فایل چیدمان فعالیتی که نقشه را مدیریت خواهد کرد:

1. عنصر fragment اضافه کنید.
2. اعلامیه نام را اضافه کنید xmlns:map="http://schemas.android.com/apk/res-auto". این کار امکان استفاده از maps مشخصه‌های XML سفارشی را فراهم می‌کند.
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. تراکنشی را که قطعه را به فعالیت اضافه می‌کند ثبت کنید. برای اطلاعات بیشتر، تراکنش‌های Fragment را ببینید.

برای مثال:

Kotlin

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

      

جاوا

SupportMapFragment mapFragment = SupportMapFragment.newInstance();
FragmentTransaction fragmentTransaction =
        getSupportFragmentManager().beginTransaction();
fragmentTransaction.add(R.id.map_container, mapFragment);
fragmentTransaction.commit();

      

پیاده‌سازی میانای OnMapReadyCallback

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

Kotlin

class MainActivity :
    AppCompatActivity(),
    OnMapReadyCallback {

    // ...
}

      

جاوا

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

      

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

در روش onCreate فعالیتتان، روش setContentView را فراخوانی کنید و فایل چیدمان را به‌عنوان نمای محتوا تنظیم کنید.

برای مثال، اگر نام فایل چیدمان main.xml باشد:

Kotlin

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);
}


      

دریافت دستگیره برای قطعه و ثبت پاسخ تماس

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

2. برای تنظیم فراخوانی در قطعه، روش getMapAsync را فراخوانی کنید.

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

Kotlin

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 استفاده کنید. وقتی نقشه آماده دریافت ورودی کاربر باشد، فراخوانی راه‌اندازی می‌شود. این روش نمونه‌ای غیرتهی از کلاس GoogleMap ارائه می‌دهد که می‌توانید از آن برای به‌روزرسانی نقشه استفاده کنید.

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

Kotlin

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"));
}


      

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

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

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

---

قدم بعدی چیست

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