Google Map API 入門教學（二）：在 Map 上加入標記

要在 Google Map 上加入標記，需要利用的是 google.maps.Marker 這個物件。
延續 Google Map API 入門教學（一）的例子，可以將 JavaScript 加上以下的語法：

google.maps.event.addListener(currentMap, "click", function(event) {
　　// Setting of marker
　　var optionOfMarker = {
　　　　position: event.latLng,
　　　　map: currentMap,
　　　　title: event.latLng.toString()
　　};

　　// Show marker in the place of mouse clicks
　　mapMarker = new google.maps.Marker(optionOfMarker);
});

一開始先在 currentMap 這個 map 物件上綁上 click 事件
然後設定標記的相關屬性之後，產生該標記就可以讓標記在地圖上出現了。
屬性說明如下：

• position：標記要放的位置，必須是一個 google.maps.LatLng 的物件。這裡因為要在使用者點擊的位置放標記，所以要讀取 click 事件傳進來的 event 物件中帶的 LatLng 位置。
• map：標記所屬的 Google Map 物件。
• title：滑鼠停留在標記上時要出現的泡泡內容。這裡是直接顯示使用者點擊的位置的座標。

以上的程式碼加進去以後就可以讓使用者在地圖上一直點，標記就會一直出現。
如果只讓標記出現一個的話，可以在 click 事件觸發時先檢查標記的變數是否存在，如果存在的話就把標記從地圖上移除。

// Clear marker if it already exists
if (mapMarker) mapMarker.setMap(null);

至於為什麼移除標記要用 setMap(null) 呢？原因可以直接參照 Google Map API 文件 [1] 的說明：

如要從地圖上移除疊加層，請呼叫疊加層的 setMap() 方法傳送 null。請注意，呼叫此方法不會刪除疊加層；只是從地圖上移除此疊加層。如果您希望刪除疊加層，應該從地圖上將其移除，然後將疊加層本身設定為 null。

如果您希望管理一組疊加層，應該建立陣列來存放疊加層。使用此陣列時，如果需要移除疊加層，您就可以在陣列的各個疊加層上呼叫 setMap()。(請注意，第 3 版與第 2 版不同，不提供 clearOverlays() 方法；您需自行負責追蹤疊加層並在不需要時從地圖上移除)。從地圖上移除疊加層並將陣列的 length 設為 0 即可刪除疊加層，這樣做會移除疊加層的所有參照。

如果需要刪除地圖註冊的事件時，可以使用 clearListeners 函式去移除事件。

google.maps.event.clearListeners(currentMap, "click");

另外 Google Map API 原生支援了兩種標記的動畫：

• BOUNCE：標記會在地圖的指定座標處不斷跳動。
• DROP：產生標記時，標記會從地圖上方掉下來。

使用方法如下：

mapMarker.setAnimation(google.maps.Animation.BOUNCE);

把上面提到的全部加上去做成完整的 JavaScript 的話，可以寫成下面的範例：

var currentMap;
var mapMarker;

$(function(){
　　initialize();
});

function initialize() {
　　var latlng = new google.maps.LatLng(-34.397, 150.644);
　　var myOptions = {
　　　　zoom: 11,
　　　　center: latlng,
　　　　mapTypeId: google.maps.MapTypeId.HYBRID
　　};
　　currentMap = new google.maps.Map(document.getElementById("map_canvas"), myOptions);

　　// Clear all the click event of the map
　　google.maps.event.clearListeners(currentMap, "click");
　　// Register a click event to the map
　　google.maps.event.addListener(currentMap, "click", function(event) {
　　　　// Clear marker if it already exists
　　　　if (mapMarker) mapMarker.setMap(null);

　　　　// Setting of marker
　　　　var optionOfMarker = {
　　　　　　position: event.latLng,
　　　　　　map: currentMap,
　　　　　　title: event.latLng.toString()
　　　　};

　　　　// Show marker in the place of mouse clicks
　　　　mapMarker = new google.maps.Marker(optionOfMarker);
　　　　mapMarker.setAnimation(google.maps.Animation.DROP);
　　});
}

HTML 的部份則請直接參閱 Google Map API 入門教學（一）中的 index.html 的範例。

參考資料：
1、Google Maps Javascript API 第 3 版疊加層
2、Google Maps Javascript API V3 Reference