本節將說明如何使用 JavaScript 車隊追蹤程式庫查看車隊。這些程序假設您已設定車隊追蹤程式庫並載入地圖。詳情請參閱「設定 JavaScript 車隊追蹤程式庫」。
本文將說明查看車隊時可執行的操作：
開始追蹤車隊
如要追蹤車隊，您需要將車隊位置供應器例項化，並為地圖檢視區設定位置限制，如以下各節所述。
例項化車隊位置提供程式
JavaScript 車隊追蹤程式庫包含位置供應器，可從車隊引擎擷取多輛車輛。
如要將其例項化，請按照下列步驟操作：
使用專案 ID，以及符記擷取器的參照。
使用車輛篩選器查詢：車輛篩選器查詢會控制地圖顯示哪些車輛。篩選器會傳遞至 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);
});
停止追蹤機群
如要停止追蹤車隊，請將位置提供者的邊界設為空值，然後按照下列各節所述，從地圖檢視畫面中移除位置提供者。
將位置資訊提供者的邊界設為空值
如要停止位置提供者追蹤車隊，請將位置提供者的邊界設為空值。
隨選行程
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);
}
};