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 marcador, pasa un literal del objeto Symbol con la ruta deseada a la propiedad icon del marcador. En el siguiente ejemplo, se usa la notación de ruta SVG a fin de crear un ícono personalizado para un 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;

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;
Ver ejemplo

Prueba la muestra

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

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 superpone 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;

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;
Ver ejemplo

Prueba la muestra