Símbolos (ícones vetoriais)

  1. Introdução
  2. Propriedades de um símbolo
  3. Símbolos predefinidos
  4. Adicionar um símbolo a um marcador
  5. Adicionar um símbolo a uma polilinha
  6. Animar um símbolo

Introdução

Um Symbol é um ícone baseado em vetor que pode ser mostrado em um Marker ou um Polyline. A forma do símbolo é definida por um caminho que usa a notação de caminho SVG. Embora path is the only required property, seja a única propriedade obrigatória, o objeto Symbol é compatível com diversas propriedades que permitem personalizar aspectos visuais, como a cor e a espessura do traço e do preenchimento. Veja a lista de propriedades.

Vários símbolos predefinidos estão disponíveis por meio da classe SymbolPath. Veja a lista abaixo.

Propriedades de um símbolo

O comportamento padrão de um Symbol varia um pouco, dependendo de ele aparecer em um marcador ou em uma polilinha. Essas variações são descritas na lista de propriedades a seguir.

Um Symbol oferece suporte às seguintes propriedades:

  • path (obrigatório) é o caminho que define a forma do símbolo. Você pode usar um dos caminhos predefinidos em google.maps.SymbolPath ou escolher um caminho personalizado usando a notação de caminho SVG. Observação: caminhos de vetores em uma polilinha devem ficar em um quadrado de 22 x 22 pixels. Se o caminho inclui pontos fora desse quadrado, você precisa ajustar a propriedade scale do símbolo para um valor fracionário, como 0.2, de modo que o resultado dos pontos da escala fiquem dentro desse quadrado.
  • anchor define a posição do símbolo em relação ao marcador ou à polilinha. As coordenadas do caminho do símbolo são convertidas para a esquerda e para cima pelas coordenadas x e y da âncora, respectivamente. Por padrão, um símbolo é ancorado em (0, 0). A posição é expressa no mesmo sistema de coordenadas que o caminho do símbolo.
  • fillColor é a cor do preenchimento do símbolo (isto é, a região delimitada pelo traço). Todas as cores CSS3 são permitidas, exceto cores nomeadas estendidas. Para marcadores de símbolos, o padrão é "preto". Para símbolos em polilinhas, o padrão é a cor do traço da polilinha correspondente.
  • fillOpacity define a opacidade relativa (isto é, a falta de transparência) de preenchimento do símbolo. Os valores variam de 0.0 (totalmente transparente) a 1.0 (totalmente opaco). O padrão é 0.0.
  • rotation é o ângulo pelo qual o símbolo deve ser girado, expresso em graus no sentido horário. Por padrão, um marcador de símbolo tem uma rotação 0 e um símbolo em uma polilinha é girado de acordo com o ângulo da borda em que está posicionado. A definição da rotação de um símbolo em uma polilinha fixa a rotação desse símbolo, que deixa de seguir a curva da linha.
  • scale define o valor da escala do símbolo em tamanho. Para marcadores de símbolo, a escala padrão é 1. Após o dimensionamento, o símbolo pode ter qualquer tamanho. Para símbolos em uma polilinha, a escala padrão é a espessura do traço da polilinha. Depois da escala, o símbolo precisa ficar dentro de um quadrado de 22 x 22 pixels, centralizado na âncora do símbolo.
  • strokeColor é a cor do traço do símbolo. Todas as cores CSS3 são permitidas, exceto cores nomeadas estendidas. Para símbolos em marcadores, o padrão é "preto". Para símbolos em uma polilinha, a cor padrão é a cor do traço da polilinha.
  • strokeOpacity determina a opacidade relativa (isto é, a falta de transparência) do traço do símbolo. Os valores variam de 0.0 (totalmente transparente) a 1.0 (totalmente opaco). Para marcadores de símbolo, o padrão é 1.0. Para símbolos em uma polilinha, o padrão é a opacidade do traço da polilinha.
  • strokeWeight define a espessura do contorno do símbolo. O padrão é o scale do símbolo.

Símbolos predefinidos

A API Maps JavaScript fornece alguns símbolos incorporados que você pode adicionar a marcadores ou polilinhas via classe SymbolPath.

Os símbolos padrão incluem um círculo e dois tipos de setas. Estão disponíveis setas para frente e para trás. Isso é particularmente útil para polilinhas porque a orientação de um símbolo na polilinha é fixa. A direção para frente é considerada como a direção para o término da polilinha.

O traço e o preenchimento dos símbolos predefinidos podem ser alterados usando as opções de símbolo padrão.

Estão incluídos os seguintes símbolos predefinidos:

Nome Descrição Exemplo
google.maps.SymbolPath.CIRCLE Um círculo.
google.maps.SymbolPath.BACKWARD_CLOSED_ARROW Uma seta apontando para trás que é fechada em todos os lados.
google.maps.SymbolPath.FORWARD_CLOSED_ARROW Uma seta apontando para a frente que é fechada em todos os lados.
google.maps.SymbolPath.BACKWARD_OPEN_ARROW Uma seta apontando para trás que é aberta em um dos lados.
google.maps.SymbolPath.FORWARD_OPEN_ARROW Uma seta apontando para a frente que é aberta em um dos lados.

Adicionar um símbolo a um marcador

Para mostrar um ícone com base em vetor em um marcador, transmita o literal de um objeto Symbol com o caminho desejado para a propriedade icon do marcador. O exemplo a seguir usa notação de caminho SVG para criar um ícone personalizado para um marcador.

TypeScript

// This example uses SVG path notation to add a vector-based symbol
// as the icon for a marker. The resulting icon is a marker-shaped
// symbol with a blue fill and no border.

function initMap(): void {
  const center = new google.maps.LatLng(-33.712451, 150.311823);
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 9,
      center: center,
    }
  );

  const svgMarker = {
    path: "M-1.547 12l6.563-6.609-1.406-1.406-5.156 5.203-2.063-2.109-1.406 1.406zM0 0q2.906 0 4.945 2.039t2.039 4.945q0 1.453-0.727 3.328t-1.758 3.516-2.039 3.070-1.711 2.273l-0.75 0.797q-0.281-0.328-0.75-0.867t-1.688-2.156-2.133-3.141-1.664-3.445-0.75-3.375q0-2.906 2.039-4.945t4.945-2.039z",
    fillColor: "blue",
    fillOpacity: 0.6,
    strokeWeight: 0,
    rotation: 0,
    scale: 2,
    anchor: new google.maps.Point(0, 20),
  };

  new google.maps.Marker({
    position: map.getCenter(),
    icon: svgMarker,
    map: map,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// This example uses SVG path notation to add a vector-based symbol
// as the icon for a marker. The resulting icon is a marker-shaped
// symbol with a blue fill and no border.
function initMap() {
  const center = new google.maps.LatLng(-33.712451, 150.311823);
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 9,
    center: center,
  });
  const svgMarker = {
    path: "M-1.547 12l6.563-6.609-1.406-1.406-5.156 5.203-2.063-2.109-1.406 1.406zM0 0q2.906 0 4.945 2.039t2.039 4.945q0 1.453-0.727 3.328t-1.758 3.516-2.039 3.070-1.711 2.273l-0.75 0.797q-0.281-0.328-0.75-0.867t-1.688-2.156-2.133-3.141-1.664-3.445-0.75-3.375q0-2.906 2.039-4.945t4.945-2.039z",
    fillColor: "blue",
    fillOpacity: 0.6,
    strokeWeight: 0,
    rotation: 0,
    scale: 2,
    anchor: new google.maps.Point(0, 20),
  };

  new google.maps.Marker({
    position: map.getCenter(),
    icon: svgMarker,
    map: map,
  });
}

window.initMap = initMap;
index.js
Exemplo

Testar amostra

Adicionar um símbolo a uma polilinha

Para mostrar símbolos em uma polilinha, defina a propriedade icons[] do objeto PolylineOptions. A matriz icons[] usa um ou mais literais de objeto IconSequence com as seguintes propriedades:

  • icon (obrigatório) é o símbolo a ser renderizado na linha.
  • offset determina a distância entre o início da linha em que um ícone deve ser renderizado. Essa distância pode ser expressa como uma porcentagem do comprimento da linha (por exemplo, "50%") ou em pixels (por exemplo, "50 px"). O padrão é "100%".
  • repeat determina a distância entre ícones consecutivos na linha. Essa distância pode ser expressa como uma porcentagem do comprimento da linha (por exemplo, "50%") ou em pixels (por exemplo, "50 px"). Para desativar a repetição do ícone, especifique "0". O padrão é "0".

Com uma combinação de símbolos e da classe PolylineOptions, você ganha bastante controle sobre a aparência de polilinhas no seu mapa. Veja a seguir alguns exemplos de personalizações possíveis.

Setas

Use a propriedade IconSequence.offset para adicionar setas ao início ou ao fim da sua polilinha.

// Define a symbol using a predefined path (an arrow)
// supplied by the Google Maps JavaScript API.
var lineSymbol = {
  path: google.maps.SymbolPath.FORWARD_CLOSED_ARROW
};

// Create the polyline and add the symbol via the 'icons' property.
var line = new google.maps.Polyline({
  path: [{lat: 22.291, lng: 153.027}, {lat: 18.291, lng: 153.027}],
  icons: [{
    icon: lineSymbol,
    offset: '100%'
  }],
  map: map
});

Exemplo

Linhas tracejadas

Aplique um efeito de linha tracejada definindo a opacidade da polilinha como 0 e sobrepondo um símbolo opaco sobre a linha em intervalos regulares.

// Define a symbol using SVG path notation, with an opacity of 1.
var lineSymbol = {
  path: 'M 0,-1 0,1',
  strokeOpacity: 1,
  scale: 4
};

// Create the polyline, passing the symbol in the 'icons' property.
// Give the line an opacity of 0.
// Repeat the symbol at intervals of 20 pixels to create the dashed effect.
var line = new google.maps.Polyline({
  path: [{lat: 22.291, lng: 153.027}, {lat: 18.291, lng: 153.027}],
  strokeOpacity: 0,
  icons: [{
    icon: lineSymbol,
    offset: '0',
    repeat: '20px'
  }],
  map: map
});

Exemplo

Caminhos personalizados

Os símbolos personalizados permitem adicionar várias formas a uma polilinha.

// Define the custom symbols. All symbols are defined via SVG path notation.
// They have varying stroke color, fill color, stroke weight,
// opacity and rotation properties.
  var symbolOne = {
    path: 'M -2,0 0,-2 2,0 0,2 z',
    strokeColor: '#F00',
    fillColor: '#F00',
    fillOpacity: 1
  };

  var symbolTwo = {
    path: 'M -1,0 A 1,1 0 0 0 -3,0 1,1 0 0 0 -1,0M 1,0 A 1,1 0 0 0 3,0 1,1 0 0 0 1,0M -3,3 Q 0,5 3,3',
    strokeColor: '#00F',
    rotation: 45
  };

  var symbolThree = {
    path: 'M -2,-2 2,2 M 2,-2 -2,2',
    strokeColor: '#292',
    strokeWeight: 4
  };

  // Create the polyline and add the symbols via the 'icons' property.
  var line = new google.maps.Polyline({
    path: [{lat: 22.291, lng: 153.027}, {lat: 18.291, lng: 153.027}],
    icons: [
      {
        icon: symbolOne,
        offset: '0%'
      }, {
        icon: symbolTwo,
        offset: '50%'
      }, {
        icon: symbolThree,
        offset: '100%'
      }
    ],
    map: map
  });

Exemplo

Animar um símbolo

Você pode animar um símbolo ao longo de um caminho usando a função window.setInterval() do DOM para mudar o deslocamento do símbolo em intervalos fixos.

TypeScript

// This example adds an animated symbol to a polyline.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: { lat: 20.291, lng: 153.027 },
      zoom: 6,
      mapTypeId: "terrain",
    }
  );

  // Define the symbol, using one of the predefined paths ('CIRCLE')
  // supplied by the Google Maps JavaScript API.
  const lineSymbol = {
    path: google.maps.SymbolPath.CIRCLE,
    scale: 8,
    strokeColor: "#393",
  };

  // Create the polyline and add the symbol to it via the 'icons' property.
  const line = new google.maps.Polyline({
    path: [
      { lat: 22.291, lng: 153.027 },
      { lat: 18.291, lng: 153.027 },
    ],
    icons: [
      {
        icon: lineSymbol,
        offset: "100%",
      },
    ],
    map: map,
  });

  animateCircle(line);
}

// Use the DOM setInterval() function to change the offset of the symbol
// at fixed intervals.
function animateCircle(line: google.maps.Polyline) {
  let count = 0;

  window.setInterval(() => {
    count = (count + 1) % 200;

    const icons = line.get("icons");

    icons[0].offset = count / 2 + "%";
    line.set("icons", icons);
  }, 20);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// This example adds an animated symbol to a polyline.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 20.291, lng: 153.027 },
    zoom: 6,
    mapTypeId: "terrain",
  });
  // Define the symbol, using one of the predefined paths ('CIRCLE')
  // supplied by the Google Maps JavaScript API.
  const lineSymbol = {
    path: google.maps.SymbolPath.CIRCLE,
    scale: 8,
    strokeColor: "#393",
  };
  // Create the polyline and add the symbol to it via the 'icons' property.
  const line = new google.maps.Polyline({
    path: [
      { lat: 22.291, lng: 153.027 },
      { lat: 18.291, lng: 153.027 },
    ],
    icons: [
      {
        icon: lineSymbol,
        offset: "100%",
      },
    ],
    map: map,
  });

  animateCircle(line);
}

// Use the DOM setInterval() function to change the offset of the symbol
// at fixed intervals.
function animateCircle(line) {
  let count = 0;

  window.setInterval(() => {
    count = (count + 1) % 200;

    const icons = line.get("icons");

    icons[0].offset = count / 2 + "%";
    line.set("icons", icons);
  }, 20);
}

window.initMap = initMap;
index.js
Exemplo

Testar amostra

JSFiddle.net (link em inglês) Google Cloud Shell