Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

3D 地圖最佳做法

本指南將詳細介紹 3D Maps 網頁元件，以及與應用程式整合時的注意事項。

Place Search 和路線規劃的用途範例。 — Place Search 和路線規劃範例。

效能考量

為確保互動和視覺元素流暢且反應靈敏，請考慮採用下列方法。

載入地圖

3D 地圖的初始載入和算繪設定結合了瀏覽器設定技術和 UI 最佳做法，可提供最佳使用者體驗。

API 載入：使用 3D 地圖非同步動態載入，在初始載入網頁時載入 Maps JavaScript API。
程式庫：視需要透過程式輔助方式載入程式庫，例如 google.maps.importLibrary("maps3d")。或者，如果您透過直接指令碼載入，在 HTML 網頁中直接使用 <gmp-map-3d> 等網頁元件，程式庫會在適當時間自動載入
管理基本地圖地圖項目：使用自訂 mapId 篩選基本地圖搜尋點 (HYBRID 模式)，並控制其密度，特別是當應用程式有自己的自訂元素 (例如標記或折線) 時。這樣可以避免視覺雜亂和潛在重疊。或者，您也可以停用底圖向量圖塊功能，例如搜尋點、道路折線、道路名稱、街道名稱 (衛星模式)。
事件：監聽 gmp-steadystate 或 gmp-error 事件，建構後續邏輯，例如載入標記、為攝影機加上動畫效果。

地圖載入序列 — 背景畫布 > 縮小的圖塊 > 地形網格 > 表面網格 (例如建築物) > 搜尋點和道路標籤，以及平行載入的自訂元素 (標記、3D 模型等)

使用者互動：請等待 gmp-steadystate 事件發生，再變更地圖內容。如果使用者在初始 gmp-steadystate 事件發生前，就開始與地圖互動 (平移、縮放)，則事件只會在使用者停止互動後觸發。使用者平移或縮放地圖時，請避免顯示或更新疊加層內容 (例如標記或多邊形)，並監聽 gmp-centerchange、gmp-headingchange、gmp-rangechange、gmp-rollchange、gmp-tiltchange，避免顯示或更新疊加層內容 (例如標記或多邊形)。
使用 requestAnimationFrame() (rAF) 進行持續更新，並嚴格區分密集計算和繪製呼叫。
- 使用 rAF：與瀏覽器的顯示速率同步更新，提供流暢的 60 FPS 動畫，並降低耗電量。
- 避免大量繪圖作業：在最終更新期間，請勿執行繁重的非繪圖工作。
- 區隔邏輯：在 rAF 迴圈內執行所有密集邏輯，再執行最小網頁元件更新呼叫。
初始場景設定：<gmp-map-3d> 傾斜等攝影機設定會影響載入速度。場景縮放或傾斜程度越大，顯示的多邊形就越精細，需要載入的資料也越多。詳細程度也取決於位置 (例如：建築物林立的城市與只有自然景觀的鄉村)。
- 建議使用縮放程度較低 (高海拔)、低傾斜或無傾斜的視角。
- 在地圖中加入邊界 (範例)，讓使用者專注於特定區域，並完整載入圖塊。
預先載入器視覺效果：雖然 <gmp-map-3d> 載入速度極快，但如果使用者使用低階裝置 (低 GPU) 或頻寬 (慢速 4G)，可能需要一些時間才能以完整解析度顯示。在這種情況下，您可以建立預先載入器，在背景載入 3D 場景時顯示圖片、動畫或文字。請參閱下方要使用的重要事件：

// create the map in the background and wait for gmp-steadystate event
async function initMap() {
    await google.maps.importLibrary("maps3d");
    const map = document.querySelector('gmp-map-3d');
    const div = document.querySelector('div'); // preloader "
    map.addEventListener('gmp-steadystate', ({isSteady}) => {
        if (isSteady) {
            div.style.display = 'none';
        }
    });
}
initMap();

2D 地圖：
- 您可以向這些使用者提供替代的 2D 地圖 (SATELLITE)，同時仍包含標記等地理資料。

或者，您也可以在載入時，以衛星模式顯示輔助的 2D 靜態地圖，讓使用者查看特定地點。

視覺元素成效和管理

3D 地圖提供多種方式，可顯示標記、折線、折線和 3D 模型等視覺元素，並以最佳效能和最短時間算繪，即使是大量視覺元素也沒問題。

標記

最佳自訂選項：
- PinElement：如要變更基本標記 (顏色、比例、邊框、文字字符)，請使用 <gmp-pin> 元素或 PinElement 類別。這是效能最佳的自訂方法。
- 謹慎使用 HTMLImageElement 或 SVGElement 標記：用於進一步自訂，例如新增透明度，或將圖示等圖片插入 SVGElement (需要 base64 編碼)。這類資源會在載入時進行點陣化，並產生效能負擔。HTMLImageElement 和 SVGElement 必須先包裝在 <template> 元素中，才能指派給 Marker3DElement 的預設版位。
- 目前無法新增純 HTML 或 CSS。
管理衝突行為：善用標記的 collisionBehavior 屬性。如果重要標記必須一律顯示，請據此設定行為。對於較不重要的標記，請允許隱藏，以維持更乾淨、不雜亂的地圖體驗，尤其是在高縮放等級時。
僅限重要 POI：只有在標記必須穿透建築物或地形顯示時 (例如救援目標、埋在地下的公用管線或使用者虛擬化身)，才使用 drawsWhenOccluded (或透過程式輔助設定屬性)。
測試遮蔽：由於地圖是 3D，標記可能會被建築物或地形遮蔽。測試不同的相機角度和標記高度，確保重要搜尋點仍可見，或實作邏輯，在遮蔽時調整可見度和高度。
利用高度：在 3D 地圖中，標記應使用具有高度值的位置。如果是與地形或建築物相關聯的標記，請使用 altitudeMode: 'RELATIVE_TO_GROUND'、'RELATIVE_TO_MESH' 或類似設定，確保地圖傾斜或旋轉時，標記能正確錨定。

多邊形和折線

多邊形載入範例 — 情境範例：載入 1, 000 個多邊形需要 100 到 150 毫秒 (現代筆電：macOS M3 Pro、Chrome)

簡化幾何圖形：在算繪前，對路徑資料套用簡化演算法。這項功能可減少頂點數量，同時保留一般形狀，大幅提升算繪速度，特別是複雜的邊界或路線。
依縮放等級抽取：如果資料集非常龐大，建議只在使用者放大區域時，才載入更精細的幾何圖形。在低縮放等級下，只需要高度簡化的折線或多邊形版本。
預先計算擠出多邊形：如果多邊形是擠出 (extruded: true)，路徑資料會定義3D 體積 (網格)。處理複雜、高頂點的多邊形需要耗費大量運算資源。請確保多邊形的來源資料盡可能簡單。
測試折線和多邊形效能：新增大量或複雜的折線/多邊形時，尤其是 3D 擠出效果，請確保不會導致影格率下降。如有需要，請限制頂點數量或使用簡化演算法。
更新形狀時，請在單一作業中修改整個路徑陣列，而不是循環修改個別元素。單一指派作業 (例如 polyline.path = newPathArray;) 的效率遠高於多次疊代更新。
盡可能避免使用擠出折線：雖然折線可以使用高度值放置在 3D 空間中，但擠出折線 (例如指定筆劃寬度和較大的高度範圍) 可能會耗用大量圖形資源。請盡可能使用地面上的 2D 折線 (RELATIVE_TO_GROUND) 或最小筆劃寬度，以提升效能。
請只針對重要的路線元素使用 drawsOccludedSegments。如果是背景或情境形狀，請允許地圖的 3D 幾何圖形自然遮擋這些形狀。顯示非關鍵的隱藏幾何圖形會增加不必要的算繪複雜度。

3D 模型

在 <gmp-map-3d> 中，3D 模型 .glb 算繪和互動功能 (例如 gmp-click 事件) 的速度非常快。

壓縮檔案，盡可能縮減大小：為確保載入速度，尤其是使用行動網路時，請將複雜的 .glb 模型檔案大小控制在 5 MB 以下 (越小越好)。主要方法是對 .glb 檔案中的網格資料套用 Draco 壓縮，這樣可以大幅縮減檔案大小 (通常超過 50%)，同時盡可能減少視覺品質損失。
置中模型原點：確認 3D 建模軟體匯出的模型原點 (0, 0, 0 點) 位於模型底部中心。這可簡化地圖上的定位和旋轉作業，確保模型正確錨定至經緯度座標。
管理 CORS：如果模型檔案託管於與網頁應用程式不同的網域或 CDN，您必須設定託管伺服器，加入必要的跨源資源共享 (CORS) 標頭 (例如 Access-Control-Allow-Origin: *)，否則地圖無法載入模型。