簡介
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;
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;
試用範例
在折線中新增符號
如要在折線上顯示符號，請設定 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;