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

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

يناقش هذا المستند ما يلي من الإجراءات التي يمكنك اتّخاذها عند عرض أسطول:

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

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

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

إنشاء مثيل لمزوّد موقع جغرافي للأسطول

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

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

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

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

  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);
});

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

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

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

لمنع مزوّد الموقع الجغرافي من تتبُّع الأسطول، اضبط حدود مزوّد الموقع الجغرافي على null.

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

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);
    }
  };

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