google map 標記事件

Ref : https://developers.google.com/maps/documentation/android-api/marker

標記

標記能指出地圖上的單一位置。 您可以透過變更預設色彩或以自訂影像取代標記圖示，以自訂您的標記。

資訊視窗可以提供標記的其他內容。

簡介

標記能指出地圖上的位置。 預設標記會使用標準圖示，並提供與 Google 地圖相同風格的感受。 您可以夠透過 API 來變更圖示的色彩、影像或錨定點。 標記是 Marker 類型的物件，並使用 GoogleMap.addMarker(markerOptions) 方法新增至地圖。

標記是以提供互動性為前提而設計的。 預設會接收click 事件，且通常會與帶出資訊視窗的事件接聽程式一起使用。將標記的 draggable 屬性設定為 true，可讓使用者變更標記的位置。使用長按可啟動移動標記的能力。

根據預設，當使用者輕按標記時，地圖工具列會出現在地圖右下方，讓使用者快速存取「Google 地圖」行動應用程式。您可以停用工具列。 如需詳細資訊，請參閱控制項指南。

開始使用標記

本集 Maps Live 涵蓋使用 Google Maps Android API 將標記新增至您地圖的基本概念。

新增標記

下列範例將示範如何將標記新增至地圖。 該標記建立在10,10 座標，而且按一下該標記將會出現一個顯示 'Hello world' 字串的資訊視窗。

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Hello world"));
}

將標記設定為可拖曳

只要標記的 draggable 屬性設定為 true，就可以在將標記新增至地圖之後，重新放置標記的位置。 長按標記，即可啟用拖曳功能。 當您的手指離開螢幕時，標記會繼續放在那個位置。

預設無法拖曳標記。 您必須使用 MarkerOptions.draggable(boolean) (在新增至地圖之前) 或Marker.setDraggable(boolean) (在新增至地圖之後)，將標記明確地設定為可拖曳。您可以針對標記接聽拖曳事件，如標記拖曳事件中所述。

下列片段會在澳洲柏斯新增可拖曳的標記。

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .draggable(true));

自訂標記

此影片顯示使用標記將地圖上的位置視覺化的方式。

標記會定義要取代預設圖示來顯示的自訂影像。 定義圖示涉及設定一些可以影響標記視覺行為的屬性。

標記支援透過下列屬性進行自訂：

位置 (必要)

表示標記在地圖上之位置的 LatLng 值。 這是Marker 物件唯一的必要屬性。

錨定點

影像上的點，要放在標記的 LatLng 位置。 這預設為影像底部的中間。

Alpha

設定標記的不透明度。 預設為 1.0。

標題

當使用者輕按標記時，顯示在資訊視窗中的字串。

片段

顯示在標題下方的其他文字。

圖示

取代預設標記影像而顯示的點陣圖。

可拖曳

如果要讓使用者移動標記，您可以設定為 true。 預設為 false。

可見

設定為 false，可讓標記不可見。 預設為 true。

扁平或佈告板方向

根據預設，標記會朝向螢幕且不會隨著相機旋轉或傾斜。 扁平標記會朝向地球表面且會隨著相機旋轉或傾斜。 兩種類型的標記都不會因為縮放而變更大小。 如果您想要有此效果，可以使用 GroundOverlays。

旋轉

標記的方向，以順時針旋轉的度數指定。 如果是扁平標記，預設位置會變更。 扁平標記的預設位置是對準北方。 當標記不是扁平時，預設位置是指向上方且會旋轉，使標記一直面對相機。

下列片段會建立一個有預設圖示的簡單標記。

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE));

自訂標記色彩

將 BitmapDescriptor 物件傳遞至 icon() 方法，即可自訂預設標記影像的色彩。 您可以使用BitmapDescriptorFactory 物件中的一組預先定義色彩，或使用 BitmapDescriptorFactory.defaultMarker(float hue) 方法設定自訂標記色彩。色調值介於 0 到 360 之間，以色彩轉輪上的點表示。

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));

自訂標記不透明度

您可以使用 MarkerOptions.alpha() 方法來控制標記的不透明度。 您應該將 Alpha 指定為介於 0.0 到 1.0 之間的浮點數，其中 0 代表完全透明，而 1 代表完全不透明。

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .alpha(0.7f));

自訂標記影像

您可以使用自訂標記影像 (通常稱為圖示) 取代預設標記影像。 自訂圖示一律會被設定為 BitmapDescriptor，並使用BitmapDescriptorFactory 類別中的四種方法之一來定義。

fromAsset(String assetName)

使用元素目錄中的影像建立自訂標記。

fromBitmap (Bitmap image)

從點陣圖影像建立自訂標記。

fromFile (String path)

從位於所指定路徑的檔案建立自訂圖示。

fromResource (int resourceId)

使用現有資源來建立自訂標記。

下列片段會建立一個有自訂圖示的標記。

  private static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
  private Marker melbourne = mMap.addMarker(new MarkerOptions()
                            .position(MELBOURNE)
                            .title("Melbourne")
                            .snippet("Population: 4,137,400")
                            .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

扁平化標記

標記圖示通常是參考螢幕繪製在相對位置；旋轉、傾斜或縮放地圖時，都不會變更標記的方向。您可以將標記的方向設定成扁平並與地球表面貼合。這種標記方向會隨著地圖一起旋轉，並會在地圖傾斜時變更視角。扁平標記的大小會在地圖縮放時維持不變。

如果要變更標記的方向，請將標記的 flat 屬性設定為 true。

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .flat(true));

旋轉標記

您可以使用 Marker.setRotation() 方法，以標記的錨定點為中心旋轉標記。 旋轉是從預設位置以順時針旋轉的角度測量。 當地圖上的是扁平標記時，預設位置是北方。 當標記不是扁平時，預設位置是指向上方且會旋轉，使標記一直面對相機。

下列範例會將標記旋轉 90°。 將錨定點設定為 0.5,0.5 會將標記的中央當成中心點旋轉，而不是以底部為中心。

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .anchor(0.5,0.5)
                          .rotation(90.0));

標記事件

Maps API 允許您接聽和回應標記事件。 如果要接聽這些事件，您必須在標記所屬的 GoogleMap 物件設定對應的接聽程式。當地圖上的其中一個標記發生事件時，就會以透過參數方式傳遞的對應 Marker 物件，呼叫接聽程式的回呼。如果要將此Marker 物件與您自己的 Marker 物件參考相比較，您必須使用 equals()，而不是 ==。

您可以接聽下列事件：

• 標記點擊事件
• 標記拖曳事件
• 資訊視窗點擊事件

標記點擊事件

您可以使用 OnMarkerClickListener 來接聽標記上的點擊事件。 如果要在地圖上設定此接聽程式，請呼叫GoogleMap.setOnMarkerClickListener(OnMarkerClickListener)。 當使用者按一下標記時，會呼叫onMarkerClick(Marker)，並會將標記傳遞為引數。此方法會傳回一個布林值，指出您是否已取用該事件 (意即，您想要抑制預設行為)。如果它傳回 false，除了您的自訂行為之外，還會發生預設行為。標記點擊事件的預設行為是要顯示其資訊視窗 (如有的話)，以及移動相機以將標記置中放在地圖上。

標記拖曳事件

您可以使用 OnMarkerDragListener 來接聽標記上的拖曳事件。 如果要在地圖上設定此接聽程式，請呼叫GoogleMap.setOnMarkerDragListener。 使用者必須長按標記，才能拖曳該標記。 當使用者的手指離開螢幕時，標記會繼續放在那個位置。 一開始拖曳標記時，會呼叫 onMarkerDragStart(Marker)。 正在拖曳標記時，會持續呼叫onMarkerDrag(Marker)。 當拖曳結束時，會呼叫 onMarkerDragEnd(Marker)。 您可以隨時透過呼叫Marker.getPosition() 以取得標記的位置。

注意：預設無法拖曳標記。 您必須明確地將標記設定為可拖曳，使用者才能拖曳標記。 使用MarkerOptions.draggable(boolean) (在新增至地圖之前) 或 Marker.setDraggable(boolean) (在新增至地圖之後)，就能完成此動作。