符號 (向量圖示)

  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 顏色，延伸的具名顏色除外。標記上符號的預設為「黑色」。折線上的符號則預設為相應折線的線條顏色。
  • fillOpacity：定義符號填色的相對不透明度 (與透明度相反)，以 0.0 (完全透明) 到 1.0 (完全不透明) 之間的數值表示。預設值為 0.0。
  • rotation：符號的順時針旋轉角度。標記上的符號預設旋轉角度為 0，而折線上的符號則是根據所在邊緣的角度而旋轉。設定折線上符號的旋轉角度可以固定符號的旋轉角度，讓符號不再隨著線條彎曲而旋轉。
  • scale：設定符號的尺寸縮放比例。標記上符號的預設縮放比例為 1。您可視需要將符號縮放成任何尺寸。折線上符號的預設縮放比例視折線的粗細而定。經過縮放後，符號必須位於 22x22 像素的正方形範圍內，且位於符號錨點的中心。
  • strokeColor：符號的外框顏色。系統支援所有 CSS3 顏色，延伸的具名顏色除外。標記上符號的預設為「黑色」。折線上的符號則預設為折線的線條顏色。
  • 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;
查看範例