Personalizar polilinhas do trajeto

Este documento aborda como personalizar a aparência das rotas de veículos rastreados em um mapa. As rotas são desenhadas em um mapa em polilinhas. Para cada par de coordenadas no trajeto ativo ou restante de um veículo, a biblioteca cria um google.maps.Polyline objeto. É possível definir o estilo dos objetos Polyline especificando personalizações de polilinha que a biblioteca aplica em duas situações:

  • Antes de adicionar os objetos ao mapa
  • Quando os dados usados para os objetos mudaram

Polilinhas de estilo

Assim como é possível personalizar marcadores, você pode definir o estilo das polilinhas de rota de diferentes maneiras:

  1. Definir o estilo das polilinhas de rota por tipo: use PolylineOptions para aplicar a todos os objetos Polyline correspondentes quando eles forem criados ou atualizados. Para conferir um exemplo, consulte Definir o estilo das polilinhas por tipo.

  2. Definir o estilo das polilinhas de rota com base em dados: especifique uma função de personalização com base em dados do rastreamento de frota ou de fontes externas:

    • Dados do rastreamento de frota: o rastreamento de frota transmite dados de polilinha para a função de personalização, incluindo dados sobre o estado atual do veículo. É possível definir o estilo das polilinhas com base nesses dados, incluindo a coloração do objeto Polyline em um tom mais escuro ou tornando-o mais espesso quando o veículo estiver se movendo mais lentamente.

    • Fontes externas: é possível combinar dados de rastreamento de frota com dados de fontes externas ao Fleet Engine e definir o estilo do objeto Polyline com base nessas informações.

    Para conferir um exemplo, consulte Definir o estilo das polilinhas com base em dados.

  3. Controlar a visibilidade das polilinhas de rota: é possível ocultar ou mostrar polilinhas usando a propriedade visible. Para mais detalhes, consulte Controlar a visibilidade das polilinhas neste guia.

  4. Mostrar informações adicionais para um marcador de veículo ou local: é possível mostrar informações adicionais usando a propriedade infowindow. Para mais detalhes, consulte Mostrar informações adicionais para um marcador de veículo ou local neste guia.

Opções de personalização de polilinha

As seguintes opções de personalização estão disponíveis em FleetEngineVehicleLocationProviderOptions e FleetEngineDeliveryVehicleLocationProviderOptions. É possível definir personalizações para diferentes estados de caminho na jornada do veículo:

Definir o estilo das polilinhas de rota por tipo

Para definir o estilo das polilinhas de rota por tipo, mude o estilo dos Polyline objetos usando PolylineOptions.

O exemplo a seguir mostra como configurar o estilo de um Polyline objeto com PolylineOptions. Siga esse padrão para personalizar o estilo de qualquer Polyline objeto usando qualquer uma das personalizações de polilinha de rota listadas em Opções de personalização de polilinha neste guia.

Exemplo de viagens sob demanda ou tarefas programadas

JavaScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

TypeScript

activePolylineCustomization = {
  strokeWidth: 5,
  strokeColor: 'black',
};

Definir o estilo das polilinhas de rota usando dados

Para definir o estilo das polilinhas de rota usando dados, mude o estilo dos objetos Polyline usando funções de personalização.

O exemplo a seguir mostra como configurar o estilo de uma rota ativa usando uma função de personalização. Siga esse padrão para personalizar o estilo de qualquer objeto Polyline usando qualquer um dos parâmetros de personalização de polilinha listados em Opções de personalização de polilinha neste guia.

Exemplo de viagens sob demanda

JavaScript

// Color the Polyline objects in green if the vehicle is nearby.
activePolylineCustomization =
  (params) => {
    const distance = params.vehicle.waypoints[0].distanceMeters;
    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: VehiclePolylineCustomizationFunctionParams) => {
    const distance = params.vehicle.waypoints[0].distanceMeters;
    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'});
      }
    }
  };

Exemplo de tarefas programadas

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

Exemplo de estilo com reconhecimento de trânsito (somente viagens sob demanda)

O Fleet Engine retorna dados de velocidade do tráfego para os caminhos ativos e restantes do veículo seguido. É possível usar essas informações para definir o estilo dos objetos Polyline de acordo com as velocidades do trânsito:

JavaScript

// Color the Polyline objects according to their real-time traffic levels
// using '#05f' for normal, '#fa0' for slow, and '#f33' for traffic jam.
activePolylineCustomization =
  FleetEngineVehicleLocationProvider.
      TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION;

// Or alter the objects further after the customization function has been
// run -- in this example, change the blue for normal to green:
activePolylineCustomization =
  (params) => {
    FleetEngineVehicleLocationProvider.
        TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION(params);
    for (const polylineObject of params.polylines) {
      if (polylineObject.get('strokeColor') === '#05f') {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

TypeScript

// Color the Polyline objects according to their real-time traffic levels
// using '#05f' for normal, '#fa0' for slow, and '#f33' for traffic jam.
activePolylineCustomization =
  FleetEngineVehicleLocationProvider.
      TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION;

// Or alter the objects further after the customization function has been
// run -- in this example, change the blue for normal to green:
activePolylineCustomization =
  (params: VehiclePolylineCustomizationFunctionParams) => {
    FleetEngineVehicleLocationProvider.
        TRAFFIC_AWARE_ACTIVE_POLYLINE_CUSTOMIZATION_FUNCTION(params);
    for (const polylineObject of params.polylines) {
      if (polylineObject.get('strokeColor') === '#05f') {
        polylineObject.setOptions({strokeColor: 'green'});
      }
    }
  };

Controlar a visibilidade das polilinhas

Por padrão, todos os objetos Polyline estão visíveis. Para tornar um objeto Polyline invisível, defina a propriedade visible como false.

Exemplo de viagens sob demanda ou tarefas programadas

JavaScript

remainingPolylineCustomization = {visible: false};

TypeScript

remainingPolylineCustomization = {visible: false};

Mostrar uma janela de informações para um marcador de veículo ou local

É possível usar um InfoWindow para mostrar mais informações sobre um marcador de veículo ou local.

O exemplo a seguir mostra como criar uma InfoWindow e anexá-la a um marcador de veículo.

Exemplo de viagens sob demanda

JavaScript

// 1. Create an info window.
const infoWindow = new google.maps.InfoWindow(
    {disableAutoPan: true});

// (Assumes a vehicle location provider.)
locationProvider.addListener('update', e => {
  if (e.vehicle) {
    const distance =
          e.vehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next drop-off point.`);

    // 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 vehicle location provider.)
locationProvider.addListener('update', (e: google.maps.journeySharing.FleetEngineVehicleLocationProviderUpdateEvent) => {
  if (e.vehicle) {
    const distance =
          e.vehicle.remainingDistanceMeters;
    infoWindow.setContent(
        `Your vehicle is ${distance}m away from the next drop-off.`);
    // 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();

Exemplo de tarefas programadas

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

A seguir