您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps Android API

為協助您開始,我們將先引導您使用 Google Developers Console 來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps Android API
  3. 建立適當的金鑰
繼續

標記

標記能指出地圖上的單一位置。 您可以透過變更預設色彩或以自訂影像取代標記圖示,以自訂您的標記。 資訊視窗可以提供標記的其他內容。

程式碼範例

GitHub 上的 ApiDemos 存放區包括示範各種標記功能的範例:

簡介

標記能指出地圖上的位置。 預設標記會使用標準圖示,並提供與 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"));
}

顯示標記的其他資訊

使用者輕按地圖上的標記時,常見的需求是顯示地點或位置的其他資訊。 請參閱資訊視窗指南。

將資料與標記關聯

您可以使用 Marker.setTag() 儲存帶標記的任意資料物件,以及使用 Marker.getTag() 來擷取資料物件,如以下程式碼範例所示:

/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends FragmentActivity implements
        OnMarkerClickListener,
        OnMapReadyCallback {

    private static final LatLng PERTH = new LatLng(-31.952854, 115.857342);
    private static final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
    private static final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

    private Marker mPerth;
    private Marker mSydney;
    private Marker mBrisbane;

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.marker_demo);

        SupportMapFragment mapFragment =
                (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /** Called when the map is ready. */
    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;

        // Add some markers to the map, and add a data object to each marker.
        mPerth = mMap.addMarker(new MarkerOptions()
                .position(PERTH)
                .title("Perth");
        mPerth.setTag(0);

        mSydney = mMap.addMarker(new MarkerOptions()
                .position(SYDNEY)
                .title("Sydney");
        mSydney.setTag(0);

        mBrisbane = mMap.addMarker(new MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane");
        mBrisbane.setTag(0);

        // Set a listener for marker click.
        mMap.setOnMarkerClickListener(this);
    }

    /** Called when the user clicks a marker. */
    @Override
    public boolean onMarkerClick(final Marker marker) {

        // Retrieve the data from the marker.
        Integer clickCount = (Integer) marker.getTag();

        // Check if a click count was set, then display the click count.
        if (clickCount != null) {
            clickCount = clickCount + 1;
            marker.setTag(clickCount);
            Toast.makeText(this,
                           marker.getTitle() +
                           " has been clicked " + clickCount + " times.",
                           Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false;
    }
}

以下範例是一些隨著標記儲存及擷取資料的實用情況:

  • 您的應用程式有不同的標記類型需求,而當使用者予以點擊時,您想要以不同的方式處理。 為達成此目的,您可以儲存帶指出類型的標記的 String

  • 您可以將帶有唯一記錄識別碼的系統用作介面,其中的標記代表該系統中的特定記錄。

  • 在決定標記的 Z 索引時,標記資料可指出要使用的優先順序。

將標記設定為可拖曳

只要標記的 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 fileName)
使用內部儲存空間中點陣圖影像檔案的名稱建立自訂圖示。
fromPath(String absolutePath)
從點陣圖影像的絕對檔案路徑建立自訂標記。
fromResource(int resourceId)
使用點陣圖影像的資源 ID 建立自訂標記。

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

  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));

標記 Z 索引

Z 索引指定此標記與地圖上其他標記相對的堆疊順序。 Z 索引較高的標記將繪製在 Z 索引較低的標記上方。 預設的 Z 索引值為 0

呼叫 MarkerOptions.zIndex() 以在標記的選項物件上設定 Z 索引,如下列程式碼片段所示:

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Marker z1")
        .zIndex(1.0f));
}

您可以呼叫 Marker.getZIndex() 以存取標記的 Z 索引,而且可以呼叫 Marker.setZIndex() 以變更它。

不論其他疊加層的 Z 索引為何,標記一律會繪製在地圖方塊圖層與其他非標記疊加層(地面疊加層、折線、多邊形與其他形狀)上方。

和其他疊加層相比,可以有效將標記視為位於個別的 Z 索引群組。

請參閱下面的點擊事件上的 Z 索引效果

處理標記事件

Maps API 允許您接聽和回應標記事件。 如果要接聽這些事件,您必須在標記所屬的 GoogleMap 物件設定對應的接聽程式。

當地圖上的其中一個標記發生事件時,就會以透過參數方式傳遞的對應 Marker 物件,呼叫接聽程式的回呼。

如果要將此Marker 物件與您自己的 Marker 物件參考相比較,您必須使用 equals(),而不是 ==

您可以接聽下列事件:

標記點擊事件

您可以使用 OnMarkerClickListener 來接聽標記上的點擊事件。 如果要在地圖上設定此接聽程式,請呼叫 GoogleMap.setOnMarkerClickListener(OnMarkerClickListener)。 當使用者按一下標記時,會呼叫 onMarkerClick(Marker),並會將標記傳遞為引數。

此方法會傳回一個布林值,指出您是否已取用該事件(意即,您想要抑制預設行為)。

如果它傳回 false,除了您的自訂行為之外,還會發生預設行為。 標記點擊事件的預設行為是要顯示其資訊視窗 (如有的話),以及移動相機以將標記置中放在地圖上。

點擊事件上的 Z 索引效果:

  • 當使用者按一下標記群集時,即會針對 Z 索引最高的標記觸發點擊事件。

  • 每個點擊最多只會觸發一個事件。 換句話說,點擊不會向下傳遞到具有較低 Z 索引值的標記或其他疊加層。

  • 按一下標記群集,即會在群集循環執行點擊,依序選取每個標記。 循環的順序會先按 Z 索引的優先順序處理,然後再處理點擊點附近。

  • 如果使用者點擊處不在該群集附近,API 會重新計算群集,並重設點擊循環的狀態,以便從頭開始。

  • 在重新開始循環之前,點擊事件會向下傳遞到標記群集中的其他形狀與疊加層。

  • 不論其他疊加層的 Z 索引為何,和其他疊加層或形狀相比,可有效將標記視為位於個別的 Z 索引群組(折線、多邊形、圓形和/或地面疊加層)。

若有多個標記、疊加層或形狀重疊在彼此上方,會先在標記群集中循環執行點擊事件,然後根據其 Z 索引值針對其他可點擊的疊加層或形狀觸發。

標記拖曳事件

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

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

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps Android API
Google Maps Android API
需要協助嗎?請前往我們的支援網頁