區域疊加層

選取平台： Android iOS JavaScript

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

程式碼範例

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 物件。

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)

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

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

Kotlin



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

Java


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

移除疊加層

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

Kotlin



imageOverlay?.remove()

Java


imageOverlay.remove();

變更疊加層

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

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

Java


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

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

指定區域疊加層的位置

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

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

請先指定區域疊加層的位置，才能將其加入地圖。

使用位置來定位圖片

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

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

Kotlin



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

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

使用 LatLngBounds 指定圖片位置

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

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

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)

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

連結資料與區域疊加層

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

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

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"

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

以下舉例說明適合使用區域疊加層儲存/擷取資料的情形：

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

處理區域疊加層事件

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

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