إعداد خريطة

اختيار النظام الأساسي: 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 لعرض مستوى تقدّم الرحلة وتعديله حسب الحاجة.

   ملاحظة: يمكنك الوصول إلى ConsumerController من ConsumerGoogleMap باستخدام getConsumerController().

مثال على كيفية إضافة 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()

Java

 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.

Java

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() للجزء.

Java

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، اطّلِع على الأمثلة التالية.

Java

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 لاستخدام الرسومات المتجهة في حزمة Consumer SDK.

Java

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

// ...

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

Kotlin

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

// ...

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

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

تتبُّع رحلة في Android

تحديد نمط خريطة