ArcGIS API 地圖初始化寬高異常：CSS 布局與 API 生命週期衝突解析

現象描述

開發者設置地圖容器 div 寬高，但調用 new Map() 初始化後，地圖實際渲染尺寸變為 400px × 400px。

根本原因：CSS 布局未就緒時初始化

ArcGIS API for JavaScript 在構造 Map 時，會立即讀取容器元素的 offsetWidth/offsetHeight。若此時：

• 容器 display: none
• 父元素未渲染完成
• CSS 彈性布局未計算出確定尺寸
• 圖片/字體加載導致回流未結束

則獲取到的尺寸為 0 或默認值，API 內部回退到默認 400×400。

解決方案矩陣

最佳實踐：生命週期同步初始化

// HTML

    



// CSS
#map { width: 100%; height: 100%; }

// JS - 確保 DOM 就緒
require(["esri/Map", "esri/views/MapView", "dojo/domReady!"], 
    function(Map, MapView) {
        const map = new Map({ basemap: "topo-vector" });
        const view = new MapView({
            container: "map",
            map: map,
            center: [116.39, 39.9],
            zoom: 10
        });
        
        // 響應式 resize
        window.addEventListener('resize', () => {
            view.resize(); // 4.x API 使用 view.resize()
        });
    }
);

常見坑點排查清單

1. 容器顯示性：display: none 會導致尺寸 0，改用 visibility: hidden 或延遲初始化
2. 父級高度塌陷：百分比高度要求父元素有確定高度，鏈式追溯到 html, body { height: 100% }
3. Box-sizing 影響：border-box 導致內容區縮小，設置 box-sizing: content-box 或調整 padding
4. 多實例衝突：同頁多地圖需分別監聽 resize
5. API 版本差異：3.x 用 map.resize()，4.x 用 view.resize()

調試技巧

// 初始化前檢查容器尺寸
const container = document.getElementById('map');
console.log('Container size:', container.offsetWidth, container.offsetHeight);

// 監聽地圖載入事件
view.when(() => {
    console.log('View size:', view.width, view.height);
    console.log('Map loaded');
});

總結

ArcGIS 地圖初始化尺寸異常，核心在於CSS 布局計算滞後於 JS 執行。解決關鍵：CSS 顯式尺寸 + DOM 就緒初始化 + resize 事件響應。理解「容器尺寸確定 → API 讀取尺寸 → 渲染地圖」這一時序依賴，配合現代前端框架（Vue/React）的掛載鉤子（mounted/useEffect），可徹底避免此類問題。