您已全部設定完成!

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

啟用 Google Maps Android API

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

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

形狀

Google Maps API for Android 提供一些簡單方法,可讓您將形狀加入地圖,來為您的應用程式自訂。

  • Polyline 是一連串相連的線段,可形成任意形狀並能用來在地圖上標記路徑與路線。

  • Polygon 是一個圍出的形狀,可用來在地圖上標記區域。

  • Circle 是在地圖上依地理位置準確投射繪製成圓形的地球表面。

對於所有這些形狀,您可以透過更改數個屬性來自訂形狀的外觀。

程式碼範例

GitHub 上的 ApiDemos 存放區包括示範形狀用法與其功能的範例:

折線

Polyline 類別定義地圖上一組相連的線段。 Polyline 物件包含一組 LatLng 位置,且會依排序連接那些位置建立一連串線段。

此影片可讓您了解要如何使用折線在地圖上繪製路徑,協助您的使用者前往想去的地點。

如果要建立折線,請先建立 PolylineOptions 物件,再加入數個點。 每個點都代表地球表面上的某地點,且會以 LatLng 物件表示。 線段是根據您加入 PolylineOptions 物件的順序在各點之間繪製而成。

如果要將點新增到 PolylineOptions 物件,請呼叫 PolylineOptions.add()。 請注意,這種方法需要數目不一的參數,如此您才能一次加入多個點(如果點已在清單中,您也可以呼叫 PolylineOptions.addAll(Iterable<LatLng>))。

您接下來可以透過呼叫 GoogleMap.addPolyline(PolylineOptions),以將折線加到地圖。 此方法會傳回 Polyline 物件,您可以在稍後用來更改折線。

下列程式碼片段示範如何將矩形新增至地圖:

// Instantiates a new Polyline object and adds points to define a rectangle
PolylineOptions rectOptions = new PolylineOptions()
        .add(new LatLng(37.35, -122.0))
        .add(new LatLng(37.45, -122.0))  // North of the previous point, but at the same longitude
        .add(new LatLng(37.45, -122.2))  // Same latitude, and 30km to the west
        .add(new LatLng(37.35, -122.2))  // Same longitude, and 16km to the south
        .add(new LatLng(37.35, -122.0)); // Closes the polyline.

// Get back the mutable Polyline
Polyline polyline = myMap.addPolyline(rectOptions);

如果要在新增後更改折線的形狀,您可以呼叫 Polyline.setPoints() 並提供折線各點的新清單。

您可以在新增至地圖之前和之後,自訂折線外觀。 如需進一步的詳細資訊,請參閱下方的自訂外觀一節。

折線事件

在預設情況下,折線不可點擊。 您可以透過呼叫 Polyline.setClickable(boolean),以啟用及停用可點擊性。

請使用 OnPolylineClickListener 在可點擊的折線上接聽點擊事件。 如果要在地圖上設定此接聽程式,請呼叫 GoogleMap.setOnPolylineClickListener(OnPolylineClickListener)

當使用者點擊折線時,您將會接收到 onPolylineClick(Polyline) 回呼。

多邊形

Polygon 物件類似於 Polyline 物件,包含一連串排序的座標。

然而,多邊形並不具備開放性的特色,而是設計來定義閉合迴圈內的填滿區域。

您可以使用與新增 Polyline 相同的方式,將 Polygon 新增至地圖。 先建立 PolygonOptions 物件,再加入幾個點。 這些點將會形成多邊形的輪廓。 接著,您可以透過呼叫 GoogleMap.addPolygon(PolygonOptions) (將會傳回 Polygon 物件),以將多邊形新增至地圖。

下列程式碼片段會將矩形新增至地圖(請注意,由於我們尚未定義填滿色彩,因此預設填滿色彩是透明,這和上一節片段中的折線完全相同):

// Instantiates a new Polygon object and adds points to define a rectangle
PolygonOptions rectOptions = new PolygonOptions()
              .add(new LatLng(37.35, -122.0),
                   new LatLng(37.45, -122.0),
                   new LatLng(37.45, -122.2),
                   new LatLng(37.35, -122.2),
                   new LatLng(37.35, -122.0));

// Get back the mutable Polygon
Polygon polygon = myMap.addPolygon(rectOptions);

如果要在新增後更改多邊形的形狀,您可以呼叫 Polygon.setPoints() 並提供多邊形輪廓各點的新清單。

您可以在新增多邊形至地圖之前和之後,自訂多邊形外觀。 如需進一步的詳細資訊,請參閱下方的自訂外觀一節。

多邊形自動完成

上述範例中的多邊形包含五個座標,但請注意第一個座標會與最後一個座標位在相同位置,這會定義迴圈。

然而,在實務上,由於多邊形會定義閉合區域,因此您不需要定義最後一個座標。 如果最後一個座標與第一個座標不同,API 會將第一個座標附加到座標序列的結尾,以自動「閉合」多邊形。

下面兩個多邊形相等,為每個多邊形呼叫 polygon.getPoints() 將傳回全部 4 點。

Polygon polygon = map.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(0, 0))
        .strokeColor(Color.RED)
        .fillColor(Color.BLUE));

Polygon polygon = map.addPolygon(new PolygonOptions()
         .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5))
         .strokeColor(Color.RED)
         .fillColor(Color.BLUE));

建立中空多邊形

您可以在單一 Polygon 物件中合併多個路徑來建立複雜的形狀,例如填滿的環形或「甜甜圈」(在多邊形內顯示為「群島」的多邊形區域)。

複雜的形狀總是由多個較簡單的路徑組成。

兩個路徑都必須在相同的區域中定義。 兩個區域當中較大的那個會定義填滿區域,且是沒有其他選項的簡單多邊形。

接著,將第二個路徑傳遞到 addHole() 方法。 當較大的路徑可完全圍住第二個較小的路徑時,看起來就像是有部分多邊形被移除。

如果孔洞與多邊形輪廓相交,將會轉譯多邊形,但不會予以填滿。

以下片段將會建立一個當中有較小矩形孔洞的矩形。

mMap.addPolygon(new PolygonOptions()
        .add(new LatLng(0, 0), new LatLng(0, 5), new LatLng(3, 5), new LatLng(3, 0), new LatLng(0, 0))
        .addHole(new LatLng(1, 1), new LatLng(1, 2), new LatLng(2, 2), new LatLng(2, 1), new LatLng(1, 1))
        .fillColor(Color.BLUE));

多邊形事件

在預設情況下,多邊形不可點擊。 您可以透過呼叫 Polygon.setClickable(boolean),以啟用及停用可點擊性。

請使用 OnPolygonClickListener 在可點擊的多邊形上接聽點擊事件。 如果要在地圖上設定此接聽程式,請呼叫 GoogleMap.setOnPolygonClickListener(OnPolygonClickListener)

當使用者點擊多邊形時,您將會接收到 onPolygonClick(Polygon) 回呼。

圓形

除了一般 Polygon 類別之外,Maps API 也包括適用於 Circle 物件的特定類別以簡化建構。

如果要建構圓形,您必須指定下列兩個屬性:

  • center (以 LatLng 表示)。
  • radius (以公尺表示)。

接著,地球表面上與指定的 center 距離 radius 公尺遠的所有點集合,將會定義出一個圓形。 由於 Maps API 所使用的麥卡托投影法在平面上轉譯球體的方式,當位置靠近赤道時,在地圖上會顯示為接近正圓的形狀,而當位置距離赤道越遠時,顯示的圓形(在畫面上)會漸漸變得不圓。

下列程式碼片段會透過建構 CircleOptions 物件並呼叫 GoogleMap.addCircle(CircleOptions),以將圓形新增至地圖:

// Instantiates a new CircleOptions object and defines the center and radius
CircleOptions circleOptions = new CircleOptions()
    .center(new LatLng(37.4, -122.1))
    .radius(1000)); // In meters

// Get back the mutable Circle
Circle circle = myMap.addCircle(circleOptions);

如果要在新增後更改圓形的形狀,您可以呼叫 Circle.setRadius()Circle.setCenter() 並提供新的值。

您可以在新增圓形至地圖之前和之後,自訂圓形外觀。 如需進一步的詳細資訊,請參閱下方的自訂外觀一節。

圓形事件

在預設情況下,圓形不可點擊。 您可以透過呼叫 GoogleMap.addCircle() 搭配 CircleOptions.clickable(boolean) 或呼叫 Circle.setClickable(boolean),以啟用及停用可點擊性。

請使用 OnCircleClickListener 在可點擊的圓形上接聽點擊事件。 如果要在地圖上設定此接聽程式,請呼叫 GoogleMap.setOnCircleClickListener(OnCircleClickListener)

當使用者點擊圓形時,您將會接收到 onCircleClick(Circle) 回呼,如下列程式碼範例所示:

public class MyActivity extends FragmentActivity
        implements OnMapReadyCallback {

        private GoogleMap mMap;
        private Circle circle;

        @Override
        public void onMapReady(GoogleMap map) {
            mMap = map;

            circle = mMap.addCircle(new CircleOptions()
                .center(new LatLng(37.4, -122.1))
                .radius(1000)
                .strokeWidth(10)
                .strokeColor(Color.GREEN)
                .fillColor(Color.argb(128, 255, 0, 0))
                .clickable(true);

            map.setOnCircleClickListener(new OnCircleClickListener() {

                @Override
                public void onCircleClick(Circle circle) {
                    // Flip the r, g and b components of the circle's
                    // stroke color.
                    int strokeColor = circle.getStrokeColor() ^ 0x00ffffff;
                    circle.setStrokeColor(strokeColor);
                }
            });
        }
}

自訂外觀

您可以在新增至地圖之前(透過在選項物件上指定所需的屬性)和之後,更改形狀的外觀。

同時對所有屬性公開 Getter,讓您輕鬆存取形狀的目前狀態。

下列片段會利用從墨爾本前往柏斯的測地區段新增粗的藍色折線。 以下各節會更詳細說明這些屬性。

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

注意: 雖然這些有大部分都可以套用到描述的任何形狀,但有些屬性對於特定形狀可能沒有意義(例如,折線不會有填滿色彩,因為折線並沒有內部)。

筆觸色彩

筆觸色彩是 32 位元 ARGB (alpha-red-green-blue) 整數,指定形狀筆觸色彩的不透明度與色彩。 透過呼叫 *Options.strokeColor() (或為折線時,可呼叫 PolylineOptions.color()),可以在形狀的選項物件上設定此屬性。

如果未指定,預設的筆觸色彩是黑色 (Color.BLACK)。

在將形狀新增至地圖之後,透過呼叫 getStrokeColor() (如果是折線,則為 getColor())就能存取筆觸色彩,且透過呼叫 setStrokeColor() (setColor() for a polyline) 就能夠變更。

填滿色彩

填滿色彩只適用於多邊形與圓形。 它不適用於折線,因為折線沒有以定義的內部。 對於多邊形,孔洞內的區域並不屬於多邊形內部,如果設定填滿色彩,亦不會填上色彩。

填滿色彩是 32 位元 ARGB (alpha-red-green-blue) 整數,指定形狀內部色彩的不透明度與色彩。 透過呼叫 *Options.fillColor(),可以在形狀的選項物件上設定此屬性。 如果未指定,預設的筆觸色彩是透明 (Color.TRANSPARENT)。

在將形狀新增至地圖之後,透過呼叫 getFillColor()就能存取填滿色彩,且透過呼叫 setFillColor() 就能夠變更。

筆觸寬度

折線筆觸寬度,以浮點數表示,單位為像素 (px)。 地圖縮放時,寬度並不會隨之調整(也就是說,不論哪個縮放層級,形狀都會有相同的筆觸寬度)。 透過呼叫 *Options.strokeWidth() (如果是折線,則為 PolylineOptions.width()),可以在形狀的選項物件上設定此屬性。

如果未指定,預設的筆觸寬度是 10 像素。

在將形狀新增至地圖之後,透過呼叫 getStrokeWidth() (如果是折線,則為 getWidth())就能存取筆觸寬度,且呼叫 setStrokeWidth() (setWidth() for a polyline) 就能夠變更。

測地區段

測地設定只適用於折線與多邊形。 它不適用於圓形,因為圓形未定義為區段集合。

測地設定可判斷要如何繪製折線/多邊形的連續頂點之間的線條區段。 測地區段就是沿著地球表面(球體)行進的最短路徑,且通常會使用麥卡托投影法在地圖上顯示為曲線。

非測地區段會在地圖上繪製為直線。

透過呼叫 *Options.geodesic() 可以在形狀的選項物件上設定此屬性,其中 true 指出應該將區段繪製為測地區段,而 false 指出應該將區段繪製為直線。

如果未指定,預設為非測地區段 (false)。

在將形狀新增至地圖之後,透過呼叫 isGeodesic() 就能存取測地設定,且透過呼叫 setGeodesic() 就能夠變更。

Z 索引

Z 索引指定此形狀與地圖上其他疊加層(其他形狀、地面疊加層及地圖方塊疊加層)相對的堆疊順序。

Z 索引較高的疊加層會繪製在 z 索引較低的疊加層上方。 Z 索引相同的兩個疊加層會以任意順序繪製。

請注意,標記一律繪製在其他疊加層之上,無論其他疊加層的 Z 索引為何。

透過呼叫 *Options.zIndex() 可以在形狀的選項物件上設定此屬性。 如果未指定,預設 z 索引為 0。 在將形狀新增至地圖之後,透過呼叫 getZIndex() 就能存取 z 索引,且透過呼叫 setZIndex() 就能夠變更。

能見度

能見度指定是否應該在地圖上繪製形狀,其中 true 指出應該繪製,而 false 指出不應該繪製。 它可以讓您暫時不在地圖上顯示某形狀。 在形狀上呼叫 remove(),就能夠從地圖永久移除該形狀。

透過呼叫 *Options.visible() 可以在形狀的選項物件上設定此屬性。 如果未指定,預設能見度為 true。 在將形狀新增至地圖之後,透過呼叫 isVisible() 就能存取能見度,且透過呼叫 setVisible() 就能夠變更。

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

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