符号（基于矢量的图标）

  1. 简介
  2. 符号的属性
  3. 预定义符号
  4. 向标记添加符号
  5. 向多段线添加符号
  6. 以动画方式呈现符号

简介

Symbol 是一种基于矢量的图标，可显示在 Marker 或 Polyline 对象上。符号的形状是使用 SVG 路径表示法通过路径定义的。虽然 path 是唯一的必需属性，但 Symbol 对象支持多种属性，让您可以自定义视觉元素（例如，描边/填充的颜色和粗细）。请参阅属性列表。

一些预定义符号可通过 SymbolPath 类获得。请参见下表。

符号的属性

请注意，根据 Symbol 是显示在标记上还是多段线上，其默认行为会略有不同。下面的属性列表介绍了这些差异。

Symbol 支持以下属性：

  • path（必需）表示用于定义符号形状的路径。您可以使用 google.maps.SymbolPath 中的某个预定义路径，也可以使用 SVG 路径表示法自定义路径。注意：多段线上的矢量路径不得超出 22x22 像素的方形范围。如果您的路径包含的点超出此方形范围，那么您必须将符号的 scale 属性调整为小数值（例如 0.2），这样生成的调整后的点便位于该方形范围内。
  • anchor 设置符号相对于标记或多段线的位置。符号路径的坐标按锚点的 x 坐标和 y 坐标分别向左和向上平移。默认情况下，符号锚定在 (0, 0) 位置。位置使用与符号路径相同的坐标系表示。
  • fillColor 表示符号的填充（即用描边框住的区域）颜色。支持所有的 CSS3 颜色，扩展的具名颜色除外。对于标记上的符号，默认值为“black”。对于多段线上的符号，默认值为相应多段线的描边颜色。
  • fillOpacity 定义符号填充的相对不透明度（与透明度相反）。该值介于 0.0（完全透明）至 1.0（完全不透明）之间。默认值为 0.0。
  • rotation 表示符号的旋转角度，以顺时针度数表示。默认情况下，符号标记的旋转角度为 0，而多段线上的符号则按其所在边缘的角度旋转。设置多段线上符号的旋转角度会固定符号的旋转角度，这样符号就不会再依循线段的曲度。
  • scale 设置符号的大小缩放比例。对于符号标记，默认缩放比例为 1。缩放后的符号大小不受限制。对于多段线上的符号，默认缩放比例为多段线的描边粗细。经过缩放后，符号必须位于 22x22 像素的方形（以符号的锚点为中心）范围内。
  • strokeColor 表示符号的轮廓颜色。支持所有的 CSS3 颜色，扩展的具名颜色除外。对于标记上的符号，默认值为“black”。对于多段线上的符号，默认颜色为多段线的描边颜色。
  • strokeOpacity 用于确定符号描边的相对不透明度（与透明度相反）。该值介于 0.0（完全透明）至 1.0（完全不透明）之间。对于符号标记，默认值为 1.0。对于多段线上的符号，默认值为多段线的描边不透明度。
  • strokeWeight 定义符号轮廓的粗细。默认值为符号的 scale。

预定义符号

Maps JavaScript API 提供了一些内置符号，您可以通过 SymbolPath 类将这些符号添加到标记或多段线。

默认符号包括一个圆圈和两种类型的箭头（向前箭头和向后箭头）。这对于多段线尤为有用，因为多段线上符号的朝向是固定的。向前被视为朝向多段线终点的方向。

您可以利用任一默认符号选项修改预定义符号的描边或填充。

包含的预定义符号如下：

名称 说明 示例
google.maps.SymbolPath.CIRCLE 圆形。
google.maps.SymbolPath.BACKWARD_CLOSED_ARROW 四面封闭的向后箭头。
google.maps.SymbolPath.FORWARD_CLOSED_ARROW 四面封闭的向前箭头。
google.maps.SymbolPath.BACKWARD_OPEN_ARROW 一面开放的向后箭头。
google.maps.SymbolPath.FORWARD_OPEN_ARROW 一面开放的向前箭头。

向标记添加符号

如需在 AdvancedMarkerElement 上显示基于矢量的图标，请使用 SVG XML 元素。以下示例展示了如何将 SVG XML 元素附加到 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);

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

向多段线添加符号

若要在多段线上显示符号，请设置 PolylineOptions 对象的 icons[] 属性。icons[] 数组接受一个或多个包含以下属性的 IconSequence 对象字面量：

  • icon（必需）表示要渲染到线条上的符号。
  • offset 用于确定距线条起点（图标渲染位置）的距离。该距离可以线条长度百分比（例如“50%”）或像素（例如“50 像素”）表示。默认值为“100%”。
  • repeat 用于确定线条上连续图标的间距。该距离可以线条长度百分比（例如“50%”）或像素（例如“50 像素”）表示。若要停用图标重复，请指定“0”。默认值为“0”。

通过结合使用符号和 PolylineOptions 类，您可以从很多方面控制地图上多段线的外观和风格。下面列举了一些您可以应用的自定义设置。

箭头

使用 IconSequence.offset 属性向多段线的起点或终点添加箭头。

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

查看示例

虚线

将多段线的不透明度设置为 0，然后按固定间隔在线条上叠加不透明符号，即可实现虚线效果。

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

查看示例

自定义路径

您可以通过自定义符号向多段线添加多个不同的形状。

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

查看示例

以动画方式呈现符号

您可以使用 DOM 的 window.setInterval() 函数按固定间隔更改符号的偏移量，从而沿着某个路径以动画方式呈现符号。

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;
查看示例