إعداد خريطة

اختيار النظام الأساسي: Android iOS

لمتابعة رحلة في تطبيق المستهلك، عليك أولاً تحديد خريطة وإضافة إمكانية استخدام الخرائط المتّجهة، إذا لزم الأمر.

لإعداد خريطة في تطبيقك، اتّبِع الخطوات التالية:

  1. حدِّد جزء خريطة لمتابعة رحلة.
  2. أضِف إمكانية استخدام طبقة أساسية لوحدة التحكّم في عرض الخرائط.
  3. أضِف إمكانية استخدام الرسومات المتّجهة على Android لعرض الخرائط المتّجهة ، إذا لزم الأمر.

بعد تحديد خريطة، يمكنك إضافة طرق عرض إضافية وعناصر تحكّم في الكاميرا لتخصيص التجربة المرئية. لمزيد من التفاصيل، اطّلِع على مقالة تخصيص نمط الخريطة.

الخطوة 1: تحديد جزء خريطة لمتابعة رحلة

يمكنك تحديد خريطة من خلال إضافة جزء خريطة أو طريقة عرض لإنشاء الخريطة التي تشارك فيها رحلة عند الطلب في تطبيق المستهلك. لتحديد خريطتك، اتّبِع إحدى الطريقتَين التاليتَين:

  • ConsumerMapFragment: استخدِم هذا الخيار لتحديد خريطتك باستخدام Fragment.

  • ConsumerMapView: استخدِم هذا الخيار لتحديد خريطة باستخدام View.

الميزات هي نفسها في كلتا الطريقتَين، لذا اختَر الطريقة الأفضل لتطبيقك.

يتم شرح كلتا الطريقتَين بمزيد من التفصيل في القسم التالي.

إضافة جزء خريطة أو طريقة عرض

لإنشاء خريطة لعرض مدى تقدّم الرحلة باستخدام جزء Android أو طريقة عرض، اتّبِع الخطوات التالية وراجِع أمثلة الرموز البرمجية.

  1. حدِّد جزءًا أو طريقة عرض في ملف XML لتنسيق تطبيقك، والذي يقع في /res/layout. حدِّد خريطة الرحلة كجزء باستخدام ConsumerMapFragment أو كطريقة عرض باستخدام ConsumerMapView.

    يوفّر الجزء أو طريقة العرض بعد ذلك إمكانية الوصول إلى خريطة الرحلة التي يمكن لتطبيقك الوصول إليها وتعديلها. توفّر الخريطة أيضًا مقبضًا لـ ConsumerController، ما يسمح لتطبيقك بالتحكّم في تجربة المستهلك وتخصيصها.

  2. من طريقة onCreate()، استدعِ الدالة getConsumerGoogleMapAsync(callback)، التي تعرض ConsumerGoogleMap بشكل غير متزامن في معاودة الاتصال.

  3. استخدِم ConsumerGoogleMap لعرض مدى تقدّم الرحلة وعدِّله حسب الحاجة.

مثال على كيفية إضافة ConsumerMapFragment

  1. حدِّد الجزء في ملف XML لتنسيق تطبيقك، كما هو موضّح في مثال الرمز البرمجي التالي.

    <fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapFragment"
    android:id="@+id/consumer_map_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

  2. استدعِ الدالة getConsumerGoogleMapAsync() من طريقة onCreate().

جافا

 public class SampleAppActivity extends AppCompatActivity {

   @Override
   protected void onCreate(Bundle savedInstanceState) {

     // Find the ConsumerMapFragment.
     ConsumerMapFragment consumerMapFragment =
         (ConsumerMapFragment) fragmentManager.findFragmentById(R.id.consumer_map_fragment);

     // Initiate the callback that returns the map.
     if (consumerMapFragment != null) {
       consumerMapFragment.getConsumerGoogleMapAsync(
           new ConsumerMapReadyCallback() {
             // The map returned in the callback is used to access the ConsumerController.
             @Override
             public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
               ConsumerController consumerController = consumerGoogleMap.getConsumerController();
             }
           });
     }
   }

 }

Kotlin

 class SampleAppActivity : AppCompatActivity() {
   override fun onCreate(savedInstanceState: Bundle?) {
     // Find the ConsumerMapFragment.
     val consumerMapFragment =
       fragmentManager.findFragmentById(R.id.consumer_map_fragment) as ConsumerMapFragment

     consumerMapFragment.getConsumerGoogleMapAsync(
       object : ConsumerMapReadyCallback() {
         override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
           val consumerController = consumerGoogleMap.getConsumerController()!!
         }
       }
     )
   }
 }

مثال على كيفية إضافة ConsumerMapView

  1. استخدِم طريقة العرض في جزء أو في نشاط، كما هو محدّد في ملف XML.

     <com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapView
     xmlns:android="http://schemas.android.com/apk/res/android"
     android:id="@+id/consumer_map_view"
     android:layout_width="match_parent"
     android:layout_height="match_parent" />

  2. استدعِ الدالة getConsumerGoogleMapAsync() من onCreate(). بالإضافة إلى مَعلمة معاودة الاتصال، أدرِج التفاصيل التالية:

    • النشاط أو الجزء الذي يحتوي على طريقة العرض يجب أن يكون الصنف الأساسي للنشاط أو الجزء إما FragmentActivity أو Fragment (على التوالي)، لأنّهما يوفّران إمكانية الوصول إلى دورة حياته.

    • GoogleMapOptions (يمكن أن تكون قيمة فارغة)، التي تحتوي على سمات الإعداد لـ MapView.

جافا

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ConsumerMapView mapView = findViewById(R.id.consumer_map_view);

    if (mapView != null) {
      mapView.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          }, this, null);
    }
  }

}

Kotlin

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    val mapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

    mapView.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        // The map returned in the callback is used to access the ConsumerController.
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      },
      /* fragmentActivity= */ this,
      /* googleMapOptions= */ null,
    )
  }
}

إنّ MapView في جزء هي نفسها في المثال السابق لـ MapView في نشاط، باستثناء أنّ الجزء يوسّع التنسيق الذي يتضمّن MapView في طريقة onCreateView() للجزء.

جافا

public class MapViewInFragment extends Fragment {

  @Override
  public View onCreateView(
      @NonNull LayoutInflater layoutInflater,
      @Nullable ViewGroup viewGroup,
      @Nullable Bundle bundle) {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false);
  }

}

Kotlin

class MapViewInFragment : Fragment() {
  override fun onCreateView(
    layoutInflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?,
  ): View {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
  }
}

الخطوة 2: إضافة إمكانية استخدام طبقة أساسية لوحدة التحكّم في عرض الخرائط

لمشاركة مدى تقدّم الرحلة في تطبيقك، أضِف الفئتَين التاليتَين إلى تطبيقك: ConsumerGoogleMap وConsumerController.

  • يمكنك الحصول على ConsumerGoogleMap من ConsumerMapFragment أو ConsumerMapView، وكلتاهما تعرضان ConsumerGoogleMap بشكل غير متزامن في ConsumerMapReadyCallback.

    ConsumerGoogleMap هي فئة تغليف للفئة GoogleMap. تستخدِم هذه الفئة واجهة برمجة تطبيقات مكافئة لـ GoogleMap حتى يتمكّن تطبيقك من التفاعل مع الخريطة. بهذه الطريقة، يمكن لتطبيقك التفاعل بسلاسة مع خريطة Google الأساسية نفسها. على سبيل المثال، لا يسمح GoogleMap إلا بتسجيل معاودة اتصال واحدة، ولكنّ ConsumerGoogleMap يتيح تسجيل معاودتَي اتصال. تسمح معاودات الاتصال هذه لتطبيقك بتسجيل معاودات اتصال يتم استدعاؤها بالتسلسل.

  • يمكنك الحصول على ConsumerController من ConsumerGoogleMap في getConsumerController().

    توفّر ConsumerController إمكانية الوصول إلى ميزات مشاركة الرحلات، مثل مراقبة الرحلات والتحكّم في حالة الرحلة وضبط المواقع الجغرافية.

لمعرفة كيفية إضافة ConsumerGoogleMap وConsumerController إلى تطبيقك في Java وKotlin، اطّلِع على المثالَين التاليَين.

جافا

private ConsumerGoogleMap consumerGoogleMap;
private ConsumerController consumerController;
private ConsumerMapView consumerMapView;

consumerMapView.getConsumerGoogleMapAsync(
    new ConsumerMapReadyCallback() {
      @Override
      public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerMap) {
        consumerGoogleMap = consumerMap;
        consumerController = consumerMap.getConsumerController();
      }
    },
    this, null);

Kotlin

var consumerGoogleMap: ConsumerGoogleMap
var consumerController: ConsumerController
val consumerMapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

consumerMapView.getConsumerGoogleMapAsync(
  object : ConsumerMapReadyCallback() {
    override fun onConsumerMapReady(consumerMap: ConsumerGoogleMap) {
      consumerGoogleMap = consumerMap
      consumerController = consumerMap.getConsumerController()
    },
    /* fragmentActivity= */ this,
    /* googleMapOptions= */ null,
  }
)

الخطوة 3: إضافة إمكانية استخدام الرسومات المتّجهة على Android

إذا كان تصميم تطبيقك يتطلّب إمكانية استخدام الرسومات المتّجهة، أضِف إمكانية استخدام أجهزة Android والرسومات المتّجهة القابلة للرسم باتّباع الخطوات التالية:

  1. أضِف الرمز البرمجي التالي إلى نشاطك. يوسّع هذا الرمز AppCompatActivity لاستخدام الرسومات المتّجهة القابلة للرسم في حزمة تطوير البرامج (SDK) للمستهلكين.

جافا

// ...
import android.support.v7.app.AppCompatActivity;

// ...

public class ConsumerTestActivity extends AppCompatActivity {
  // ...
}

Kotlin

// ...
import android.support.v7.app.AppCompatActivity

// ...

class ConsumerTestActivity : AppCompatActivity() {
  // ...
}

الخطوة التالية

متابعة رحلة على Android

تخصيص نمط الخريطة