يوضّح هذا القسم كيفية استخدام مكتبة تتبُّع الأسطول 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، ثم إزالة مقدّم خدمة الموقع الجغرافي من عرض الخريطة كما هو موضّح في القسم التالي.
ضبط حدود موفِّر الموقع الجغرافي على قيمة فارغة
لإيقاف موفِّر خدمة الموقع الجغرافي عن تتبُّع الأسطول، اضبط الحدود لموفِّر خدمة الموقع الجغرافي على قيمة فارغة.
الرحلات عند الطلب
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
});
استخدام تخصيص العلامة لتتبُّع مركبة توصيل
لتفعيل مزوّد بيانات الموقع الجغرافي لمركبة التسليم من أجل تتبُّع مركبة التسليم عند النقر على علامة أسطولها، اتّبِع الخطوات التالية:
تخصيص علامة وإضافة إجراء للنقر
إخفاء العلامة لمنع ظهور علامات مكرّرة
يمكنك الاطّلاع على أمثلة لهذه الخطوات في الأقسام التالية.
تخصيص علامة وإضافة إجراء للنقر عليها
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);
}
};