Marker (legacy)

Marker 類別

google.maps.Marker class
extends MVCObject
library "marker"

已淘汰：google.maps.Marker 已於 2024 年 2 月 21 日淘汰。請改用「AdvancedMarkerElement」。目前 google.maps.Marker 沒有停用計畫，但建議使用 AdvancedMarkerElement，而非 google.maps.Marker。雖然 google.maps.Marker 會繼續修正重大迴歸錯誤，但不會解決現有錯誤。如要停止支援，我們會在 12 個月前發出通知。如要瞭解詳情，請參閱 https://developers.google.com/maps/deprecations；如需遷移指南，請前往 https://developers.google.com/maps/documentation/javascript/advanced-markers/migration。

const {Marker} = await google.maps.importLibrary("marker");

建構函式
Marker	Marker([opts]) 參數： opts：MarkerOptions optional 使用指定選項建立標記。如果指定地圖，標記會在建立時加入地圖。請注意，必須為標記設定要顯示的位置。

常數
MAX_ZINDEX	API 將會指派給標記的最大預設 Z 索引。您可以設定較高的 Z 索引，將標記置於最前方。

方法
getAnimation	getAnimation() 參數：無 傳回值： Animation|null|undefined 取得目前執行的動畫。
getClickable	getClickable() 參數：無 傳回值：如果標記可點選，則傳回 boolean True。 取得 Marker 的可點擊狀態。
getCursor	getCursor() 參數：無 傳回值： string|null|undefined 取得懸停時顯示的滑鼠游標類型。
getDraggable	getDraggable() 參數：無 傳回值：如果標記可拖曳，則傳回 boolean True。 取得 Marker 的可拖曳狀態。
getIcon	getIcon() 參數：無 傳回值： string|Icon|Symbol|null|undefined 取得 Marker 的圖示。查看《MarkerOptions.icon》。
getLabel	getLabel() 參數：無 傳回值： MarkerLabel|string|null|undefined 取得 Marker 的標籤。查看《MarkerOptions.label》。
getMap	getMap() 參數：無 傳回值： Map|StreetViewPanorama|null 取得 Marker 算繪的地圖或全景。
getOpacity	getOpacity() 參數：無 傳回值： number|null|undefined 介於 0.0 和 1.0 之間的數字。 取得Marker的不透明度。
getPosition	getPosition() 參數：無 傳回值： LatLng|null|undefined 取得 Marker 的位置。
getShape	getShape() 參數：無 傳回值： MarkerShape|null|undefined 取得用於互動的 Marker 形狀。請參閱《MarkerOptions.shape》和《MarkerShape》。
getTitle	getTitle() 參數：無 傳回值： string|null|undefined 取得「Marker」工具提示的標題。查看《MarkerOptions.title》。
getVisible	getVisible() 參數：無 傳回值： boolean 如果標記可見，則為 True。 取得 Marker 的瀏覽權限。
getZIndex	getZIndex() 參數：無 傳回值：標記的 number|null|undefined zIndex。 取得 Marker 的 zIndex。查看《MarkerOptions.zIndex》。
setAnimation	setAnimation([animation]) 參數： animation：Animation optional要播放的動畫。 傳回值：無 啟動動畫。所有正在進行的動畫都會取消。目前支援的動畫為：Animation.BOUNCE、Animation.DROP。傳入 null 會導致所有動畫停止。
setClickable	setClickable(flag) 參數： flag：boolean如果為 true，則可點選標記。 傳回值：無 設定 Marker 是否可點選。
setCursor	setCursor([cursor]) 參數： cursor：string optional 滑鼠游標類型。 傳回值：無 設定滑鼠游標懸停時顯示的類型。
setDraggable	setDraggable(flag) 參數： flag：boolean optional如果為 true，標記可以拖曳。 傳回值：無 設定 Marker 是否可拖曳。
setIcon	setIcon([icon]) 參數： icon：string|Icon|Symbol optional 傳回值：無 設定 Marker 的圖示。查看《MarkerOptions.icon》。
setLabel	setLabel([label]) 參數： label：string|MarkerLabel optional 標籤可以是字元字串或 MarkerLabel 物件。 傳回值：無 設定 Marker 的標籤。查看《MarkerOptions.label》。
setMap	setMap(map) 參數： map：Map|StreetViewPanorama optional 傳回值：無 在指定的地圖或全景上算繪 Marker。如果地圖設為 null，系統會移除標記。
setOpacity	setOpacity([opacity]) 參數： opacity：number optional 介於 0.0 (透明) 和 1.0 (不透明) 之間的數字。 傳回值：無 設定 Marker 的不透明度。
setOptions	setOptions(options) 參數： options：MarkerOptions optional 傳回值：無 設定 Marker 的選項。
setPosition	setPosition([latlng]) 參數： latlng：LatLng|LatLngLiteral optional 新位置。 傳回值：無 設定 Marker 的位置。
setShape	setShape([shape]) 參數： shape：MarkerShape optional 傳回值：無 設定用於互動的 Marker 形狀。請參閱《MarkerOptions.shape》和《MarkerShape》。
setTitle	setTitle([title]) 參數： title：string optional 傳回值：無 設定 Marker 工具提示的標題。查看《MarkerOptions.title》。
setVisible	setVisible(visible) 參數： visible：boolean如果為 true，標記就會顯示 傳回值：無 設定是否顯示 Marker。
setZIndex	setZIndex([zIndex]) 參數： zIndex：number optional 傳回值：無 設定 Marker 的 zIndex。查看《MarkerOptions.zIndex》。
繼承： addListener、bindTo、get、notify、set、setValues、unbind、unbindAll

事件
animation_changed	function() 引數：無 Marker 動畫屬性變更時，系統會觸發這個事件。
click	function(event) 引數： event：MapMouseEvent optional 使用者點選 Marker 圖示時，系統會觸發這個事件。
clickable_changed	function() 引數：無 Marker 可點擊屬性變更時，系統會觸發這個事件。
contextmenu	function(event) 引數： event：MapMouseEvent optional 在 Marker 上觸發 DOM contextmenu 事件時，就會觸發這個事件
cursor_changed	function() 引數：無 Marker 游標屬性變更時，就會觸發這個事件。
dblclick	function(event) 引數： event：MapMouseEvent optional 按兩下 Marker 圖示時，就會觸發這個事件。
drag	function(event) 引數： event：MapMouseEvent optional 使用者拖曳Marker時，系統會重複觸發這個事件。
dragend	function(event) 引數： event：MapMouseEvent optional 使用者停止拖曳 Marker 時，系統會觸發這個事件。
draggable_changed	function() 引數：無 Marker 可拖曳屬性變更時，就會觸發這個事件。
dragstart	function(event) 引數： event：MapMouseEvent optional 使用者開始拖曳 Marker 時，系統會觸發這個事件。
flat_changed	function() 引數：無 Marker 平面屬性變更時，系統會觸發這個事件。
icon_changed	function() 引數：無 Marker 圖示屬性變更時，系統會觸發這個事件。
mousedown	function(event) 引數： event：MapMouseEvent optional 在 Marker 上按下時，系統會觸發這個事件。
mouseout	function(event) 引數： event：MapMouseEvent optional 滑鼠離開 Marker 圖示區域時，就會觸發這個事件。
mouseover	function(event) 引數： event：MapMouseEvent optional 滑鼠進入 Marker 圖示區域時，就會觸發這個事件。
mouseup	function(event) 引數： event：MapMouseEvent optional 在 Marker 上放開滑鼠按鈕時，系統會觸發這個事件。
position_changed	function() 引數：無 Marker 位置屬性變更時，系統會觸發這個事件。
shape_changed	function() 引數：無 Marker 形狀屬性變更時，會觸發這個事件。
title_changed	function() 引數：無 Marker 標題屬性變更時，系統會觸發這個事件。
visible_changed	function() 引數：無 當 Marker 可見屬性變更時，系統會觸發這個事件。
zindex_changed	function() 引數：無 Marker zIndex 屬性變更時，就會觸發這個事件。
rightclick	已淘汰：請改用 Marker.contextmenu 事件，以支援 macOS 上的 Control 鍵 + 點擊等使用模式。 function(event) 引數： event：MapMouseEvent optional 在 Marker 上按一下滑鼠右鍵時，會觸發這個事件。

MarkerOptions 介面

google.maps.MarkerOptions 介面

已淘汰：google.maps.Marker 已於 2024 年 2 月 21 日淘汰。請改用 google.maps.marker.AdvancedMarkerElement。如要瞭解淘汰相關詳情，請參閱 https://developers.google.com/maps/deprecations；如需遷移指南，請參閱 https://developers.google.com/maps/documentation/javascript/advanced-markers/migration。

MarkerOptions 物件，用於定義可在 Marker 上設定的屬性。

屬性
anchorPoint 選填	類型： Point optional 從標記位置到 InfoWindow 尖端的偏移量，該 InfoWindow 已以標記為錨點開啟。
animation 選填	類型： Animation optional 預設值： null 在地圖中新增標記時所要播放的動畫。
clickable 選填	類型： boolean optional 預設值： true 如果為 true，標記就會接收滑鼠和觸控事件。
collisionBehavior 選填	已淘汰： collisionBehavior 已於 2023 年 7 月淘汰。改用 AdvancedMarkerElement.collisionBehavior。 注意：僅適用於 v=beta 版。 類型： string|CollisionBehavior optional 預設值： null 設定向量地圖上標記的衝突行為。
crossOnDrag 選填	類型： boolean optional 預設值： true 如果設為 false，則拖曳時標記下方不會顯示十字。
cursor 選填	類型： string optional 預設值： pointer 懸停時要顯示的滑鼠游標類型。
draggable 選填	類型： boolean optional 預設值： false 如果為 true，則可拖曳標記。注意：如果將這項屬性設為 true，即使 clickable 設為 false，標記仍可點選。
icon 選填	類型： string|Icon|Symbol optional 前景圖示。如果提供字串，系統會將其視為 Icon，並將字串視為 url。
label 選填	類型： string|MarkerLabel optional 預設值： null 為標記新增標籤。標記標籤是顯示在標記內的字母或數字。標籤可以是字串或 MarkerLabel 物件。如果提供此屬性，但未提供 MarkerOptions.title，系統會使用提供的標籤文字，為標記新增無障礙文字 (例如供螢幕閱讀器使用)。請注意，label 目前僅用於未最佳化標記的無障礙文字。
map 選填	類型： Map|StreetViewPanorama optional 要顯示標記的地圖。地圖是顯示標記的必要元素，如果在建構標記時未提供，則可透過 Marker.setMap 提供。
opacity 選填	類型： number optional 預設值：1.0 介於 0.0 (透明) 和 1.0 (不透明) 之間的數字。
optimized 選填	類型： boolean optional 您可進行最佳化處理來將多個標記算繪為單一靜態元素，藉此提升效能。這個做法在需要使用大量標記時相當實用。進一步瞭解標記最佳化。注意：這項最佳化作業不會影響向量地圖上的標記。
position 選填	類型： LatLng|LatLngLiteral optional 設定標記位置。標記可以先建構，但必須提供位置資訊 (例如透過使用者動作或選擇) 才會顯示。如果建立標記時未提供標記位置，可以使用 Marker.setPosition 提供。
shape 選填	類型： MarkerShape optional 用於拖曳/點擊的圖片地圖區域定義。
title 選填	類型： string optional 預設值： undefined 滑鼠游標懸停效果文字。如果提供無障礙文字 (例如與螢幕閱讀器搭配使用)，系統會將該文字新增至標記，並提供相應的值。請注意，title 目前僅用於未最佳化標記的無障礙文字。
visible 選填	類型： boolean optional 預設值： true 如果為 true，則會顯示標記。
zIndex 選填	類型： number optional 所有標記都會依其 zIndex 順序顯示，較大的標記值會顯示在值較小的標記值之前。根據預設，標記會依據其在畫面上的垂直位置顯示，而較小的標記將會顯示在畫面上方的標記之前。

CollisionBehavior 常數

google.maps.CollisionBehavior constants
程式庫"marker"

這些常數也可以做為字串使用。在 TypeScript 中，字串常值是由 CollisionBehaviorString 類型定義。

const {CollisionBehavior} = await google.maps.importLibrary("marker");

常數
OPTIONAL_AND_HIDES_LOWER_PRIORITY	標記只會在沒有重疊情況時顯示。如果這個類型的兩個標記重疊，系統會顯示 zIndex 較高的標記。如果兩者的 zIndex 相同，系統會顯示直向畫面位置較低的標記。
REQUIRED	無論是哪種衝突，一律顯示標記。此為預設行為。
REQUIRED_AND_HIDES_OPTIONAL	無論是哪種衝突，一律顯示標記，並隱藏與標記重疊的任何 OPTIONAL_AND_HIDES_LOWER_PRIORITY 標記或標籤。

Icon 介面

google.maps.Icon 介面

代表標記圖示圖片的結構。

屬性
url	類型： string 圖片或綜合連續圖片的網址。
anchor 選填	類型： Point optional 圖片錨定位置，對應標記在地圖上的位置。錨點的預設位置在圖片下方的中心點。
labelOrigin 選填	類型： Point optional 標籤的原點 (相對於圖示圖片左上角)，如果標記有提供標籤。根據預設，原點位於圖片的中心點。
origin 選填	類型： Point optional 綜合圖片內圖片的位置 (如果有)。根據預設，原點位於圖片 (0, 0) 的左上角。
scaledSize 選填	類型： Size optional 縮放之後整個圖片的大小 (如果有)。您可以使用此屬性拉伸/縮短圖片或綜合圖片。
size 選填	類型： Size optional 綜合圖片或圖片的顯示大小。使用綜合圖片時，您必須指定綜合圖片的大小。如未提供大小，系統會在載入圖片時加以設定。

MarkerLabel 介面

google.maps.MarkerLabel 介面

這些選項會指定標記標籤的外觀。標記標籤是顯示在標記內的字串 (通常是單一字元)。如果搭配自訂標記使用，可以透過 Icon 類別中的 labelOrigin 屬性調整位置。

屬性
text	類型： string 標籤中顯示的文字。
className 選填	類型： string optional 預設值： '' (空字串) 標籤元素的 className 屬性 (等同於元素的 class 屬性)。您可以新增多個 CSS 類別，並以空格分隔。字型顏色、大小、粗細和系列只能透過 MarkerLabel 的其他屬性設定。如果同時使用標記衝突管理，請勿使用 CSS 類別變更標籤的位置或方向 (例如使用平移和旋轉)。
color 選填	類型： string optional 預設值： 'black' 標籤文字的顏色。
fontFamily 選填	類型： string optional 標籤文字的字型系列 (相當於 CSS font-family 屬性)。
fontSize 選填	類型： string optional 預設值： '14px' 標籤文字的字型大小 (相當於 CSS font-size 屬性)。
fontWeight 選填	類型： string optional 標籤文字的字型粗細 (相當於 CSS font-weight 屬性)。

MarkerShape 介面

google.maps.MarkerShape 介面

這個物件會定義標記圖片的可點擊區域。形狀由 type 和 coord 兩個屬性組成，用於定義圖片的非透明區域。

屬性
type	類型： string 說明形狀類型，可以是 circle、poly 或 rect。
coords 選填	類型： Array<number> optional 這項屬性的格式取決於 type 的值，並遵循 w3 AREA coords 規格，詳情請參閱 http://www.w3.org/TR/REC-html40/struct/objects.html#adef-coords。 coords 屬性是整數陣列，用於指定形狀相對於目標圖片左上角的像素位置。座標取決於 type 的值，如下所示：   - circle：coords 為 [x1,y1,r]，其中 x1、y2 是圓心座標，r 是圓半徑。   - poly：coords 為 [x1,y1,x2,y2...xn,yn]，其中每個 x,y 組合包含多邊形一個頂點的座標。   - rect：coords 為 [x1,y1,x2,y2]，其中 x1、y1 是矩形左上角的座標，x2、y2 是矩形右下角的座標。

Symbol 介面

google.maps.Symbol 介面

描述符號，由具有樣式的向量路徑組成。符號可用做標記的圖示，或放在折線上。

屬性
path	類型： SymbolPath|string 符號的路徑，可以是內建符號路徑，也可以是使用 SVG 路徑標記法表示的自訂路徑。必填。
anchor 選填	類型： Point optional 預設值： google.maps.Point(0,0) 相對於標記或折線的符號位置。符號的路徑座標會分別根據錨點的 x 和 y 座標轉譯成左方和上方的位置。位置使用與符號路徑相同的座標系統表示。
fillColor 選填	類型： string optional 符號的填滿顏色。系統支援所有 CSS3 色彩 (延伸的具名色彩除外)。標記上符號的預設為「黑色」。折線上的符號則預設為相應折線的線條顏色。
fillOpacity 選填	類型： number optional 預設值： 0 符號的填色不透明度。
labelOrigin 選填	類型： Point optional 預設值： google.maps.Point(0,0) 標籤的原點 (相對於路徑的原點)，如果標籤是由標記提供。原點使用與符號路徑相同的座標系統表示。折線上的符號不使用這項屬性。
rotation 選填	類型： number optional 預設值： 0 符號的順時針旋轉角度。IconSequence 中的符號 (其中 fixedRotation 為 false) 會根據所在邊緣的角度而旋轉。
scale 選填	類型： number optional 符號的尺寸縮放比例。符號標記的預設值為 1，縮放後可為任何大小。折線上符號的預設縮放比例視折線的粗細而定。經過縮放後，符號必須位於 22 像素的正方形範圍內，且位於符號錨點的中心。
strokeColor 選填	類型： string optional 符號的筆劃顏色。系統支援所有 CSS3 色彩 (延伸的具名色彩除外)。標記上符號的預設為「黑色」。折線上的符號則預設為折線的線條顏色。
strokeOpacity 選填	類型： number optional 符號的筆劃不透明度。標記上符號的預設縮放比例為 1。折線上的符號則預設為折線的線條不透明度。
strokeWeight 選填	類型： number optional 預設：符號的 Symbol.scale。 符號的外框粗細。

SymbolPath 常數

google.maps.SymbolPath constants
程式庫"core"

內建符號路徑。

const {SymbolPath} = await google.maps.importLibrary("core");

常數
BACKWARD_CLOSED_ARROW	指向後方的封閉箭頭。
BACKWARD_OPEN_ARROW	指向後方的開放式箭頭。
CIRCLE	圓形。
FORWARD_CLOSED_ARROW	指向前方的封閉箭頭。
FORWARD_OPEN_ARROW	指向前方的開放式箭頭。

Animation 常數

google.maps.Animation constants
程式庫"marker"

可在標記上播放的動畫。使用 Marker 的 Marker.setAnimation 方法或 MarkerOptions.animation 選項，即可播放動畫。

const {Animation} = await google.maps.importLibrary("marker");

常數
BOUNCE	標記會持續彈跳，直到呼叫 Marker.setAnimation 並傳入 null 停止動畫為止。
DROP	標記會從地圖頂端落到最終位置。當標記停止時，動畫會隨之停止，且 Marker.getAnimation 會傳回 null。這類動畫通常是在建立標記時指定。