Azure 地圖服務 Web SDK 最佳做法

發行項
04/11/2024

本文件著重於 Azure 地圖服務 Web SDK 的最佳做法，但此處概述的許多最佳做法和最佳化方式皆可套用至其他所有 Azure 地圖服務 SDK。

Azure 地圖服務 Web SDK 提供強大的畫布功能，可透過許多不同方式轉譯大型空間資料集。在某些情況下，有多種方式能以相同方式轉譯資料，但根據資料集的大小及所需功能，其中一種方法可能更為適合。本文重點說明各項最佳做法及秘訣與訣竅，以便發揮最佳效能，建立流暢的使用者體驗。

基本上，若要改善地圖效能，請盡可能減少圖層和來源數，以及所用資料集與轉譯樣式的複雜度。

安全性最佳做法

如需安全性最佳做法的更多資訊，請參閱驗證和授權最佳做法。

使用最新版本的 Azure 地圖服務

Azure 地圖服務 SDK 會搭配用於 SDK 的任何外部相依性程式庫，進行一般安全性測試。已知的任何安全性問題皆會及時修正，並核發至實際執行環境。若應用程式指向裝載 Azure 地圖服務 Web SDK 的最新主要版本，便會自動收到包含安全性相關修正的所有次要版本更新。

若是透過 NPM 模組自我裝載 Azure 地圖服務 Web SDK，請務必使用插入號 (^) 符號，搭配 package.json 檔案中的 Azure 地圖服務 NPM 套件版本號碼，使其指向最新的次要版本。

"dependencies": {
  "azure-maps-control": "^3.0.0"
}

提示

請一律使用最新版的 npm Azure 地圖服務控制項。如需詳細資訊，請參閱 npm 文件中的 azure-maps-control。

地圖初始載入最佳化

載入網頁時的第一件事，便是盡快開始進行轉譯，以免讓使用者只能看著空白畫面。

觀看地圖就緒事件

初始載入地圖時，通常也會期望能盡快載入資料，以免讓使用者只能看著空白地圖。由於地圖會以非同步方式載入資源，因此您必須等到地圖準備好進行互動，再嘗試轉譯自己的資料。您可等候兩個事件： load 事件和 ready 事件。載入事件會在地圖完成載入初始地圖檢視之後引發，而且每個地圖圖格都已載入。如果您看到「樣式未完成載入」錯誤，則應該使用 load 事件，並等候樣式完全載入。

當需要最低限度的地圖資源以便與地圖互動時，便會引發就緒事件。更精確地說，當地圖第一次載入樣式資料時，就會觸發 ready 事件。就緒事件通常會在載入事件進行到一半時引發，以便更快開始將資料載入地圖。請避免在此時變更地圖的樣式或語言，因為這樣做可能會觸發樣式重新載入。

消極式載入 Azure 地圖服務 Web SDK

若非立即需要地圖，請消極式載入 Azure 地圖服務 Web SDK，需要時再載入。如此可延遲載入 Azure 地圖服務 Web SDK 所用的 JavaScript 和 CSS 檔案，直到需要時為止。發生此情況的常見案例是，若地圖以索引標籤或飛出面板方式載入，頁面載入時便不會顯示。

消極式載入地圖程式碼範例示範如何延遲載入 Azure 地圖服務 Web SDK，直到按下按鈕為止。如需原始程式碼，請參閱消極式載入地圖範例程式碼。

新增地圖的預留位置

若由於應用程式內的網路限制或其他優先順序，而需要一段時間載入地圖，請考慮將小型背景影像新增至地圖 div，作為地圖的預留位置。如此載入時便會填滿地圖 div 的空處。

在初始化時設定初始地圖樣式及相機選項

應用程式通常要載入地圖的特定位置或樣式。有時開發人員會等候地圖載入後 (或等候 ready 事件)，再使用地圖的 setCamera 或 setStyle 函式。如此取得所需初始地圖檢視的時間通常較長，因為在載入所需地圖檢視的所需資源前，有許多資源已預設先載入。更好的做法是在初始化時，便將所需的地圖相機和樣式選項傳至地圖。

最佳化資料來源

Web SDK 有兩個資料來源：

GeoJSON 來源：DataSource 類別會在本機管理 GeoJSON 格式的原始位置資料。適用於中小型資料集 (至少有數十萬個圖徵)。
向量圖格來源：VectorTileSource 類別會根據地圖底圖系統，以向量圖格為格式載入目前地圖檢視的資料。適用於大型資料集 (數百萬或數十億個圖徵)。

大型資料集採用圖格式解決方案

若使用含數百萬個圖徵的大型資料集，則建議採用伺服器端解決方案 (如向量或點陣影像圖格服務) 來公開資料，以達最佳效能。
向量圖格已進行最佳化，只載入裁剪為圖格焦點區域的幾何要素資料；並已進行一般化，以便符合圖格縮放層級的地圖解析度。

Azure 地圖服務建立工具平台會以向量圖格的格式擷取資料。其他資料格式可以使用 Tippecanoe 之類的工具。如需使用向量圖格的詳細資訊，請參閱 GitHub 中的 Mapbox awesome-vector-tiles 讀我檔案。

您也可建立自訂服務，將資料集轉譯為伺服器端的點陣影像圖格，並使用地圖 SDK 中的 TileLayer 類別載入資料。如此便可提供絕佳的效能，因為地圖最多僅須載入和管理數十個影像。但由於原始資料無法在本機使用，因此點陣圖格有些使用限制。次要服務通常會需要進行任何類型的互動體驗，例如：找出使用者所點選的圖形。此外，相較於壓縮的向量圖格 (包含已一般化、縮放層級最佳化的幾何圖形)，點陣圖格的檔案大小通常也較大。

如需資料來源的詳細資訊，請參閱建立資料來源。

將多個資料集合併為單一向量圖格來源

地圖須管理的資料來源愈少，處理所有待顯示圖徵的速度愈快。特別是圖格來源，合併兩個向量圖格來源可讓擷取圖格的 HTTP 要求數目減半；由於只有一個檔案標頭，因此總資料量也會少一點。

使用 Tippecanoe 等工具，即可合併單一向量圖格來源中的多個資料集。資料集可合併為單一圖徵集合，也可分為向量圖格內的不同圖層 (亦稱為來源圖層)。連結向量圖格來源與轉譯圖層時，您可指定待轉譯圖層資料所屬的來源圖層。

減少因資料更新而重新整理畫布的次數

DataSource 類別的資料有幾種新增或更新的方式。下列清單列出確保效能無虞的不同方法及幾項考量。

資料來源 add 函數可用於將一或多個圖徵新增至資料來源。每次呼叫此函數時，皆會觸發地圖畫布重新整理。若要新增許多圖徵，請將其合併為陣列或圖徵集合並一次傳至此函數，而不是迴圈執行資料集，並針對每個圖徵呼叫此函數。
資料來源 setShapes 函數可用於覆寫資料來源中的所有圖形。基本上，此函數會結合資料來源 clear 與 add 函數，一次重新整理地圖畫布，而無須分兩次，藉此提升速度。當您要更新資料來源中的全部資料時，請務必使用此函數。
資料來源 importDataFromUrl 函數可用於透過 URL 將 GeoJSON 檔案載入資料來源。資料下載後便會傳遞至資料來源函數 add。若 GeoJSON 檔案裝載於不同網域，請確定該網域支援跨網域要求 (COR)。若不支援，則請考慮將資料複製至網域上的本機檔案，或建立已啟用 COR 的 Proxy 服務。若檔案較大，請考慮轉換為向量圖格來源。
若圖徵包裝為 Shape 類別，則圖形的 addProperty、setCoordinates和 setProperties 函數會觸發更新資料來源，以及重新整理地圖畫布。資料來源 getShapes 和 getShapeById 函數傳回的所有圖徵皆會自動包裝為 Shape 類別。若要更新數個圖形，速度較快的方式是使用資料來源 toJson 函數將其轉換為 JSON，編輯 GeoJSON，再將此資料傳至資料來源函數 setShapes。

避免非必要呼叫資料來源的 clear 函數

呼叫 DataSource 類別的 clear 函數時，地圖畫布便會重新整理。若在資料列中多次呼叫 clear 函數，則地圖等候每次重新整理時可能會發生延遲。

當應用程式清除資料來源、下載新資料、再次清除資料來源，接著將資料新增至資料來源時，經常發生此情況。視所需的使用者體驗而定，下列替代方案可能更好。

先清除資料再下載新資料，接著將新資料傳至資料來源 add 或 setShapes 函數。若這是地圖上唯一的資料集，則下載新資料時地圖將為空白。
下載新資料，並將其傳至資料來源 setShapes 函數。此操作會取代地圖上的所有資料。

移除未使用的圖徵和屬性

若資料集所含的圖徵不會用於應用程式，則請移除。非必要圖徵的所有屬性也請移除。這有幾項優點：

減少必須下載的資料量。
減少轉譯資料時須迴圈執行的圖徵數。
有時有助於簡化或移除資料驅動的運算式和篩選條件，意即轉譯時所需的處理更少。

當圖徵有許多屬性或內容時，更具效率的做法是：將資料來源的新增項目僅限於轉譯所需的項目，並視需要採用不同方法或服務來擷取其他屬性或服務。例如：如果您使用一個簡易地圖顯示地圖上的位置，當您選取時，會顯示大量詳細內容。若要使用資料驅動樣式來自訂地圖位置的轉譯方式，請只在資料來源中載入所需屬性。若要顯示詳細內容，請使用圖徵的識別碼個別擷取其他內容。若內容儲存於伺服器端，您可使用服務以非同步方式擷取內容，減少地圖初始載入時須下載的資料量。

此外，減少圖徵座標中的有效位數，也可有效縮小資料量。座標包含 12 個以上的小數位數並非不常見；但六個小數位數的精確度約為 0.1 公尺，通常比座標所代表的位置更為精確 (若使用室內建築物配置等小型的位置資料，則建議使用六小數位數)。對資料轉譯方式而言，六個以上的小數位數可能並無差異，且會要求使用者下載更多資料，而無其他效益。

以下為使用 GeoJSON 資料的實用工具清單。

使用不同的資料來源以快速變更資料

有時必須快速更新地圖上的資料，例如：顯示串流資料的即時更新或以動畫方式呈現圖徵。更新資料來源時，轉譯引擎會迴圈執行並轉譯資料來源中的所有圖徵。將靜態和快速變更的資料分隔為不同的資料來源，減少每次更新期間重新轉譯的圖徵數目，從而改善整體效能。

若向量圖格要使用即時資料，則可使用 expires 回應標頭，以輕鬆支援更新。依預設，所有向量圖格來源或點陣圖格圖層皆會在 expires 日期自動重新載入圖格。地圖中的交通流量和事件圖格會使用此圖徵，以確保地圖顯示全新的即時交通資料。將地圖 refreshExpiredTiles 服務選項設為 false，即可停用此圖徵。

調整 GeoJSON 資料來源中的緩衝區和容錯選項

DataSource 類別會將原始位置資料轉換為本機的向量圖格，以進行即時轉譯。這些本機向量圖格會依圖格區域界限裁剪原始資料，並包含些許緩衝區，以確保圖格轉譯流暢。 buffer 選項愈小，本機向量圖格所儲存的重疊資料愈少，效能也愈好，但轉譯成品的變更則愈大。請嘗試調整此選項，適當平衡效能與最少的轉譯成品。

DataSource 類別也有 tolerance 選項，要降低幾何解析度以進行轉譯時，可搭配 Douglas-Peucker 簡化演算法使用。提高此容錯值時會降低幾何解析度，進而改善效能。調整此選項，適當平衡資料集的幾何解析度與效能。

設定 GeoJSON 資料來源的最高縮放選項

DataSource 類別會將原始位置資料轉換為本機的向量圖格，以進行即時轉譯。依預設，該動作執行到縮放層級 18 為止，此時便會從縮放層級 18 產生的圖格取樣資料。多數資料集在這些層級放大時需要較高解析度，便適用此作業。但若資料集較可能使用縮小檢視 (如檢視州或省的多邊形時)，將資料來源的 minZoom 選項設為較小值 (如 12) 便可減少計算量和產生的本機圖格，以及資料來源所用的記憶體，進而提升效能。

盡量減少 GeoJSON 回應

從伺服器載入 GeoJSON 資料 (透過服務或載入一般檔案) 時，請務必將資料最小化，並移除會讓下載大小超過需求的非必要空白字元。

使用 URL 存取原始 GeoJSON

GeoJSON 物件可內嵌儲存於 JavaScript，但這將會使用更多記憶體，因為您為此物件建立的變數及資料來源執行個體皆會儲存其副本，並在不同的 Web 背景工作角色內進行管理。請改用 URL 向應用程式公開 GeoJSON，資料來源便會將單一資料複本直接載入資料來源背景工作角色。

最佳化轉譯圖層

Azure 地圖服務提供數個不同圖層，可供轉譯地圖上的資料。您可運用許多最佳化功能為您的案例打造適合的圖層，以改善效能與整體使用者體驗。

一次建立圖層並重複使用

Azure 地圖服務 Web SDK 為資料驅動。資料會進入資料來源，並連接至轉譯圖層。若要變更地圖上的資料，請更新資料來源中的資料，或變更圖層上的樣式選項。這通常比起在每次變更時移除再重新建立圖層更快。

考慮使用泡泡圖層，而不是符號圖層

泡泡圖層會將點轉譯為地圖上的圓形，並可透過資料驅動運算式輕鬆設定其半徑和色彩樣式。由於圓形是容易用 WebGL 繪製的簡單圖形，因此轉譯引擎的轉譯速度會優於符號圖層，後者必須載入和轉譯影像。當轉譯數萬個點時，這兩個轉譯圖層的效能差異便顯而易見。

慎用 HTML 標記和快顯

Azure 地圖服務 Web 控制項中的大多數圖層使用 WebGL 來進行轉譯；但 HTML 標記和快顯則有所不同，使用傳統的 DOM 元素來進行轉譯。因此，頁面新增的 HTML 標記和快顯愈多，其中的 DOM 元素則愈多。新增幾百個 HTML 標記或快顯後，效能便會下降。若資料集較大，請考慮將資料叢集化，或使用「符號」或「泡泡」圖層。

重複使用具有多個釘選的快顯範例程式碼示範如何建立單一快顯，並藉由更新其內容和位置來重複使用。如需原始程式碼，請參閱重複使用具有多個圖釘的快顯範例程式碼。

話雖如此，若地圖上只有幾個點要轉譯，選用 HTML 標籤可能較為方便。此外，HTML 標籤也可視需要輕鬆設為可拖曳。

合併圖層

地圖可轉譯數百個圖層，但當圖層愈多時，轉譯場景所需的時間也愈多。減少圖層數的其中一項策略是合併類似樣式的圖層，或合併可使用資料驅動樣式的圖層。

例如：假設某資料集的所有圖徵皆具有 isHealthy 屬性，且值可為 true 或 false。若要建立泡泡圖層，並根據此屬性轉譯不同色彩的泡泡，可採用下表所列的幾種進行方式，依序為效率最低至最高。

根據 isHealthy 值將資料分為兩個資料來源，並於各資料來源附加具有硬式編碼色彩選項的泡泡圖層。
將所有資料放入單一資料來源，並建立兩個泡泡圖層，各包含硬式編碼色彩選項及根據 isHealthy 屬性的篩選條件。
將所有資料放入單一資料來源，建立單一泡泡圖層，並使用 case 樣式表達式設定根據 isHealthy 屬性的色彩選項。以下為示範此情況的程式碼範例。

var layer = new atlas.layer.BubbleLayer(source, null, {
    color: [
        'case',

        //Get the 'isHealthy' property from the feature.
        ['get', 'isHealthy'],

        //If true, make the color 'green'. 
        'green',

        //If false, make the color red.
        'red'
    ]
});

建立流暢的符號圖層動畫

依預設，符號圖層會啟用衝突偵測。此衝突偵測功能目的是確保任兩個符號皆不重疊。符號圖層的圖示和文字選項有兩個選項：

allowOverlap - 指定當該符號與其他符號相衝突時是否要顯示。
ignorePlacement - 指定是否允許其他符號與該符號相衝突。

依預設，這兩個選項皆設為 false。當符號以動畫方式呈現時，動畫的每個幀皆會進行衝突偵測計算，因而降低動畫速度以及流暢度。若要讓動畫更為流暢，請將這些選項設定為 true。

簡單符號動畫程式碼範例會示範一個以動畫顯示符號圖層的簡單方法。如需此範例的原始程式碼，請參閱簡單符號動畫範例程式碼。

具有轉圈符號之世界地圖的螢幕擷取畫面，示範如何藉由更新座標，以使地圖上有符號的位置活動起來。

指定縮放層級範圍

若您的資料符合下列其中一項準則，請務必指定圖層縮放等級的最小值和最大值，以便讓轉譯引擎在超出縮放等級範圍時跳過。

若資料來自向量圖格來源，不同資料類型的來源圖層通常只能透過各種縮放層級來使用。
若使用的圖格圖層並非在 0 至 24 的所有縮放層級皆有圖格，且您只要轉譯具有圖格的層級，而不嘗試使用其他縮放層級的圖格填入缺少的圖格。
若只要轉譯特定縮放層級的圖層。所有圖層都有 minZoom 和 maxZoom 選項，當圖層介於這些縮放層級之間時，便會根據邏輯 maxZoom > zoom >= minZoom 轉譯。

範例

//Only render this layer between zoom levels 1 and 9. 
var layer = new atlas.layer.BubbleLayer(dataSource, null, {
    minZoom: 1,
    maxZoom: 10
});

指定圖格圖層界限和來源縮放範圍

依預設，圖格圖層會載入整個地球的圖格。但若地圖底圖服務只有特定區域的圖格，當超出此區域時地圖會嘗試載入圖格。發生這種情況時，便會針對各圖格提出要求並等候回應，以阻止地圖提出其他要求而導致其他圖層轉譯變慢。指定圖格圖層的界限時，地圖便只會要求該界限方塊內的圖格。同理可證，若圖格圖層僅適用於特定縮放層級之間，請指定來源縮放的最小值和最大值。

範例

var tileLayer = new atlas.layer.TileLayer({
    tileUrl: 'myTileServer/{z}/{y}/{x}.png',
    bounds: [-101.065, 14.01, -80.538, 35.176],
    minSourceZoom: 1,
    maxSourceZoom: 10
});

底圖未顯示時使用空白地圖樣式

若地圖上覆蓋的圖層可完全遮住底圖，請考慮將地圖樣式設為 blank 或 blank_accessible，以免轉譯底圖。此作業的常見案例是，當底圖上覆蓋的完整地球圖格為完全透明或具有透明區域。

流暢建立影像或圖格圖層的動畫

若地圖上的一系列影像或圖格圖層要以動畫方式呈現。為每個影像或圖格圖層建立圖層，並變更不透明度，通常會比更新每個動畫幀的單一圖層來源更快。與其更新圖層中的來源，將不透明度設為零以隱藏圖層，且將不透明度設為大於零的值以顯示新圖層的做法效率較高。或者，您也可切換圖層的可見度，但務必將圖層的淡出持續時間設定為零，否則會以動畫方式顯示圖層，這會導致在顯示新圖層之前隱藏上一層，因而產生閃爍效果。

調整符號圖層的衝突偵測邏輯

符號圖層具有圖示和文字的兩個選項，稱為 allowOverlap 和 ignorePlacement。這兩個選項會指定符號的圖示或文字是否可相互重疊。當設定為 false 時，符號圖層轉譯各點時會執行計算，以確認是否會與圖層中其他已轉譯的符號相衝突，如果有衝突，則不要轉譯衝突的符號。此功能適用於改善地圖的雜亂狀態，並減少轉譯的物件數目。若將這些選項設為 false，則會跳過此衝突偵測邏輯，並轉譯地圖上的所有符號。調整此選項，以取得效能及使用者體驗的最佳組合。

叢集化大型的點資料集

若使用大型資料集，在特定縮放層級轉譯時可能有許多點會相互重疊，且只能看清一部分。叢集化流程可將鄰近點分為一組，且以一個叢集點作為代表。當使用者放大地圖時，叢集便會分解為個別的資料點。這可大幅減少必須轉譯的資料量、維持地圖簡潔，同時改善效能。 DataSource 類別具有在本機叢集化資料的選項。許多可產生向量圖格的工具也具有叢集選項。

此外，增加叢集半徑的大小也可改善效能。叢集半徑愈大，要追蹤及轉譯的叢集點則愈少。如需詳細資訊，請參閱 Web SDK 中的叢集點資料。

使用加權的叢集熱度圖

熱度圖圖層可輕鬆轉譯數萬個資料點。若資料集較大，請考慮在資料來源上啟用叢集化，使用較小的叢集半徑，並以叢集的 point_count 屬性作為熱度圖的權重。當叢集半徑大小只有數個像素時，所轉譯的熱度圖視覺差異不大。使用較大的叢集半徑可提升效能，但轉譯的熱度圖解析度可能會降低。

var layer = new atlas.layer.HeatMapLayer(source, null, {
   weight: ['get', 'point_count']
});

如需詳細資訊，請參閱群集和熱度圖圖層。

保持小量的映像資源

影像可新增至地圖影像原件，以轉譯符號圖層中的圖示或多邊形圖層中的圖樣。盡可能使用較小影像，以便降低必須下載的資料量，以及地圖影像原件中佔用的空間量。當要使用的符號圖層透過 size 選項縮放圖示時，請使用地圖上計劃顯示的最大影像，且不得超過此大小。這可確保轉譯高解析度的圖示，並盡可能減少所用資源。此外，SVG 也可作為簡單圖示影像的小型檔案格式。

最佳化運算式

資料驅動樣式運算式可提供彈性及功能，以便篩選和設定地圖資料的樣式。運算式有許多最佳化的方式。以下是一些秘訣。

降低篩選複雜度

篩選條件會針對資料來源的所有資料迴圈執行，並檢查各篩選條件是否皆符合篩選條件中的邏輯。複雜的篩選可能會導致效能問題。以下為幾項可能的因應策略。

若使用向量圖格，請將資料分成不同的來源圖層。
若使用 DataSource 類別，請將該資料分成不同的資料來源。請嘗試平衡資料來源數目與篩選條件的複雜度。資料來源過多時也會造成效能問題，因此您可能需要進行一些測試，找出最適合您的案例。
在圖層上使用複雜的篩選條件時，請考慮使用具有樣式表達式的多個圖層，以減少篩選複雜度。若可使用樣式表達式，則避免使用硬式編碼樣式建立許多圖層，因為大量圖層也可能導致效能問題。

確定運算式不會產生錯誤

運算式通常用於產生程式碼，以便在轉譯時執行計算或邏輯運算。請比照應用程式的其餘程式碼，確定計算及邏輯合理，不易發生錯誤。運算式中的錯誤會讓評估運算式時發生問題，進而導致效能降低及轉譯問題。

其中一個應注意的常見錯誤是，運算式已根據某個圖徵屬性，且所有圖徵可能皆未包含該屬性。例如下列程式碼使用運算式，將泡泡圖層的色彩屬性設為 myColor 圖徵的屬性。

var layer = new atlas.layer.BubbleLayer(source, null, {
    color: ['get', 'myColor']
});

若資料來源中的所有圖徵皆有 myColor 屬性，且該屬性的值為色彩，上述程式碼便可正常運作。若您可完整控制資料來源中的資料，且確定所有圖徵的屬性 myColor 皆使用有效的色彩，便不構成問題。話雖如此，若要確保此程式碼免於發生錯誤，則可搭配使用 case 運算式和運算式 has，以檢查圖徵是否具有 myColor 屬性。若有，便可使用 to-color 類型運算式，嘗試將該屬性值轉換為色彩。若色彩無效，則可使用後援色彩。下列程式碼示範如何執行這項作業，並將後援色彩設為綠色。

var layer = new atlas.layer.BubbleLayer(source, null, {
    color: [
        'case',

        //Check to see if the feature has a 'myColor' property.
        ['has', 'myColor'],

        //If true, try validating that 'myColor' value is a color, or fallback to 'green'. 
        ['to-color', ['get', 'myColor'], 'green'],

        //If false, return a fallback value.
        'green'
    ]
});

從最特定到最不特定排序布林運算式

使用包含多個條件式測試的布爾表達式時，藉由將條件式測試依照特定程度從高到低排序，以減少所需的條件式測試總數。

簡化運算式

運算式功能雖強大，且有時可能相當複雜。較不複雜的運算式評估速度會更快。例如：如需進行簡單比較，相較於 ['match', ['get', 'category'], 'restaurant', true, false] 這類比對運算式，使用 ['==', ['get', 'category'], 'restaurant'] 這類運算式更為適合。在此情況下，若所檢查的屬性為布林值，get 運算式更為簡單 ['get','isRestaurant']。

Web SDK 疑難排解

針對使用 Azure 地圖服務 Web SDK 開發時的某些常見問題，下列秘訣可供您進行偵錯。

載入 Web 控制項時，為何不會顯示地圖？

檢查事項：

請確定您已完成地圖中的驗證選項。如果沒有驗證，地圖會載入空白畫布，並在瀏覽器開發人員工具的網路索引標籤中傳回 401 錯誤。
請確定您有網際網路連線。
檢查主控台是否有瀏覽器開發人員工具的錯誤。某些錯誤可能會導致地圖無法轉譯。為您的應用程式偵錯。
請確定您是使用受支援的瀏覽器。

我的所有資料皆顯示於世界另一端，怎麼回事？

Azure 地圖服務 SDK 中的座標 (亦稱為位置) 符合地理空間產業標準格式 [longitude, latitude]。 Azure 地圖服務 SDK 中使用的核心資料格式，也是 GeoJSON 結構描述中定義座標的格式。若您的資料顯示於世界另一端，很可能是因為座標/位置資訊的經度與緯度值相反。

為何 Web 控制項中的 HTML 標記出現在錯誤位置？

檢查事項：

若標記要使用自訂內容，請確定 anchor 和 pixelOffset 選項正確無誤。依預設，內容底部中間會與地圖上的位置對齊。
確定已載入 Azure 地圖服務的 CSS 檔案。
檢查 HTML 標記 DOM 元素，查看您的應用程式是否有任何 CSS 已附加至該標記，且影響其位置。

為何符號圖層中的圖示或文字出現在錯誤位置？

檢查 anchor 和 offset 選項是否已正確設定，以和您想要與地圖上的座標對齊的影像或文字部分對齊。若符號位置只會在地圖旋轉時發生錯誤，請檢查 rotationAlignment 選項。根據預設，符號會隨著地圖檢視區一併旋轉，向使用者直立顯示。但根據具體情況需要，您也可以將 map 選項設定為 rotationAlignment 以鎖定地圖方向的符號。

若符號位置只會在地圖呈俯仰/傾斜角度時發生錯誤，請檢查 pitchAlignment 選項。依預設，當地圖呈俯仰或傾斜角度時，地圖檢視區中的符號會維持直立。但根據具體情況需要，您也可以將 map 選項設定為 pitchAlignment 以鎖定地圖俯仰的符號。

為何我的所有資料皆未出現在地圖上？

檢查事項：

檢查瀏覽器的開發人員工具主控台是否發生錯誤。
確定已建立資料來源並新增至地圖，而且資料來源已連接到先前新增至地圖的轉譯圖層。
在您的程式碼中新增斷點並逐步執行。確定資料已新增至資料來源，並將資料來源和圖層新增至地圖。
請嘗試從轉譯層移除資料驅動運算式。其中一個運算式可能包含錯誤，因而導致此問題。

沙箱模式的 iframe 可使用 Azure 地圖服務 Web SDK 嗎？

是。

取得支援

根據您的問題，以下為取得 Azure 地圖服務支援的幾種方式。

如何回報資料問題或位址問題？

使用 Azure 地圖服務意見反應網站回報問題。如需了解回報資料問題的詳細指示，請參閱提供資料意見反應給 Azure 地圖服務。

注意

提交的各項問題皆會產生唯一的 URL 以便追蹤。根據問題類型及確認變更正確所需的時間，解決時間有所不同。轉譯服務的每週更新會顯示這些變更，其他服務 (如地理編碼和路線規劃) 則為每月更新。

如何回報服務或 API 中的錯誤？

選取 [建立支援要求] 按鈕，在 Azure 的 [說明 + 支援] 頁面上回報問題。

哪裡可找到 Azure 地圖服務的技術說明？

如需了解 Azure 地圖服務 Power BI 視覺效果的相關問題，請連絡 Power BI 支援。
如需其他所有 Azure 地圖服務，請連絡 Azure 支援。
若對 Azure 地圖服務特定圖徵有疑問或意見，請使用 Azure 地圖服務開發人員論壇。

下一步

如需了解改善應用程式使用者體驗的其他秘訣，請參閱下列文章。

讓您的應用程式可供存取

深入了解 Azure 地圖服務和地理空間產業所使用的術語。

Azure 地圖服務字彙

共用方式為

Azure 地圖服務 Web SDK 最佳做法

安全性最佳做法

使用最新版本的 Azure 地圖服務

地圖初始載入最佳化

觀看地圖就緒事件

消極式載入 Azure 地圖服務 Web SDK

新增地圖的預留位置

在初始化時設定初始地圖樣式及相機選項

最佳化資料來源

大型資料集採用圖格式解決方案

將多個資料集合併為單一向量圖格來源

減少因資料更新而重新整理畫布的次數

避免非必要呼叫資料來源的 clear 函數

移除未使用的圖徵和屬性

使用不同的資料來源以快速變更資料

調整 GeoJSON 資料來源中的緩衝區和容錯選項

設定 GeoJSON 資料來源的最高縮放選項

盡量減少 GeoJSON 回應

使用 URL 存取原始 GeoJSON

最佳化轉譯圖層

一次建立圖層並重複使用

考慮使用泡泡圖層，而不是符號圖層

慎用 HTML 標記和快顯

合併圖層

建立流暢的符號圖層動畫

指定縮放層級範圍

指定圖格圖層界限和來源縮放範圍

底圖未顯示時使用空白地圖樣式

流暢建立影像或圖格圖層的動畫

調整符號圖層的衝突偵測邏輯

叢集化大型的點資料集

使用加權的叢集熱度圖

保持小量的映像資源

最佳化運算式

降低篩選複雜度

確定運算式不會產生錯誤

從最特定到最不特定排序布林運算式

簡化運算式

Web SDK 疑難排解

取得支援

下一步

意見反應

其他資源