Thư viện theo dõi đội xe JavaScript cho phép bạn trực quan hoá vị trí của xe trong đội xe theo thời gian gần thực. Thư viện này sử dụng API Phân phối để cho phép trực quan hoá xe phân phối cũng như các tác vụ. Giống như Thư viện theo dõi việc vận chuyển JavaScript, thư viện này chứa thành phần bản đồ JavaScript dùng để thay thế cho thực thể google.maps.Map
tiêu chuẩn và các thành phần dữ liệu để kết nối với Fleet Engine.
Thành phần
Thư viện theo dõi nhóm JavaScript cung cấp các thành phần để trực quan hoá xe và điểm dừng giao hàng, cũng như nguồn cấp dữ liệu thô cho ETA hoặc quãng đường còn lại cho đến khi giao hàng.
Chế độ xem bản đồ Theo dõi đội xe
Thành phần chế độ xem bản đồ Theo dõi đội xe trực quan hoá vị trí của xe và nhiệm vụ. Nếu đã biết tuyến đường của một chiếc xe, thành phần chế độ xem bản đồ sẽ tạo ảnh động cho chiếc xe đó khi xe di chuyển dọc theo đường đi được dự đoán.
Nhà cung cấp dịch vụ vị trí
Trình cung cấp vị trí làm việc với thông tin lưu trữ trong Fleet Engine để gửi thông tin vị trí của các đối tượng được theo dõi đến bản đồ chia sẻ hành trình.
Nhà cung cấp vị trí xe giao hàng
Nhà cung cấp vị trí xe giao hàng sẽ hiển thị thông tin vị trí của một xe giao hàng. Lớp này có thông tin về vị trí của xe cũng như các công việc mà xe giao hàng đã hoàn thành.
Nhà cung cấp vị trí nhóm giao hàng
Nhà cung cấp vị trí đội xe giao hàng sẽ hiển thị thông tin vị trí của nhiều xe. Bạn có thể lọc theo các phương tiện hoặc vị trí cụ thể hoặc có thể hiển thị toàn bộ đội xe.
Kiểm soát chế độ hiển thị của vị trí được theo dõi
Phần này mô tả các quy tắc hiển thị cho các đối tượng vị trí được theo dõi trên bản đồ cho trình cung cấp vị trí đã xác định trước của Fleet Engine. Trình cung cấp vị trí tuỳ chỉnh hoặc phát sinh có thể thay đổi các quy tắc hiển thị.
Xe giao hàng
Xe giao hàng sẽ xuất hiện ngay sau khi được tạo trong Fleet Engine và xuất hiện trong suốt lộ trình bất kể nó có nhiệm vụ gì.
Điểm đánh dấu vị trí việc cần làm
Các điểm dừng xe theo kế hoạch sẽ xuất hiện trên bản đồ dưới dạng điểm đánh dấu dừng phương tiện. Điểm đánh dấu cho các nhiệm vụ đã hoàn thành sẽ xuất hiện theo một kiểu khác với điểm dừng theo kế hoạch của xe.
Vị trí của kết quả nhiệm vụ sẽ xuất hiện cùng với điểm đánh dấu kết quả của nhiệm vụ. Những tác vụ có kết quả SUCCEEDED sẽ hiển thị kèm theo điểm đánh dấu tác vụ thành công, trong khi tất cả các tác vụ khác sẽ hiển thị bằng điểm đánh dấu tác vụ không thành công.
Bắt đầu sử dụng Thư viện theo dõi nhóm JavaScript
Trước khi sử dụng Thư viện theo dõi nhóm JavaScript, hãy đảm bảo rằng bạn đã quen dùng Fleet Engine và cách nhận khoá API. Sau đó, hãy tạo mã công việc và mã xe giao hàng.
Tạo mã công việc và mã xe giao hàng
Để theo dõi xe giao hàng bằng cách sử dụng nhà cung cấp vị trí xe giao hàng, hãy tạo Mã thông báo web JSON (JWT) có mã công việc và mã xác nhận quyền sở hữu mã xe giao hàng.
Để tạo tải trọng JWT, hãy thêm một thông báo xác nhận quyền sở hữu bổ sung vào phần uỷ quyền bằng các khoá taskid và deliveryvehicleid rồi đặt giá trị của mỗi khoá thành *. Bạn phải tạo mã thông báo bằng vai trò Cloud IAM của Cloud IAM Fleet Engine Super Service. Xin lưu ý rằng việc này cấp quyền truy cập rộng rãi để tạo, đọc và sửa đổi các thực thể Fleet Engine, và bạn chỉ nên chia sẻ quyền này với những người dùng đáng tin cậy.
Ví dụ sau đây cho biết cách tạo mã thông báo để theo dõi bằng xe và nhiệm vụ:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
"sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"scope": "https://www.googleapis.com/auth/xapi",
"authorization": {
"taskid": "*",
"deliveryvehicleid": "*",
}
}
Tạo trình tìm nạp mã thông báo xác thực
Bạn có thể tạo trình tìm nạp mã thông báo xác thực để truy xuất mã thông báo được tạo cùng với các thông báo xác nhận quyền sở hữu phù hợp trên máy chủ bằng cách sử dụng chứng chỉ tài khoản dịch vụ cho dự án của bạn. Điều quan trọng là chỉ đúc mã thông báo trên máy chủ của bạn và không bao giờ chia sẻ chứng chỉ của bạn trên bất kỳ ứng dụng nào. Nếu không, tính bảo mật của hệ thống sẽ bị xâm phạm.
Trình tìm nạp phải trả về một cấu trúc dữ liệu với hai trường, được gói trong một Promise:
- Một chuỗi
token
. - Số
expiresInSeconds
. Mã thông báo sẽ hết hạn trong khoảng thời gian này sau khi tìm nạp.
Thư viện theo dõi nhóm JavaScript sẽ yêu cầu một mã thông báo thông qua trình tìm nạp mã thông báo xác thực khi bất kỳ trường hợp nào sau đây xảy ra:
- Giao diện này không có mã thông báo hợp lệ, chẳng hạn như khi chưa gọi trình tìm nạp trong một lần tải trang mới hoặc khi trình tìm nạp không trả về mã thông báo.
- Mã thông báo mà tính năng này tìm nạp trước đó đã hết hạn.
- Mã thông báo mà nó tìm nạp trước đó sẽ hết hạn trong vòng một phút.
Nếu không, thư viện sẽ sử dụng mã thông báo vẫn hợp lệ và đã phát hành trước đó và không gọi trình tìm nạp.
Ví dụ sau đây cho thấy cách tạo trình tìm nạp mã thông báo xác thực:
JavaScript
function authTokenFetcher(options) {
// options is a record containing two keys called
// serviceType and context. The developer should
// generate the correct SERVER_TOKEN_URL and request
// based on the values of these fields.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.Token,
expiresInSeconds: data.ExpiresInSeconds
};
}
TypeScript
function authTokenFetcher(options: {
serviceType: google.maps.journeySharing.FleetEngineServiceType,
context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
// The developer should generate the correct
// SERVER_TOKEN_URL based on options.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.token,
expiresInSeconds: data.expiration_timestamp_ms - Date.now(),
};
}
Khi triển khai điểm cuối phía máy chủ để đúc mã thông báo, hãy lưu ý những điều sau:
- Điểm cuối phải trả về thời gian hết hạn cho mã thông báo; trong ví dụ trên, điểm cuối được cung cấp là
data.ExpiresInSeconds
. - Trình tìm nạp mã thông báo xác thực phải chuyển thời gian hết hạn (tính bằng giây, kể từ thời điểm tìm nạp) cho thư viện, như minh hoạ trong ví dụ.
- SERVER_TOKEN_URL phụ thuộc vào cách triển khai phần phụ trợ của bạn, sau đây là các URL cho phần phụ trợ ứng dụng mẫu:
- https://
SERVER_URL
/token/delivery_driver/DELIVERY_VEHICLE_ID
- https://
SERVER_URL
/token/delivery_consumer/TRACKING_ID
- https://
SERVER_URL
/token/fleet_reader
- https://
Tải bản đồ từ HTML
Ví dụ sau đây cho thấy cách tải thư viện Chia sẻ hành trình JavaScript qua một URL đã chỉ định. Tham số callback thực thi hàm initMap
sau khi API tải. Thuộc tính defer (trì hoãn) cho phép trình duyệt tiếp tục hiển thị phần còn lại của trang trong khi API tải.
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing" defer></script>
Đi theo một xe giao hàng
Phần này cho biết cách sử dụng Thư viện theo dõi nhóm JavaScript để theo dõi một xe giao hàng. Hãy nhớ tải thư viện từ hàm callback được chỉ định trong thẻ tập lệnh trước khi chạy mã.
Tạo thực thể cho nhà cung cấp dịch vụ giao hàng xe
Thư viện theo dõi nhóm JavaScript xác định sẵn một trình cung cấp vị trí cho Fleet Engine Deliveries API. Sử dụng mã dự án và tham chiếu đến nhà máy mã thông báo của bạn để tạo bản sao của dự án đó.
JavaScript
locationProvider =
new google.maps.journeySharing
.FleetEngineDeliveryVehicleLocationProvider({
projectId,
authTokenFetcher,
// Optionally, you may specify
// deliveryVehicleId to immediately start
// tracking.
deliveryVehicleId: 'your-delivery-id',
});
TypeScript
locationProvider =
new google.maps.journeySharing
.FleetEngineDeliveryVehicleLocationProvider({
projectId,
authTokenFetcher,
// Optionally, you may specify
// deliveryVehicleId to immediately start
// tracking.
deliveryVehicleId: 'your-delivery-id',
});
Khởi chạy chế độ xem bản đồ
Sau khi tải thư viện Chia sẻ hành trình JavaScript, hãy khởi chạy chế độ xem bản đồ và thêm chế độ xem đó vào trang HTML. Trang của bạn phải chứa một phần tử <div> chứa chế độ xem bản đồ. Phần tử <div> được đặt tên là map_canvas trong ví dụ bên dưới.
JavaScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// 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 wish.
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],
// Styling customizations; see below.
vehicleMarkerSetup: vehicleMarkerSetup,
anticipatedRoutePolylineSetup:
anticipatedRoutePolylineSetup,
// Any undefined styling options will use defaults.
});
// 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 wish.
mapView.map.setCenter('Times Square, New York, NY');
mapView.map.setZoom(14);
Theo dõi các sự kiện thay đổi
Bạn có thể truy xuất thông tin meta về một tác vụ từ đối tượng deliveryVehicle
bằng cách sử dụng trình cung cấp vị trí. Thông tin siêu dữ liệu bao gồm thời gian đến dự kiến và quãng đường còn lại trước lần đón hoặc trả xe tiếp theo. Các thay đổi đối với thông tin meta sẽ kích hoạt sự kiện update. Ví dụ sau cho thấy cách theo dõi các sự kiện thay đổi này.
JavaScript
locationProvider.addListener('update', e => {
// e.deliveryVehicle contains data that may be
// useful to the rest of the UI.
if (e.deliveryVehicle) {
console.log(e.deliveryVehicle.remainingDuration);
}
});
TypeScript
locationProvider.addListener('update',
(e: google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProviderUpdateEvent) => {
// e.deliveryVehicle contains data that may be
// useful to the rest of the UI.
if (e.deliveryVehicle) {
console.log(e.deliveryVehicle.remainingDuration);
}
});
Nghe lỗi
Các lỗi phát sinh không đồng bộ khi yêu cầu giao thông tin xe kích hoạt các sự kiện lỗi. Ví dụ sau cho biết cách theo dõi những sự kiện này để xử lý lỗi.
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);
});
Dừng theo dõi
Để ngăn trình cung cấp vị trí theo dõi xe giao hàng, hãy xoá mã xe giao hàng khỏi nhà cung cấp vị trí.
JavaScript
locationProvider.deliveryVehicleId = '';
TypeScript
locationProvider.deliveryVehicleId = '';
Xóa trình cung cấp vị trí khỏi chế độ xem bản đồ
Ví dụ sau đây cho thấy cách xoá một nhà cung cấp vị trí khỏi chế độ xem bản đồ.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
Xem nhóm thiết bị giao hàng
Phần này cho biết cách sử dụng thư viện Chia sẻ hành trình JavaScript để xem nhóm phân phối. Hãy nhớ tải thư viện từ hàm callback được chỉ định trong thẻ tập lệnh trước khi chạy mã.
Tạo thực thể cho nhà cung cấp vị trí nhóm giao hàng
Thư viện theo dõi nhóm JavaScript định nghĩa trước một trình cung cấp vị trí để tìm nạp nhiều phương tiện từ FleetEngine Deliveries API. Sử dụng mã dự án cũng như tệp tham chiếu đến trình tìm nạp mã thông báo để tạo thực thể cho dự án đó.
JavaScript
locationProvider =
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"',
});
TypeScript
locationProvider =
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"',
});
deliveryVehicleFilter
chỉ định một truy vấn dùng để lọc các xe xuất hiện trên bản đồ. Bộ lọc này được chuyển trực tiếp đến Fleet Engine. Hãy xem ListDeliveryVehiclesRequest.filter
để biết các định dạng được hỗ trợ.
locationRestriction
giới hạn khu vực hiển thị phương tiện di chuyển trên bản đồ.
Chế độ này cũng kiểm soát việc tính năng theo dõi vị trí có đang hoạt động hay không. Tính năng theo dõi vị trí sẽ không bắt đầu cho đến khi bạn đặt tùy chọn này.
Sau khi tạo trình cung cấp vị trí, hãy khởi động chế độ xem bản đồ.
Đặt giới hạn vị trí bằng cách sử dụng khung nhìn bản đồ
Các giới hạn locationRestriction
có thể được định cấu hình để khớp với khu vực hiện đang hiển thị trong chế độ xem bản đồ.
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;
}
});
Theo dõi các sự kiện thay đổi
Bạn có thể truy xuất thông tin meta về nhóm thiết bị từ đối tượng deliveryVehicles
bằng cách sử dụng trình cung cấp vị trí. Thông tin meta bao gồm các thuộc tính của xe, chẳng hạn như trạng thái điều hướng, quãng đường còn lại và các thuộc tính tuỳ chỉnh; xem tài liệu tham khảo để biết thêm thông tin chi tiết. Việc thay đổi thông tin meta sẽ kích hoạt sự kiện update. Ví dụ sau cho thấy cách theo dõi các sự kiện thay đổi này.
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);
}
}
});
Nghe lỗi
Các lỗi phát sinh không đồng bộ khi yêu cầu thông tin về nhóm phân phối sẽ kích hoạt các sự kiện lỗi. Để xem ví dụ minh hoạ cách theo dõi những sự kiện này, hãy tham khảo bài viết Nghe lỗi.
Dừng theo dõi
Để ngăn trình cung cấp vị trí theo dõi nhóm thiết bị phân phối, hãy đặt các giới hạn của trình cung cấp vị trí thành rỗng.
JavaScript
locationProvider.locationRestriction = null;
TypeScript
locationProvider.locationRestriction = null;
Xóa trình cung cấp vị trí khỏi chế độ xem bản đồ
Ví dụ sau đây cho thấy cách xoá một nhà cung cấp vị trí khỏi chế độ xem bản đồ.
JavaScript
mapView.removeLocationProvider(locationProvider);
TypeScript
mapView.removeLocationProvider(locationProvider);
Theo dõi xe giao hàng trong khi xem đội xe giao hàng
Trong khi xem đội xe, bạn có thể hiển thị tuyến đường và các nhiệm vụ sắp tới cho một phương tiện giao hàng cụ thể. Để thực hiện việc này, hãy tạo thực thể cho cả Nhà cung cấp vị trí nhóm giao hàng và Trình cung cấp vị trí xe giao hàng, rồi thêm cả hai vào chế độ xem bản đồ:
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
});
Nhà cung cấp vị trí nhóm giao hàng bắt đầu cho thấy các xe giao hàng trên bản đồ. Hãy tuỳ chỉnh điểm đánh dấu để cho phép nhà cung cấp vị trí xe giao hàng theo dõi xe giao hàng khi người dùng nhấp vào điểm đánh dấu của đội xe:
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();
});
}
};
Ẩn điểm đánh dấu đối với nhà cung cấp vị trí xe giao hàng để ngăn việc hiển thị 2 điểm đánh dấu cho cùng một chiếc xe:
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);
}
};
Tuỳ chỉnh giao diện của bản đồ cơ sở
Để tuỳ chỉnh giao diện của thành phần bản đồ, hãy tạo kiểu cho bản đồ bằng công cụ trên đám mây hoặc bằng cách thiết lập các tuỳ chọn ngay trong mã.
Sử dụng kiểu bản đồ dựa trên đám mây
Định kiểu bản đồ dựa trên đám mây cho phép bạn tạo và chỉnh sửa kiểu bản đồ cho bất kỳ ứng dụng nào sử dụng Google Maps từ bảng điều khiển Google Cloud mà không yêu cầu thay đổi mã.
Các kiểu bản đồ được lưu dưới dạng mã bản đồ trong dự án Cloud của bạn. Để áp dụng một kiểu cho bản đồ Theo dõi nhóm JavaScript, hãy chỉ định mapId
khi bạn tạo JourneySharingMapView
. Bạn không thể thay đổi hoặc thêm trường mapId
sau khi tạo thực thể cho JourneySharingMapView
. Ví dụ
sau đây cho biết cách bật kiểu bản đồ đã tạo trước đó bằng
mã bản đồ.
JavaScript
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
mapOptions: {
mapId: 'YOUR_MAP_ID'
}
});
TypeScript
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
mapOptions: {
mapId: 'YOUR_MAP_ID'
}
});
Sử dụng kiểu bản đồ dựa trên mã
Một cách khác để tuỳ chỉnh kiểu bản đồ là đặt mapOptions
khi bạn tạo JourneySharingMapView
.
JavaScript
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
mapOptions: {
styles: [
{
"featureType": "road.arterial",
"elementType": "geometry",
"stylers": [
{ "color": "#CCFFFF" }
]
}
]
}
});
TypeScript
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
mapOptions: {
styles: [
{
"featureType": "road.arterial",
"elementType": "geometry",
"stylers": [
{ "color": "#CCFFFF" }
]
}
]
}
});
Sử dụng các tuỳ chỉnh điểm đánh dấu
Với Thư viện theo dõi nhóm JavaScript, bạn có thể tuỳ chỉnh giao diện của các điểm đánh dấu được thêm vào bản đồ. Bạn thực hiện việc này bằng cách chỉ định các cách tuỳ chỉnh điểm đánh dấu. Thư viện theo dõi đội xe sẽ áp dụng điểm đánh dấu này trước khi thêm điểm đánh dấu vào bản đồ và trong mỗi lần cập nhật điểm đánh dấu.
Cách tuỳ chỉnh đơn giản nhất là chỉ định một đối tượng MarkerOptions
sẽ áp dụng cho tất cả các điểm đánh dấu cùng loại. Các thay đổi đã chỉ định trong đối tượng sẽ được áp dụng sau khi tạo từng điểm đánh dấu, ghi đè mọi tuỳ chọn mặc định.
Tuỳ chọn nâng cao hơn là chỉ định hàm tuỳ chỉnh. Các hàm tuỳ chỉnh cho phép tạo kiểu cho điểm đánh dấu dựa trên dữ liệu, cũng như thêm tính tương tác vào điểm đánh dấu, chẳng hạn như xử lý lượt nhấp. Cụ thể, tính năng Theo dõi nhóm phương tiện sẽ truyền dữ liệu đến chức năng tuỳ chỉnh về loại đối tượng mà điểm đánh dấu đại diện: xe, trạm dừng hoặc nhiệm vụ. Sau đó, việc này cho phép kiểu điểm đánh dấu thay đổi dựa trên trạng thái hiện tại của chính phần tử điểm đánh dấu đó; ví dụ: số điểm dừng còn lại hoặc loại tác vụ. Bạn thậm chí có thể kết hợp dữ liệu từ các nguồn bên ngoài Fleet Engine và tạo kiểu cho điểm đánh dấu dựa trên thông tin đó.
Ngoài ra, bạn có thể dùng các chức năng tuỳ chỉnh để lọc chế độ hiển thị điểm đánh dấu.
Để thực hiện việc này, hãy gọi setVisible(false)
trên điểm đánh dấu.
Tuy nhiên, vì lý do hiệu suất, bạn nên lọc bằng bộ lọc gốc trong trình cung cấp vị trí, chẳng hạn như FleetEngineDeliveryFleetLocationProvider.deliveryVehicleFilter
.
Tuy nhiên, khi cần thêm chức năng lọc, bạn có thể áp dụng lọc bằng cách sử dụng chức năng tuỳ chỉnh.
Thư viện Theo dõi nhóm vận chuyển cung cấp các thông số tuỳ chỉnh sau:
Thay đổi kiểu của điểm đánh dấu bằng MarkerOptions
Ví dụ sau đây cho thấy cách định cấu hình kiểu của điểm đánh dấu xe bằng đối tượng MarkerOptions
. Hãy làm theo mẫu này để tuỳ chỉnh kiểu của mọi điểm đánh dấu bằng cách sử dụng bất kỳ tham số tuỳ chỉnh điểm đánh dấu nào nêu trên.
JavaScript
deliveryVehicleMarkerCustomization = {
cursor: 'grab'
};
TypeScript
deliveryVehicleMarkerCustomization = {
cursor: 'grab'
};
Sử dụng các hàm tuỳ chỉnh để thay đổi kiểu của điểm đánh dấu
Ví dụ sau đây cho thấy cách định cấu hình kiểu của điểm đánh dấu xe. Hãy làm theo mẫu này để tuỳ chỉnh kiểu của một điểm đánh dấu bất kỳ bằng cách sử dụng bất kỳ thông số tuỳ chỉnh điểm đánh dấu nào nêu trên.
JavaScript
deliveryVehicleMarkerCustomization =
(params) => {
var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
params.marker.setLabel(`${stopsLeft}`);
};
TypeScript
deliveryVehicleMarkerCustomization =
(params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
params.marker.setLabel(`${stopsLeft}`);
};
Thêm hoạt động xử lý lượt nhấp vào điểm đánh dấu
Ví dụ sau đây cho thấy cách thêm thao tác nhấp vào điểm đánh dấu xe. Hãy làm theo mẫu này để thêm thao tác xử lý lượt nhấp vào bất kỳ điểm đánh dấu nào bằng cách sử dụng bất kỳ tham số tuỳ chỉnh điểm đánh dấu nào nêu trên.
JavaScript
deliveryVehicleMarkerCustomization =
(params) => {
if (params.isNew) {
params.marker.addListener('click', () => {
// Perform desired action.
});
}
};
TypeScript
deliveryVehicleMarkerCustomization =
(params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
if (params.isNew) {
params.marker.addListener('click', () => {
// Perform desired action.
});
}
};
Lọc điểm đánh dấu có thể nhìn thấy
Ví dụ sau đây cho thấy cách lọc những điểm đánh dấu xe có thể nhìn thấy. Hãy làm theo mẫu này để lọc mọi điểm đánh dấu bằng cách sử dụng bất kỳ thông số tuỳ chỉnh điểm đánh dấu nào nêu trên.
JavaScript
deliveryVehicleMarkerCustomization =
(params) => {
var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
if (stopsLeft > 10) {
params.marker.setVisible(false);
}
};
TypeScript
deliveryVehicleMarkerCustomization =
(params: DeliveryVehicleMarkerCustomizationFunctionParams) => {
var stopsLeft = params.vehicle.remainingVehicleJourneySegments.length;
if (stopsLeft > 10) {
params.marker.setVisible(false);
}
};
Sử dụng chế độ tuỳ chỉnh nhiều đường khi đi theo một xe giao hàng
Với Thư viện theo dõi đội xe JavaScript, bạn cũng có thể tuỳ chỉnh giao diện và cảm nhận về tuyến đường của xe bạn theo dõi trên bản đồ. Thư viện sẽ tạo một đối tượng google.maps.Polyline
cho từng cặp toạ độ trong đường dẫn đang hoạt động hoặc còn lại của xe.
Bạn có thể tạo kiểu cho các đối tượng Polyline
bằng cách chỉ định tuỳ chỉnh nhiều đường. Sau đó, thư viện sẽ áp dụng các phần tuỳ chỉnh này trong 2 trường hợp: trước khi thêm đối tượng vào bản đồ và khi dữ liệu dùng cho các đối tượng đã thay đổi.
Tương tự như việc tuỳ chỉnh điểm đánh dấu, bạn có thể chỉ định một tập hợp PolylineOptions
để áp dụng cho mọi đối tượng Polyline
trùng khớp khi các đối tượng đó được tạo hoặc cập nhật.
Tương tự, bạn có thể chỉ định một hàm tuỳ chỉnh. Các hàm tuỳ chỉnh cho phép tạo kiểu riêng cho đối tượng dựa trên dữ liệu do Fleet Engine gửi.
Hàm này có thể thay đổi kiểu của từng đối tượng dựa trên trạng thái hiện tại của xe; ví dụ: tô màu cho đối tượng Polyline
sang màu đậm hơn hoặc làm cho đối tượng dày hơn khi xe di chuyển chậm hơn. Bạn thậm chí có thể tham gia dựa trên các nguồn bên ngoài Fleet Engine và tạo kiểu cho đối tượng Polyline
dựa trên thông tin đó.
Bạn có thể chỉ định các thành phần tuỳ chỉnh bằng cách sử dụng các tham số được cung cấp trong FleetEngineDeliveryVehicleLocationProviderOptions
.
Bạn có thể đặt tuỳ chỉnh cho các trạng thái đường dẫn khác nhau trong hành trình của xe – đã đi, đang di chuyển hoặc chưa đi. Các tham số như sau:
takenPolylineCustomization
, cho một đường dẫn đã đi;activePolylineCustomization
, đối với một đường dẫn di chuyển chủ động;remainingPolylineCustomization
, cho một đường dẫn chưa đi.
Thay đổi kiểu của đối tượng Polyline
bằng PolylineOptions
Ví dụ sau cho thấy cách định cấu hình định kiểu cho đối tượng Polyline
bằng PolylineOptions
.
Hãy tuân theo mẫu này để tuỳ chỉnh kiểu của bất kỳ đối tượng Polyline
nào bằng cách sử dụng bất kỳ tuỳ chỉnh nhiều đường nào nêu trên.
JavaScript
activePolylineCustomization = {
strokeWidth: 5,
strokeColor: 'black',
};
TypeScript
activePolylineCustomization = {
strokeWidth: 5,
strokeColor: 'black',
};
Thay đổi kiểu của đối tượng Polyline
bằng các hàm tuỳ chỉnh
Ví dụ sau đây cho thấy cách định cấu hình kiểu cho một đối tượng Polyline đang hoạt động bằng cách sử dụng hàm tuỳ chỉnh. Hãy làm theo mẫu này để tuỳ chỉnh kiểu của mọi đối tượng Polyline
bằng cách sử dụng bất kỳ tham số tuỳ chỉnh hình nhiều đường nào nêu trên.
JavaScript
// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
(params) => {
const distance = params.deliveryVehicle.remainingDistanceMeters;
if (distance < 1000) {
// params.polylines contains an ordered list of Polyline objects for
// the path.
for (const polylineObject of params.polylines) {
polylineObject.setOptions({strokeColor: 'green'});
}
}
};
TypeScript
// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
(params: DeliveryVehiclePolylineCustomizationFunctionParams) => {
const distance = params.deliveryVehicle.remainingDistanceMeters;
if (distance < 1000) {
// params.polylines contains an ordered list of Polyline objects for
// the path.
for (const polylineObject of params.polylines) {
polylineObject.setOptions({strokeColor: 'green'});
}
}
};
Kiểm soát chế độ hiển thị của các đối tượng Polyline
Theo mặc định, mọi đối tượng Polyline
đều xuất hiện. Để ẩn một đối tượng Polyline
, hãy đặt thuộc tính visible
của đối tượng đó:
JavaScript
remainingPolylineCustomization = {visible: false};
TypeScript
remainingPolylineCustomization = {visible: false};
Hiện InfoWindow
cho xe hoặc điểm đánh dấu vị trí
Bạn có thể sử dụng InfoWindow
để hiện thêm thông tin về xe hoặc điểm đánh dấu vị trí.
Ví dụ sau đây cho biết cách tạo InfoWindow
và đính kèm mã này vào điểm đánh dấu xe.
JavaScript
// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
{disableAutoPan: true});
// (Assumes a delivery vehicle location provider.)
locationProvider.addListener('update', e => {
if (e.deliveryVehicle) {
const distance =
e.deliveryVehicle.remainingDistanceMeters;
infoWindow.setContent(
`Your vehicle is ${distance}m away from the next task.`);
// 2. Attach the info window to a vehicle marker.
// This property can return multiple markers.
const marker = mapView.vehicleMarkers[0];
infoWindow.open(mapView.map, marker);
}
});
// 3. Close the info window.
infoWindow.close();
TypeScript
// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
{disableAutoPan: true});
// (Assumes a delivery vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProviderUpdateEvent) => {
if (e.deliveryVehicle) {
const distance =
e.deliveryVehicle.remainingDistanceMeters;
infoWindow.setContent(
`Your vehicle is ${distance}m away from the next task.`);
// 2. Attach the info window to a vehicle marker.
// This property can return multiple markers.
const marker = mapView.vehicleMarkers[0];
infoWindow.open(mapView.map, marker);
}
});
// 3. Close the info window.
infoWindow.close();
Tắt tính năng tự động điều chỉnh
Bạn có thể dừng chế độ tự động điều chỉnh khung nhìn với xe và tuyến đường dự kiến để bản đồ không cho khớp vào khung nhìn bằng cách tắt tính năng tự động điều chỉnh. Ví dụ sau cho thấy cách tắt tính năng tự động điều chỉnh khi bạn định cấu hình chế độ xem bản đồ chia sẻ hành trình.
JavaScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
automaticViewportMode:
google.maps.journeySharing
.AutomaticViewportMode.NONE,
...
});
TypeScript
const mapView = new
google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map_canvas'),
locationProviders: [locationProvider],
automaticViewportMode:
google.maps.journeySharing
.AutomaticViewportMode.NONE,
...
});
Thay thế bản đồ hiện tại
Bạn có thể thay thế bản đồ hiện có bao gồm các điểm đánh dấu hoặc các yếu tố tuỳ chỉnh khác mà không làm mất các yếu tố tuỳ chỉnh đó.
Ví dụ: giả sử bạn có một trang web có thực thể google.maps.Map
chuẩn hiển thị điểm đánh dấu:
<!DOCTYPE html>
<html>
<head>
<style>
/* Set the size of the div element that contains the map */
#map {
height: 400px; /* The height is 400 pixels */
width: 100%; /* The width is the width of the web page */
}
</style>
</head>
<body>
<h3>My Google Maps Demo</h3>
<!--The div element for the map -->
<div id="map"></div>
<script>
// Initialize and add the map
function initMap() {
// The location of Uluru
var uluru = {lat: -25.344, lng: 131.036};
// The map, initially centered at Mountain View, CA.
var map = new google.maps.Map(document.getElementById('map'));
map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
// The marker, now positioned at Uluru
var marker = new google.maps.Marker({position: uluru, map: map});
}
</script>
<!-- Load the API from the specified URL.
* The async attribute allows the browser to render the page while the API loads.
* The key parameter will contain your own API key (which is not needed for this tutorial).
* The callback parameter executes the initMap() function.
-->
<script defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>
</body>
</html>
Cách thêm thư viện Chia sẻ hành trình JavaScript, bao gồm cả tính năng Theo dõi nhóm thiết bị:
- Thêm mã cho nhà máy mã thông báo xác thực.
- Khởi động trình cung cấp vị trí trong hàm
initMap()
. - Khởi động chế độ xem bản đồ trong hàm
initMap()
. Chế độ xem này có chứa bản đồ. - Di chuyển nội dung tuỳ chỉnh của bạn vào hàm callback để khởi chạy chế độ xem bản đồ.
- Thêm thư viện vị trí vào trình tải API.
Ví dụ sau đây cho thấy các thay đổi cần thực hiện:
<!DOCTYPE html>
<html>
<head>
<style>
/* Set the size of the div element that contains the map */
#map {
height: 400px; /* The height is 400 pixels */
width: 100%; /* The width is the width of the web page */
}
</style>
</head>
<body>
<h3>My Google Maps Demo</h3>
<!--The div element for the map -->
<div id="map"></div>
<script>
let locationProvider;
// (1) Authentication Token Fetcher
function authTokenFetcher(options) {
// options is a record containing two keys called
// serviceType and context. The developer should
// generate the correct SERVER_TOKEN_URL and request
// based on the values of these fields.
const response = await fetch(SERVER_TOKEN_URL);
if (!response.ok) {
throw new Error(response.statusText);
}
const data = await response.json();
return {
token: data.Token,
expiresInSeconds: data.ExpiresInSeconds
};
}
// Initialize and add the map
function initMap() {
// (2) Initialize location provider. Use FleetEngineDeliveryVehicleLocationProvider
// as appropriate.
locationProvider = new google.maps.journeySharing.FleetEngineDeliveryVehicleLocationProvider({
YOUR_PROVIDER_ID,
authTokenFetcher,
});
// (3) Initialize map view (which contains the map).
const mapView = new google.maps.journeySharing.JourneySharingMapView({
element: document.getElementById('map'),
locationProviders: [locationProvider],
// any styling options
});
mapView.addListener('ready', () => {
locationProvider.deliveryVehicleId = DELIVERY_VEHICLE_ID;
// (4) Add customizations like before.
// The location of Uluru
var uluru = {lat: -25.344, lng: 131.036};
// The map, initially centered at Mountain View, CA.
var map = mapView.map;
map.setOptions({center: {lat: 37.424069, lng: -122.0916944}, zoom: 14});
// The marker, now positioned at Uluru
var marker = new google.maps.Marker({position: uluru, map: map});
};
}
</script>
<!-- Load the API from the specified URL
* The async attribute allows the browser to render the page while the API loads
* The key parameter will contain your own API key (which is not needed for this tutorial)
* The callback parameter executes the initMap() function
*
* (5) Add the journey sharing library to the API loader, which includes Fleet Tracking functionality.
-->
<script defer
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&libraries=journeySharing">
</script>
</body>
</html>
Nếu bạn vận hành một phương tiện giao hàng có mã nhận dạng đã chỉ định ở gần Uluru, thì giờ đây, phương tiện đó sẽ hiển thị trên bản đồ.