Mapbox GL Android

نسخه جاری v9.5.0

Mapbox GL Android SDK مبتنی بر پلت‌فرم اندروید متشکل از مجموعه ابزاری است که برای نمایش نقشه درون پروژه‌های توسعه یافته در محیط اندروید، کاربرد دارد.

شروع سریع

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

افزودن وابستگی

Mapbox قادر است SDK نقشه را از طریق Maven ارائه دهد.

جهت افزودن SDK نقشه براساس یک وابستگی، باید SDK مستقیماً از Mapbox به روش زیر دریافت و در پروژه توسط پیکربندی زیر، اضافه شود.

1. پروژه را در Android Studio باز کنید.

2. فایل build.gradle که در سطح ماژول پروژه (دایرکتوری app) قرار دارد را باز کنید.

3. اطمینان حاصل کنید که حداقل نسخه SDK برابر 14 یا بالاتر از این مقدار باشد.

android {
  ...
  defaultConfig {
      minSdkVersion 14
  }
}

4. زیرِ بخش dependencies فایل باز شده، یک rule جدید جهت دریافت آخرین نسخه mapbox-android-sdk اضافه کنید.

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-sdk:9.5.0'
}

5. فایل build.gradle که در سطح ریشه پروژه قرار دارد را باز کنید. در بخش repositories موارد مربوط به maven را تعریف کنید.

allprojects {
  repositories {
    maven {
      url 'https://api.mapbox.com/downloads/v2/releases/maven'
      authentication {
          basic(BasicAuthentication)
      }
      credentials {
        // Do not change the username below.
        // This should always be `mapbox` (not your username).
          username = 'mapbox'
          // Use the secret token you stored in gradle.properties as the password
          password = project.properties['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
      }
    }
  }
}

6. پس از انجام مراحل فوق، با توجه به اینکه محتوای فایل‌های Gradle پروژه تغییر یافت، نیاز است که جهت اعمال تغییرات، گزینه sync کلیک شود.

پس از اضافه شدن SDK نقشه به پروژه ممکن است با مشکل عدم سازگاری SDK با دیگر وابستگی‌های موجود مواجهه شوید، در صورت نیاز لازم است که ماژول مربوطه را از داخل SDK خارج نمود که این کار توسط exclude group امکان‌پذیر است.

implementation ('com.mapbox.mapboxsdk:mapbox-android-sdk:9.5.0'){
    exclude group: 'group_name', module: 'module_name'
}

افزودن نقشه

activity مربوطه جهت اضافه کردن نقشه را باز کرده و از کد زیر استفاده کنید.

    private MapView mapView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Mapbox.getInstance(this, "");

        setContentView(R.layout.activity_main);

        mapView = (MapView) findViewById(R.id.mapView);
        mapView.onCreate(savedInstanceState);
        mapView.getMapAsync(new OnMapReadyCallback() {
            @Override
            public void onMapReady(@NonNull MapboxMap mapboxMap) {
                mapboxMap.setStyle("https://api.parsimap.ir/styles/parsimap-streets-v11?key=PMI_MAP_TOKEN");
            }
        });
    }

برای استفاده از استایل‌های پارسی‌مپ لازم است بجای عبارت PMI_MAP_TOKEN توکن معتبری قرار یابد.

فایل XML مربوط به layout که می‌خواهید نقشه در آن نمایش یابد را باز کرده و کدهای زیر را در آن اضافه کنید.

<com.mapbox.mapboxsdk.maps.MapView
  android:id="@+id/mapView"
  android:layout_width="match_parent"
  android:layout_height="match_parent" />

خصوصیات MapView

خصوصیات XML مربوطه به MapView می‌تواند رفتار نقشه را سفارشی کند، از قبیل تنظیمات اولیه برای تعیین مختصات مرکز نقشه، سطح بزرگ‌نمایی و سایر گزینه‌ها است. تمامی خصوصیات نقشه با پیشوند mapbox_ جهت عدم تداخل با کتابخانه‌های دیگر تعیین و شناسایی می شوند.

برخی از خصوصیات مربوط به MapView در مثال ارائه شده، بکارگرفته شده است.

<com.mapbox.mapboxsdk.maps.MapView
  mapbox:mapbox_cameraTargetLat="35.7575"
  mapbox:mapbox_cameraTargetLng="51.41"
  mapbox:mapbox_cameraZoom="12"
  mapbox:mapbox_cameraBearing="34.33"
  mapbox:mapbox_cameraTilt="50.25"
  mapbox:mapbox_cameraZoomMax="12.41"
  mapbox:mapbox_cameraZoomMin="6"
  mapbox:mapbox_uiRotateGestures="false" />

MapView شامل متدهای lifecycle مربوط به خودش است که برای مدیریت کردن متدهای مربوط به OpenGL لازم است که درون Activity فراخوانی شوند. این متدها در حالیکه عملکردهای مرتبط را توسط mapView فراخوانی می‌کنند باید به صورت کامل override شوند. اگر شما از fragment استفاده می‌کنید لازم است که متد mapview.onDestroy() را داخل متدد onDestroyView() بجای متد onDestroy() فراخوانی کنید. در زیر تمامی متدهای lifecycle که باید override شوند قرار یافته است.

@Override
protected void onStart() {
  super.onStart();
  mapView.onStart();
}

@Override
protected void onResume() {
  super.onResume();
  mapView.onResume();
}

@Override
protected void onPause() {
  super.onPause();
  mapView.onPause();
}

@Override
protected void onStop() {
  super.onStop();
  mapView.onStop();
}

@Override
protected void onSaveInstanceState(Bundle outState) {
  super.onSaveInstanceState(outState);
  mapView.onSaveInstanceState(outState);
}

@Override
public void onLowMemory() {
  super.onLowMemory();
  mapView.onLowMemory();
}

@Override
protected void onDestroy() {
  super.onDestroy();
  mapView.onDestroy();
}

برای override کردن متدها در fragment باید به شکل زیر عمل کرد.

override fun onDestroyView() {
  super.onDestroyView()
  mapView?.onDestroy()
}