إعداد خريطة

اختيار النظام الأساسي: 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().

جافا

 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

تخصيص مظهر خريطة