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 AdvancedMarkerElement, use um elemento XML SVG. O exemplo a seguir mostra como anexar um elemento XML SVG a um AdvancedMarkerElement.

TypeScript

const parser = new DOMParser();

// A marker with a custom inline SVG.
const pinSvgString =
    '<svg xmlns="http://www.w3.org/2000/svg" width="56" height="56" viewBox="0 0 56 56" fill="none"><rect width="56" height="56" rx="28" fill="#7837FF"></rect><path d="M46.0675 22.1319L44.0601 22.7843" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M11.9402 33.2201L9.93262 33.8723" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M27.9999 47.0046V44.8933" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M27.9999 9V11.1113" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M39.1583 43.3597L37.9186 41.6532" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M16.8419 12.6442L18.0816 14.3506" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M9.93262 22.1319L11.9402 22.7843" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M46.0676 33.8724L44.0601 33.2201" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M39.1583 12.6442L37.9186 14.3506" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M16.8419 43.3597L18.0816 41.6532" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M28 39L26.8725 37.9904C24.9292 36.226 23.325 34.7026 22.06 33.4202C20.795 32.1378 19.7867 30.9918 19.035 29.9823C18.2833 28.9727 17.7562 28.0587 17.4537 27.2401C17.1512 26.4216 17 25.5939 17 24.7572C17 23.1201 17.5546 21.7513 18.6638 20.6508C19.7729 19.5502 21.1433 19 22.775 19C23.82 19 24.7871 19.2456 25.6762 19.7367C26.5654 20.2278 27.34 20.9372 28 21.8649C28.77 20.8827 29.5858 20.1596 30.4475 19.6958C31.3092 19.2319 32.235 19 33.225 19C34.8567 19 36.2271 19.5502 37.3362 20.6508C38.4454 21.7513 39 23.1201 39 24.7572C39 25.5939 38.8488 26.4216 38.5463 27.2401C38.2438 28.0587 37.7167 28.9727 36.965 29.9823C36.2133 30.9918 35.205 32.1378 33.94 33.4202C32.675 34.7026 31.0708 36.226 29.1275 37.9904L28 39Z" fill="#FF7878"></path></svg>';

const pinSvg = parser.parseFromString(
    pinSvgString,
    'image/svg+xml'
).documentElement;
const pinSvgMarker = new AdvancedMarkerElement({
    position: { lat: 37.42475, lng: -122.094 },
    title: 'A marker using a custom SVG image.',
    anchorLeft: '-50%',
    anchorTop: '-50%',
});
pinSvgMarker.append(pinSvg);
mapElement.append(pinSvgMarker);
index.ts

Observação:leia o guia sobre como usar o TypeScript e o Google Maps.

JavaScript

const parser = new DOMParser();

// A marker with a custom inline SVG.
const pinSvgString =
    '<svg xmlns="http://www.w3.org/2000/svg" width="56" height="56" viewBox="0 0 56 56" fill="none"><rect width="56" height="56" rx="28" fill="#7837FF"></rect><path d="M46.0675 22.1319L44.0601 22.7843" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M11.9402 33.2201L9.93262 33.8723" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M27.9999 47.0046V44.8933" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M27.9999 9V11.1113" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M39.1583 43.3597L37.9186 41.6532" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M16.8419 12.6442L18.0816 14.3506" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M9.93262 22.1319L11.9402 22.7843" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M46.0676 33.8724L44.0601 33.2201" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M39.1583 12.6442L37.9186 14.3506" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M16.8419 43.3597L18.0816 41.6532" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path><path d="M28 39L26.8725 37.9904C24.9292 36.226 23.325 34.7026 22.06 33.4202C20.795 32.1378 19.7867 30.9918 19.035 29.9823C18.2833 28.9727 17.7562 28.0587 17.4537 27.2401C17.1512 26.4216 17 25.5939 17 24.7572C17 23.1201 17.5546 21.7513 18.6638 20.6508C19.7729 19.5502 21.1433 19 22.775 19C23.82 19 24.7871 19.2456 25.6762 19.7367C26.5654 20.2278 27.34 20.9372 28 21.8649C28.77 20.8827 29.5858 20.1596 30.4475 19.6958C31.3092 19.2319 32.235 19 33.225 19C34.8567 19 36.2271 19.5502 37.3362 20.6508C38.4454 21.7513 39 23.1201 39 24.7572C39 25.5939 38.8488 26.4216 38.5463 27.2401C38.2438 28.0587 37.7167 28.9727 36.965 29.9823C36.2133 30.9918 35.205 32.1378 33.94 33.4202C32.675 34.7026 31.0708 36.226 29.1275 37.9904L28 39Z" fill="#FF7878"></path></svg>';

const pinSvg = parser.parseFromString(
    pinSvgString,
    'image/svg+xml'
).documentElement;
const pinSvgMarker = new AdvancedMarkerElement({
    position: { lat: 37.42475, lng: -122.094 },
    title: 'A marker using a custom SVG image.',
    anchorLeft: '-50%',
    anchorTop: '-50%',
});
pinSvgMarker.append(pinSvg);
mapElement.append(pinSvgMarker);
index.js

Os marcadores permitem usar imagens rasterizadas e vetoriais. Consulte Criar marcadores com imagens.

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".

Observação: se a polilinha for geodésica, ou seja, se a geodesic propriedade for definida como true, as distâncias especificadas para offset e repeat são calculadas em metros por padrão. Definir offset ou repeat em um valor em pixels faz com que as distâncias sejam calculadas em pixels na tela.

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

Observação:leia o guia sobre como usar o TypeScript e o Google Maps.

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

Observação:o JavaScript é compilado no snippet do TypeScript.

Exemplo