عرض مجموعة مركبات

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

يناقش هذا المستند الأشياء التالية التي يمكنك القيام بها عند عرض أسطول:

  1. ابدأ تتبُّع الأسطول.
  2. الاستماع إلى الأحداث ومعالجة الأخطاء
  3. إيقاف التتبّع
  4. تتبُّع مركبة واحدة أثناء عرض أسطول

ابدأ بتتبُّع الأسطول

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

إنشاء مثيل لموقع أسطول المركبات

تتضمّن مكتبة تتبُّع الأسطول في JavaScript مقدّم موقع جغرافيًا يجمع معلومات عن مركبات متعددة من Fleet Engine.

لإنشاء مثيل له، اتّبِع الخطوات التالية:

  1. استخدِم رقم تعريف مشروعك بالإضافة إلى مرجع إلى أداة جلب الرموز المميّزة.

  2. استخدام طلب بحث عن فلتر للمركبات: يتحكّم طلب البحث عن فلتر المركبات في المركبات التي تعرضها الخريطة. يتم تمرير الفلتر إلى Fleet Engine.

    • للحصول على الخدمات المتوفرة عند الطلب، يمكنك استخدام vehicleFilter ومراجعة ListVehiclesRequest.filter.
    • بالنسبة إلى المهام المُجدوَلة، استخدِم deliveryVehicleFilter، وراجِع ListDeliveryVehiclesRequest.filter
  3. ضبط الحدود لعرض المركبة استخدِم locationRestriction لتحديد المنطقة التي تظهر فيها المركبات على الخريطة. لن يكون موفّر الموقع نشطًا إلى أن يتم ضبط هذا الإعداد. يمكنك تعيين حدود الموقع إما في الدالة الإنشائية أو بعد الدالة الإنشائية.

  4. إعداد عرض الخريطة

توضح الأمثلة التالية كيفية إنشاء مثيل لمزود موقع أسطول لكل من سيناريوهات المهام عند الطلب والمجدوَلة. يوضح هذا المثال أيضًا كيفية استخدام locationRestriction في الدالة الإنشائية لجعل موفِّر الموقع الجغرافي نشطًا.

الرحلات عند الطلب

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which vehicles are retrieved.
          vehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

المهام المُجدوَلة

JavaScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately make the location provider active.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

TypeScript

locationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately make the location provider active.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

لضبط locationRestriction بعد الدالة الإنشائية، أضِف locationProvider.locationRestriction لاحقًا في الرمز الخاص بك كما هو موضّح في مثال JavaScript التالي.

   // You can choose to not set locationRestriction in the constructor.
   // In this case, the location provider *DOES NOT START* after this line, because
   // no locationRestriction is set.
   locationProvider = new google.maps.journeySharing.DeliveryFleetLocationProvider({
   ... // not setting locationRestriction here
   });

   // You can then set the locationRestriction *after* the constructor.
   // After this line, the location provider is active.
   locationProvider.locationRestriction = {
     north: 1,
     east: 2,
     south: 0,
     west: 1,
   };

ضبط القيود المتعلّقة بالموقع الجغرافي باستخدام إطار عرض الخريطة

يمكنك أيضًا ضبط حدود locationRestriction لمطابقة المنطقة المرئية حاليًا في عرض الخريطة.

رحلات عند الطلب

JavaScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

TypeScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location tracking will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

المهام المُجدوَلة

JavaScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location provider will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

TypeScript

google.maps.event.addListenerOnce(
  mapView.map, 'bounds_changed', () => {
    const bounds = mapView.map.getBounds();
    if (bounds) {
      // If you did not specify a location restriction in the
      // location provider constructor, you may do so here.
      // Location provider will start as soon as this is set.
      locationProvider.locationRestriction = bounds;
    }
  });

إعداد وضع الخريطة

بعد إنشاء مقدّم الموقع الجغرافي، يمكنك بدء عرض الخريطة بالطريقة نفسها التي تتم بها عند تتبُّع مركبة واحدة.

بعد تحميل مكتبة JavaScript لمشاركة الرحلة، يمكنك بدء استخدام عرض الخريطة وإضافته إلى صفحة HTML. يجب أن تحتوي صفحتك على عنصر <div> يحتوي على عرض الخريطة. تتم تسمية عنصر <div> بـ map_canvas في الأمثلة التالية.

رحلات عند الطلب

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
});

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.vehicleId
                        = 'your-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

TypeScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
});

// If you did not specify a vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.VehicleId
                        = 'your-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

المهام المُجدوَلة

JavaScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
});

// If you did not specify a delivery vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId
                        = 'your-delivery-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

TypeScript

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [locationProvider],
});

// If you did not specify a delivery vehicle ID in the
// location provider constructor, you may do so here.
// Location tracking will start as soon as this is set.
locationProvider.deliveryVehicleId
                        = 'your-delivery-vehicle-id';

// Give the map an initial viewport to allow it to
// initialize; otherwise the 'ready' event above may
// not fire. The user also has access to the mapView
// object to customize as they want.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);

الاستماع إلى الأحداث ومعالجة الأخطاء

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

رصد أحداث التغيير

يمكنك استرداد معلومات وصفية عن الأسطول من عنصر المركبة باستخدام موفِّر الموقع. تؤدي التغييرات التي تطرأ على المعلومات الوصفية إلى تشغيل حدث تحديث. تتضمّن المعلومات الوصفية خصائص المركبة، مثل حالة التنقّل والمسافة المتبقية والسمات المخصّصة.

لمعرفة التفاصيل، يُرجى الاطّلاع على ما يلي:

توضّح الأمثلة التالية كيفية الاستماع إلى أحداث التغيير هذه.

رحلات عند الطلب

JavaScript

locationProvider.addListener('update', e => {
  // e.vehicles contains data that may be
  // useful to the rest of the UI.
  for (vehicle of e.vehicles) {
    console.log(vehicle.navigationStatus);
  }
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineFleetLocationProviderUpdateEvent) => {
  // e.vehicles contains data that may be
  // useful to the rest of the UI.
  if (e.vehicles) {
    for (vehicle of e.vehicles) {
      console.log(vehicle.navigationStatus);
    }
  }
});

المهام المُجدوَلة

JavaScript

locationProvider.addListener('update', e => {
  // e.deliveryVehicles contains data that may be
  // useful to the rest of the UI.
  if (e.deliveryVehicles) {
    for (vehicle of e.deliveryVehicles) {
      console.log(vehicle.remainingDistanceMeters);
    }
  }
});

TypeScript

locationProvider.addListener('update',
    (e: google.maps.journeySharing.FleetEngineDeliveryFleetLocationProviderUpdateEvent) => {
  // e.deliveryVehicles contains data that may be
  // useful to the rest of the UI.
  if (e.deliveryVehicles) {
    for (vehicle of e.deliveryVehicles) {
      console.log(vehicle.remainingDistanceMeters);
    }
  }
});

الاستماع إلى الأخطاء

تريد أيضًا الاستماع إلى الأخطاء التي تحدث أثناء القيادة والتعامل معها. تؤدي الأخطاء التي تنشأ بشكل غير متزامن عن طلب معلومات المركبة إلى تشغيل أحداث الخطأ.

يوضح المثال التالي كيفية الاستماع إلى هذه الأحداث حتى تتمكن من التعامل مع الأخطاء.

JavaScript

locationProvider.addListener('error', e => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

TypeScript

locationProvider.addListener('error', (e: google.maps.ErrorEvent) => {
  // e.error is the error that triggered the event.
  console.error(e.error);
});

إيقاف تتبُّع الأسطول

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

ضبط حدود موفِّر الموقع الجغرافي على قيمة فارغة

لمنع مزود خدمة الموقع من تتبع الأسطول، يمكنك ضبط حدود موفر الموقع على قيمة خالية.

الرحلات عند الطلب

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

المهام المُجدوَلة

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

إزالة مقدّم الموقع الجغرافي من عرض الخريطة

يوضح المثال التالي كيفية إزالة مزوّد موقع جغرافي من عرض الخريطة.

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

تتبُّع مركبة تسليم أثناء عرض أسطول تسليم

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

JavaScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [
    deliveryFleetLocationProvider,
    deliveryVehicleLocationProvider,
  ],
  // Any other options
});

TypeScript

deliveryFleetLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryFleetLocationProvider({
          projectId,
          authTokenFetcher,

          // Optionally, specify location bounds to
          // limit which delivery vehicles are
          // retrieved and immediately start tracking.
          locationRestriction: {
            north: 37.3,
            east: -121.8,
            south: 37.1,
            west: -122,
          },
          // Optionally, specify a filter to limit
          // which delivery vehicles are retrieved.
          deliveryVehicleFilter:
            'attributes.foo = "bar" AND attributes.baz = "qux"',
        });

deliveryVehicleLocationProvider =
    new google.maps.journeySharing
        .FleetEngineDeliveryVehicleLocationProvider({
          projectId,
          authTokenFetcher
        });

const mapView = new
    google.maps.journeySharing.JourneySharingMapView({
  element: document.getElementById('map_canvas'),
  locationProviders: [
    deliveryFleetLocationProvider,
    deliveryVehicleLocationProvider,
  ],
  // Any other options
});

استخدام تخصيص محدّد الموقع لتتبُّع مركبة توصيل

لتمكين موفر موقع مركبة التسليم من تتبع مركبة التسليم عند النقر على علامة أسطول المركبات، اتبع الخطوات التالية:

  1. تخصيص علامة وإضافة إجراء للنقر

  2. إخفاء العلامة لمنع ظهور علامات مكرّرة

تتوفّر أمثلة على هذه الخطوات في الأقسام التالية.

تخصيص علامة وإضافة إجراء للنقر عليها

JavaScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery fleet location provider constructor.
deliveryFleetLocationProvider.deliveryVehicleMarkerCustomization =
  (params: google.maps.journeySharing.DeliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.addListener('click', () => {
        // params.vehicle.name follows the format
        // "providers/{provider}/deliveryVehicles/{vehicleId}".
        // Only the vehicleId portion is used for the delivery vehicle
        // location provider.
        deliveryVehicleLocationProvider.deliveryVehicleId =
            params.vehicle.name.split('/').pop();
      });
    }
  };

إخفاء العلامة لمنع ظهور علامات مكرّرة

يمكنك إخفاء العلامة من مقدم خدمة الموقع لمركبة التسليم لمنع عرض علامتين للمركبة نفسها:

JavaScript

// Specify the customization function either separately, or as a field in
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

TypeScript

// Specify the customization function either separately, or as a field in
// the options for the delivery vehicle location provider constructor.
deliveryVehicleLocationProvider.deliveryVehicleMarkerCustomization =
  (params: deliveryVehicleMarkerCustomizationFunctionParams) => {
    if (params.isNew) {
      params.marker.setVisible(false);
    }
  };

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