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

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

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

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

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

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

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

إنشاء مثيل لموفّر بيانات الموقع الجغرافي لمجموعة الأجهزة

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

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

استخدِم رقم تعريف مشروعك بالإضافة إلى مرجع إلى أداة جلب الرموز المميزة.
استخدام طلب بحث يتضمّن فلتر المركبات يتحكّم طلب البحث الذي يتضمّن فلتر المركبات في المركبات التي تعرضها الخريطة. يتم تمرير الفلتر إلى Fleet Engine.
- بالنسبة إلى الخدمات عند الطلب، استخدِم vehicleFilter وراجِع ListVehiclesRequest.filter.
- بالنسبة إلى المهام المُجدوَلة، استخدِم deliveryVehicleFilter وراجِع ListDeliveryVehiclesRequest.filter.
ضبط المساحة المحيطة لعرض المركبة استخدِم السمة locationRestriction للحدّ من المساحة التي يتم فيها عرض المركبات على الخريطة. لن يتم تفعيل مقدّم خدمة تحديد الموقع الجغرافي إلا بعد ضبط هذا الإعداد. يمكنك ضبط حدود الموقع الجغرافي إما في الدالة الإنشائية أو بعدها.
تهيئة طريقة عرض الخريطة

توضّح الأمثلة التالية كيفية إنشاء مثيل لموفّر بيانات الموقع الجغرافي للأسطول في سيناريوهات المهام عند الطلب والمهام المجدوَلة. توضّح هذه الأمثلة أيضًا كيفية استخدام 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.

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

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

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

JavaScript

locationProvider.locationRestriction = null;

TypeScript

locationProvider.locationRestriction = null;

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

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

JavaScript

mapView.removeLocationProvider(locationProvider);

TypeScript

mapView.removeLocationProvider(locationProvider);

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

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

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

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

لتفعيل خدمة تحديد الموقع الجغرافي لمركبة التسليم من أجل تتبُّع مركبة تسليم عند النقر على علامة أسطولها، اتّبِع الخطوات التالية:

تخصيص علامة وإضافة إجراء عند النقر
أخفِ العلامة لتجنُّب العلامات المكرّرة.

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

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

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

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

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

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

عرض مجموعة مركبات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

إنشاء مثيل لموفّر بيانات الموقع الجغرافي لمجموعة الأجهزة

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

JavaScript

TypeScript

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

JavaScript

TypeScript

تهيئة عرض الخريطة

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

الاستماع إلى أحداث التغيير

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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

JavaScript

TypeScript

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

JavaScript

TypeScript

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

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