區域疊加層

區域疊加層是指固定在地圖上某個經緯度座標的影像重疊,因此當您拖曳或縮放地圖時,區域疊加層會隨之移動。

程式碼範例

GitHub 上的 ApiDemos 存放區有區域疊加層的說明範例:

簡介

區域疊加層是指固定於地圖上的圖片。不同於標記,區域疊加層顯示方向的依據是實際地表而非裝置螢幕,因此當您旋轉、傾斜或縮放地圖時,圖片的方向也會隨之改變。當您想修正地圖上某個區域的單一圖片時,區域疊加層就非常實用。如果您想新增涵蓋地圖上大範圍區域的大量圖像,建議您使用圖塊疊加層

新增疊加層

如要新增 GroundOverlay,請建立用於定義圖片和位置的 GroundOverlayOptions 物件。您可以視需要針對地圖上的圖片位置指定額外設定;定義必要的選項後,將物件傳送至 GoogleMap.addGroundOverlay() 方法,即可將圖片加入地圖。addGroundOverlay() 方法會傳回 GroundOverlay 物件;建議您保留這個物件的參考資料,以便日後修改。

逐步指南如下:

  1. 將新的 GroundOverlayOptions 物件執行個體化
  2. 將圖片指定為 BitmapDescriptor
  3. 請使用下列其中一個可用方法設定圖片的位置:
    • position(LatLng location, float width, float height)
    • position(LatLng location, float width)
    • positionFromBounds(LatLngBounds bounds)
  4. 視需要設定選用屬性,例如 transparency
  5. 呼叫 GoogleMap.addGroundOverlay() 可將圖片加入地圖。

以下範例說明如何將區域疊加層加到現有的 GoogleMap 物件。

Java

LatLng newarkLatLng = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f);
map.addGroundOverlay(newarkMap);
      

Kotlin

val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)
      

如果您在區域疊加層加到地圖中之後,想要予以變更或移除,請務必保留 GroundOverlay 物件,這樣稍後您只要變更這個物件,就可以修改疊加層。

Java

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);
      

Kotlin

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)
      

移除疊加層

使用 GroundOverlay.remove() 方法可移除區域疊加層。

Java

imageOverlay.remove();
      

Kotlin

imageOverlay.remove()
      

變更疊加層

將區域疊加層圖片加入地圖後,使用 GroundOverlay.setImage(BitmapDescriptor) 方法可對其進行變更。

Java

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));
      

Kotlin

// Update the GroundOverlay with a new image of the same dimension

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
      

setImage() 方法可將現有圖片換成另一張尺寸相同的圖片。

指定區域疊加層的位置

有兩種方法可指定區域疊加層的位置:

  • 使用 LatLng 將疊加層置於中心處,並以公尺為單位指定圖片尺寸。
  • 使用 LatLngBounds 指定圖片的東北角和西南角。

您必須先指定區域疊加層的位置,才能將其加入地圖。

使用位置來定位圖片

加入圖片時,您必須指定錨點的經緯度,以及疊加層的寬度 (單位為公尺)。系統會將 anchor 預設為圖片的中心。您也可以視情況提供疊加層的高度 (單位為公尺)。如未提供疊加層的高度,系統會自動計算,以維持圖片比例。

下方程式碼是將一張圖片置於寬 8.6 公里、高 6.5 公里高的 40.714086, -74.228697 位置,且將圖片錨定在左下角。

Java

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0, 1)
    .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);
      

Kotlin

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)
      

使用 LatLngBounds 指定圖片位置

您提供的 LatLngBounds 包含圖片。LatLngBounds 會設定圖片的東北角和西南角。在地圖上繪製圖片時,系統會將圖片旋轉至適合的邊界。如果邊界與原始顯示比例不相符,圖像將遭到扭曲。

下方程式碼將一張圖片置於地圖上,其西南角邊界為 40.712216,-74.22655、東北角邊界為 40.773941, -74.12544

Java

LatLngBounds newarkBounds = new LatLngBounds(
    new LatLng(40.712216, -74.22655),       // South west corner
    new LatLng(40.773941, -74.12544));      // North east corner
GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds);
      

Kotlin

val newarkBounds = LatLngBounds(
    LatLng(40.712216, -74.22655),  // South west corner
    LatLng(40.773941, -74.12544)   // North east corner
)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds)
      

連結資料與區域疊加層

您可以呼叫 GroundOverlay.setTag() 以儲存包含區域疊加層的任意資料物件,並使用 GroundOverlay.getTag() 擷取資料物件。

以下程式碼範例會儲存包含區域疊加層的字串說明:

Java

GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206), 100)
    .clickable(true));

sydneyGroundOverlay.setTag("Sydney");
      

Kotlin

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay.tag = "Sydney"
      

以下範例說明如何儲存及擷取包含區域疊加層的資料:

  • 您的應用程式可支援不同的區域疊加層,而您希望系統能在使用者點擊區域疊加層時,根據類型以不同方式回應。
  • 您操作的系統可能具備不重複的記錄 ID,而在該系統內,疊加層代表特定記錄。
  • 疊加層資料可指示決定疊加層 Z-index 的優先順序。

處理區域疊加層事件

根據預設,區域疊加層不可點擊;您可以呼叫 GroundOverlay.setClickable(boolean) 來啟用及停用可點擊屬性。

使用 OnGroundOverlayClickListener 可監聽可點擊區域疊加層的點擊事件。如要在地圖上設定這個事件監聽器,請呼叫 GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener)。這樣一來,使用者點擊區域疊加層時,您就會收到 onGroundOverlayClick(GroundOverlay) 回呼。