Ground Overlays | Maps SDK for Android | Google Developers

A ground overlay is an image that is fixed to a map. Unlike markers, ground overlays are oriented against the Earth's surface rather than the screen, so ... Google 地圖平台 總覽 產品 定價 說明文件 開始使用 開始使用Google地圖平台 API挑選器 計費和定價方式 報表與監控 地圖ID 常見問題 支援與資源 事件管理 地圖介面集 MapsJavaScriptAPI MapsSDKforAndroid MapsSDKforiOS MapsStaticAPI StreetViewStaticAPI MapsEmbedAPI 地圖網址 MapsElevationAPI 路徑介面集 DirectionsAPI DistanceMatrixAPI RoadsAPI 解決方案 產業解決方案 遊戲服務 運輸與物流 地點介面集 PlacesAPI PlacesSDKforAndroid PlacesSDKforiOS PlacesLibrary、MapsJavaScriptAPI GeocodingAPI GeolocationAPI TimeZoneAPI 其他資源 API安全性最佳做法 地圖涵蓋範圍詳細資料 最佳化指南 行動作業系統和軟體支援 淘汰項目 資產追蹤方案 根憑證授權單位遷移常見問題 網址編碼 WordPress使用者 網誌 社群 StackOverflow GitHub YouTube Discord Twitter IssueTracker Language English BahasaIndonesia Deutsch Español Español–AméricaLatina Français Português–Brasil Русский 中文–简体 中文–繁體 日本語 한국어 登入 Android MapsSDKforAndroid 開始使用 聯絡銷售人員 指南 參考資料 範例 支援 Google 地圖平台 總覽 產品 定價 說明文件 更多 指南 參考資料 範例 支援 網誌 社群 更多 MapsSDKforAndroid 總覽 快速入門導覽課程 設定 設定GoogleCloud專案 使用API金鑰 設定AndroidStudio專案 版本 Beta版 MapsSDKforAndroid3.1.0Beta版 使用MapsSDK3.1.0Beta版Beta版 教學課程 含有標記的地圖 代表路徑和區域的折線和多邊形 選取目前所在地點 作業與概念 建立和設定地圖 新增地圖設定現有地圖新版地圖轉譯器(選用)街景服務全景商家和其他搜尋點精簡模式 與地圖互動 相機和檢視畫面控制項和手勢事件位置資料啟動Google地圖 在地圖上繪圖 標記資訊視窗形狀區域疊加層圖塊疊加層 管理標記和標籤衝突 使用雲端式地圖樣式設定進行自訂 使用JSON樣式進行自訂 新增樣式化地圖使用樣式隱藏地圖項目樣式參考資料 強化無障礙功能 在WearOS上使用MapsAPI 開放原始碼程式庫 公用程式庫 總覽設定和示範GeoJSONKML熱視圖標記叢集多圖層 KTXKotlin擴充功能 MapsCompose程式庫 MapsRx程式庫 SecretsGradle外掛程式 政策與條款 用量與計費 回報與監控 服務條款 為GooglePlay的資料揭露規定做好準備 開始使用 開始使用Google地圖平台 API挑選器 計費和定價方式 報表與監控 地圖ID 常見問題 支援與資源 事件管理 地圖介面集 MapsJavaScriptAPI MapsSDKforAndroid MapsSDKforiOS MapsStaticAPI StreetViewStaticAPI MapsEmbedAPI 地圖網址 MapsElevationAPI 路徑介面集 DirectionsAPI DistanceMatrixAPI RoadsAPI 解決方案 產業解決方案 遊戲服務 運輸與物流 地點介面集 PlacesAPI PlacesSDKforAndroid PlacesSDKforiOS PlacesLibrary、MapsJavaScriptAPI GeocodingAPI GeolocationAPI TimeZoneAPI 其他資源 API安全性最佳做法 地圖涵蓋範圍詳細資料 最佳化指南 行動作業系統和軟體支援 淘汰項目 資產追蹤方案 根憑證授權單位遷移常見問題 網址編碼 WordPress使用者 StackOverflow GitHub YouTube Discord Twitter IssueTracker 首頁 產品 Google地圖平台 說明文件 Android MapsSDKforAndroid 指南 提供意見 區域疊加層 選取平台： Android iOS JavaScript 區域疊加層是指固定在地圖上某個經緯度座標的影像重疊，因此在拖曳或縮放地圖時，區域疊加層會隨之移動。

程式碼範例 GitHub上的ApiDemos存放區有區域疊加層的說明範例： GroundOverlayDemoActivity-Java：Java環境中的區域疊加層功能和事件監聽器 GroundOverlayDemoActivity-Kotlin：Kotlin環境中的區域疊加層功能和事件監聽器 簡介 區域疊加層是指固定於地圖上的圖片。

不同於標記，區域疊加層顯示方向的依據是實際地表而非裝置螢幕，因此當您旋轉、傾斜或縮放地圖時，圖片的方向也會隨之改變。

當您想修正地圖上某個區域的單一圖片時，區域疊加層就非常實用。

如果您想新增涵蓋地圖上大範圍區域的大量圖像，建議您使用圖塊疊加層。

新增疊加層 如要新增GroundOverlay，請建立用於定義圖片和位置的GroundOverlayOptions物件。

您可以視需要針對地圖上的圖片位置指定額外設定；定義必要的選項後，將物件傳送至GoogleMap.addGroundOverlay()方法，即可將圖片加入地圖。

addGroundOverlay()方法會傳回GroundOverlay物件；建議您保留這個物件的參考資料，以便日後修改。

注意：將圖片加到地圖中後，系統會將圖片的長寬轉換為二次方的倍數。

如不希望系統幫您轉換圖片大小，請使用原尺寸就是二次方倍數的圖片，例如128x512或1024x1024。

逐步指南如下： 將新的GroundOverlayOptions物件執行個體化 將圖片指定為BitmapDescriptor。

請使用下列其中一個可用方法設定圖片的位置： position(LatLnglocation,floatwidth,floatheight) position(LatLnglocation,floatwidth) positionFromBounds(LatLngBoundsbounds) 視需要設定選用屬性，例如transparency。

呼叫GoogleMap.addGroundOverlay()可將圖片加入地圖。

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

Java LatLngnewarkLatLng=newLatLng(40.714086,-74.228697); GroundOverlayOptionsnewarkMap=newGroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .position(newarkLatLng,8600f,6500f); map.addGroundOverlay(newarkMap); Kotlin valnewarkLatLng=LatLng(40.714086,-74.228697) valnewarkMap=GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .position(newarkLatLng,8600f,6500f) map.addGroundOverlay(newarkMap) 如果您在區域疊加層加到地圖中之後，想要予以變更或移除，請務必保留GroundOverlay物件，這樣稍後您只要變更這個物件，就可以修改疊加層。

Java //Addanoverlaytothemap,retainingahandletotheGroundOverlayobject. GroundOverlayimageOverlay=map.addGroundOverlay(newarkMap); Kotlin //Addanoverlaytothemap,retainingahandletotheGroundOverlayobject. valimageOverlay=map.addGroundOverlay(newarkMap) 移除疊加層 使用GroundOverlay.remove()方法可移除區域疊加層。

Java imageOverlay.remove(); Kotlin imageOverlay?.remove() 變更疊加層 將區域疊加層圖片加入地圖後，使用GroundOverlay.setImage(BitmapDescriptor)方法可對其進行變更。

Java //UpdatetheGroundOverlaywithanewimageofthesamedimension imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)); Kotlin //UpdatetheGroundOverlaywithanewimageofthesamedimension //UpdatetheGroundOverlaywithanewimageofthesamedimension imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) setImage()方法可將現有圖片換成另一張尺寸相同的圖片。

指定區域疊加層的位置 有兩種方法可指定區域疊加層的位置： 使用LatLng將疊加層置於中心處，並以公尺為單位指定圖片尺寸。

使用LatLngBounds指定圖片的東北角和西南角。

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

使用位置來定位圖片 加入圖片時，您必須指定錨點的經緯度，以及疊加層的寬度(單位為公尺)。

系統會將anchor預設為圖片的中心。

您也可以視情況提供疊加層的高度(單位為公尺)。

如未提供疊加層的高度，系統會自動計算，以維持圖片比例。

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

Java GroundOverlayOptionsnewarkMap=newGroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .anchor(0,1) .position(newLatLng(40.714086,-74.228697),8600f,6500f); Kotlin valnewarkMap=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 LatLngBoundsnewarkBounds=newLatLngBounds( newLatLng(40.712216,-74.22655),//Southwestcorner newLatLng(40.773941,-74.12544));//Northeastcorner GroundOverlayOptionsnewarkMap=newGroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .positionFromBounds(newarkBounds); Kotlin valnewarkBounds=LatLngBounds( LatLng(40.712216,-74.22655),//Southwestcorner LatLng(40.773941,-74.12544)//Northeastcorner ) valnewarkMap=GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .positionFromBounds(newarkBounds) 連結資料與區域疊加層 您可以呼叫GroundOverlay.setTag()以儲存包含區域疊加層的任意資料物件，並使用GroundOverlay.getTag()擷取資料物件。

以下程式碼範例會儲存包含區域疊加層的字串說明： Java GroundOverlaysydneyGroundOverlay=map.addGroundOverlay(newGroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge)) .position(newLatLng(-33.873,151.206),100) .clickable(true)); sydneyGroundOverlay.setTag("Sydney"); Kotlin valsydneyGroundOverlay=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)回呼。

注意：如果多個疊加層或形狀(標記、折線、多邊形、圓形和/或區域疊加層)彼此重疊，點擊事件會先透過標記叢集循環，然後根據其他可點擊疊加層或形狀的Z-index值加以觸發。

每次點擊最多只能觸發一個事件；也就是說，點擊不會向下傳遞至具有較低Z-index值的疊加層或形狀。

進一步瞭解標記Z-index和點擊事件。

提供意見 Exceptasotherwisenoted,thecontentofthispageislicensedundertheCreativeCommonsAttribution4.0License,andcodesamplesarelicensedundertheApache2.0License.Fordetails,seetheGoogleDevelopersSitePolicies.JavaisaregisteredtrademarkofOracleand/oritsaffiliates. Lastupdated2022-03-30UTC. [{ "type":"thumb-down", "id":"missingTheInformationINeed", "label":"缺少我需要的資訊" },{ "type":"thumb-down", "id":"tooComplicatedTooManySteps", "label":"過於複雜/步驟過多" },{ "type":"thumb-down", "id":"outOfDate", "label":"過時" },{ "type":"thumb-down", "id":"translationIssue", "label":"翻譯問題" },{ "type":"thumb-down", "id":"samplesCodeIssue", "label":"示例/程式碼問題" },{ "type":"thumb-down", "id":"otherDown", "label":"其他" }] [{ "type":"thumb-up", "id":"easyToUnderstand", "label":"容易理解" },{ "type":"thumb-up", "id":"solvedMyProblem", "label":"確實解決了我的問題" },{ "type":"thumb-up", "id":"otherUp", "label":"其他" }] 想進一步說明嗎？ StackOverflow 使用google-maps標記提出問題。

GitHub 運用現有樣本進行設計。

Discord 與其他開發人員交流，瞭解Google地圖平台。

IssueTracker 如果發生錯誤，請傳送錯誤報告給我們！ 瞭解詳情 常見問題 API挑選器 PlacesSDKforAndroid 平台 Android iOS 網路 網路服務 產品資訊 計費方式與方案簡介 與銷售人員聯絡 支援 服務條款 Android Chrome Firebase GoogleCloudPlatform 所有產品 條款 隱私權 訂閱GoogleDevelopers電子報 訂閱 Language English BahasaIndonesia Deutsch Español Español–AméricaLatina Français Português–Brasil Русский 中文–简体 中文–繁體 日本語 한국어