Símbolos (íconos basados en vectores)

1. Introducción
2. Propiedades de un símbolo
3. Símbolos predefinidos
4. Cómo agregar un símbolo a un marcador
5. Cómo agregar un símbolo a una polilínea
6. Cómo animar un símbolo

Introducción

Un Symbol es un ícono basado en vectores que se puede mostrar en un Marker o una Polyline. La forma del símbolo se define mediante una ruta que usa la notación de ruta SVG. Si bien path es la única propiedad obligatoria, el objeto Symbol admite varias propiedades que te permiten personalizar aspectos visuales, como el color y el grosor del trazo y el relleno. Consulta la lista de propiedades.

Hay varios símbolos predefinidos disponibles a través de la clase SymbolPath. Consulta la lista a continuación.

Propiedades de un símbolo

Ten en cuenta que el comportamiento predeterminado de un Symbol varía levemente según si aparece en un marcador o una polilínea. Estas variaciones se describen en la lista de propiedades a continuación.

Un Symbol admite las siguientes propiedades:

• path (obligatorio): Es la ruta que define la forma del símbolo. Puedes usar una de las rutas predefinidas en google.maps.SymbolPath o definir una ruta personalizada con la notación de ruta SVG. Nota: Las rutas vectoriales de una polilínea deben caber dentro de un cuadrado de 22 x 22 px. Si la ruta incluye puntos fuera de este cuadrado, debes ajustar la propiedad scale del símbolo a un valor fraccionario, como 0.2, para que los puntos a escala resultantes se adapten al cuadrado.
• anchor: Establece la posición del símbolo en relación con el marcador o la polilínea. Las coordenadas de la ruta del símbolo se convierten hacia la izquierda y arriba según las coordenadas X e Y del anclaje respectivamente. De forma predeterminada, los símbolos se anclan a (0, 0). La posición se expresa en el mismo sistema de coordenadas que la ruta del símbolo.
• fillColor: Es el color del relleno del símbolo (es decir, la región bordeada por el trazo). Se admiten todos los colores CSS3, salvo aquellos con nombres extendidos. En el caso de los símbolos de marcadores, el color predeterminado es negro. En el caso de los símbolos de polilíneas, el color predeterminado es el color del trazo de la polilínea correspondiente.
• fillOpacity: Define la opacidad relativa (es decir, la falta de transparencia) del relleno del símbolo. Los valores varían entre "0.0" (completamente transparente) y "1.0" (completamente opaco). El valor predeterminado es "0.0".
• rotation: Es el ángulo de rotación del símbolo, expresado en grados en el sentido de las manecillas del reloj. De forma predeterminada, el valor de rotación de un símbolo de marcador es "0" y un símbolo de polilínea rota conforme al ángulo del borde sobre el cual se encuentra. Si fijas la rotación de un símbolo de una polilínea, se corregirá su rotación de tal manera que dejará de guiarse por la curva de la línea.
• scale: Especifica la escala de tamaño que se aplica al símbolo. En el caso de los símbolos de marcadores, la escala predeterminada es 1. Después del escalamiento, el símbolo puede ser de cualquier tamaño. En el caso de los símbolos de una polilínea, la escala predeterminada equivale al grosor del trazo de la polilínea. Después del escalamiento, el símbolo debe caber dentro de un cuadrado de 22 x 22 px y quedar centrado en el anclaje correspondiente.
• strokeColor: Es el color del contorno del símbolo. Se admiten todos los colores CSS3, salvo aquellos con nombres extendidos. En el caso de los símbolos de marcadores, el color predeterminado es negro. En el caso de los símbolos de una polilínea, el color predeterminado equivale al color del trazo de la polilínea.
• strokeOpacity: Determina la opacidad relativa (es decir, la falta de transparencia) del trazo del símbolo. Los valores varían entre "0.0" (completamente transparente) y "1.0" (completamente opaco). En el caso de los símbolos de marcadores, el valor predeterminado es 1.0. En el caso de los símbolos de polilíneas, el valor predeterminado es la opacidad del trazo de la polilínea.
• strokeWeight: Define el grosor del contorno del símbolo. El valor predeterminado es la scale del símbolo.

Símbolos predefinidos

La API de Maps JavaScript proporciona algunos símbolos integrados que puedes agregar a marcadores o polilíneas a través de la clase SymbolPath.

Los símbolos predeterminados incluyen un círculo y dos tipos de flechas. Se encuentran disponibles las flechas que apuntan hacia delante y atrás. Esto resulta particularmente útil para las polilíneas, ya que la orientación de un símbolo de una polilínea es fija. Se considera que la orientación hacia delante apunta hacia el extremo final de la polilínea.

Puedes modificar el trazo o el relleno de los símbolos predefinidos usando cualquiera de las opciones de símbolos predeterminadas.

Se incluyen los siguientes símbolos predefinidos:

Nombre	Descripción	Ejemplo
google.maps.SymbolPath.CIRCLE	Un círculo
google.maps.SymbolPath.BACKWARD_CLOSED_ARROW	Una flecha que apunta hacia atrás y está totalmente cerrada
google.maps.SymbolPath.FORWARD_CLOSED_ARROW	Una flecha que apunta hacia delante y está totalmente cerrada
google.maps.SymbolPath.BACKWARD_OPEN_ARROW	Una flecha que apunta hacia atrás y tiene un lado abierto
google.maps.SymbolPath.FORWARD_OPEN_ARROW	Una flecha que apunta hacia delante y tiene un lado abierto

Cómo agregar un símbolo a un marcador

Para mostrar un ícono basado en vectores en un AdvancedMarkerElement, usa un elemento XML SVG. En el siguiente ejemplo, se muestra cómo agregar un elemento XML de SVG a un objeto 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

Nota: Consulta la guía sobre cómo utilizar TypeScript y 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

Los marcadores admiten el uso de imágenes vectoriales y de trama. Consulta Cómo crear marcadores con gráficos.

Cómo agregar un símbolo a una polilínea

Para mostrar símbolos en una polilínea, configura la propiedad icons[] del objeto PolylineOptions. El array icons[] toma uno o más literales del objeto IconSequence, con las siguientes propiedades:

• icon (obligatorio): Es el símbolo que se renderizará en la línea.
• offset: Determina la distancia desde el inicio de la línea en la que se renderizará un ícono. Esta distancia puede expresarse como un porcentaje de la longitud de la línea (por ejemplo, "50%") o en píxeles (por ejemplo, "50 px"). El valor predeterminado es "100%".
• repeat: Determina la distancia entre los íconos consecutivos de la línea. Esta distancia puede expresarse como un porcentaje de la longitud de la línea (por ejemplo, "50%") o en píxeles (por ejemplo, "50 px"). Para inhabilitar la repetición del ícono, establece el valor "0". El valor predeterminado es "0".

Nota: Si la polilínea es geodésica (es decir, si la propiedad geodesic se configuró en true), las distancias especificadas para offset y repeat se calculan en metros de forma predeterminada. Si configuras offset o repeat en un valor de píxel, las distancias se calcularán en píxeles en la pantalla.

Con una combinación de símbolos y la clase PolylineOptions, tienes mucho control sobre el aspecto de las polilíneas del mapa. A continuación, se incluyen ejemplos de personalizaciones que puedes aplicar.

Flechas

Usa la propiedad IconSequence.offset para agregar flechas al principio o al final de la polilínea.

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

Ver ejemplo

Líneas punteadas

Para lograr un efecto de línea punteada, configura la opacidad de tu polilínea en 0 y superpón un símbolo opaco sobre la línea a 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
});

Ver ejemplo

Rutas personalizadas

Los símbolos personalizados te permiten agregar muchas formas diferentes a una polilínea.

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

Ver ejemplo

Cómo animar un símbolo

Puedes animar un símbolo en una ruta mediante la función window.setInterval() del DOM para cambiar el desplazamiento del símbolo a intervalos fijos.

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

Nota: Consulta la guía sobre cómo utilizar TypeScript y 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

Nota: El código JavaScript se genera al compilar el fragmento de TypeScript.

Ver ejemplo