Google 地圖平台 15 週年紀念查看最新消息和公告

區域疊加層

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

程式碼範例

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

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

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

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

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

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

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

移除疊加層

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

imageOverlay.remove();

變更疊加層

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

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

// Update the GroundOverlay with a new image of the same dimensions.
imageOverlay = map.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1975));

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

指定區域疊加層的位置

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

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

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

使用位置來定位圖片

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

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

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

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() 擷取資料物件。

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

private GoogleMap mMap;
private GroundOverlay mSydneyGroundOverlay;

mSydneyGroundOverlay = mMap.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206))
    .clickable(true));

mSydneyGroundOverlay.setTag("Sydney");

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

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

處理區域疊加層事件

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

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