افزودن نقشه

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

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

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

نمای کلی

کیت توسعه نرم‌افزار Google 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

if (context is FragmentActivity) {
    val mapFragment = SupportMapFragment.newInstance()
    context.supportFragmentManager
        .beginTransaction()
        .add(com.example.snippets.common.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"));
}

      

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

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

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

---

قدم بعدی چیست

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