符號 (向量圖示)

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	一端開放且指向前方的箭頭。

在標記中新增符號

如要在標記上顯示向量圖示，請將 Symbol 物件常值與所需路徑傳遞至標記的 icon 屬性。以下範例會利用 SVG 路徑標記法建立標記的自訂圖示。

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;
index.ts

注意：請參閱這份指南，瞭解如何在 Google 地圖上使用 TypeScript。

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;
index.js

注意：JavaScript 是從 TypeScript 程式碼片段編譯而成。

查看範例

測試範例程式碼

JSFiddle.net Google Cloud Shell

標記支援使用光柵圖片和向量圖片，請參閱「自訂標記圖示」一文。

在折線中新增符號

如要在折線上顯示符號，請設定 PolylineOptions 物件的 icons[] 屬性。icons[] 陣列採用一或多個 IconSequence 物件常值，其中的屬性如下：

• icon (必要)：顯示在線條上的符號。
• offset：決定線條起點與圖示顯示位置之間的距離。這段距離可以使用線條長度的百分比 (例如「50%」) 或像素 (例如「50 像素」) 表示。預設值為「100%」。
• repeat：決定線條上連續圖示之間的距離。這段距離可以使用線條長度的百分比 (例如「50%」) 或像素 (例如「50 像素」) 表示。如要停止重複顯示圖示，請將這個屬性指定為「0」。預設值為「0」。

注意：如果折線是測地線 (亦即折線的 geodesic 屬性已設為 true)，系統預設會以公尺為單位計算指定的 offset 和 repeat 距離。如果將 offset 或 repeat 設為像素值，系統會以螢幕上的像素為單位計算距離。

此外，只要結合使用符號和 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;
index.ts

注意：請參閱這份指南，瞭解如何在 Google 地圖上使用 TypeScript。

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

注意：JavaScript 是從 TypeScript 程式碼片段編譯而成。

查看範例

測試範例程式碼

JSFiddle.net Google Cloud Shell