2026 年 11 月 9 日，開發者「啾咪orJIUMI」在掘金分享了 Vue 3 + TypeScript 搭配高德地圖 JS API 2.0 與 Loca 2.0 的封裝實戰，內容涵蓋點位、區域、聚合、流光圖層與資訊窗體。這類文章在社羣上向來有穩定流量，原因很實際：幾乎每個做過後臺系統的前端，都碰過「老闆要在地圖上看到所有門市」這種需求。
封裝的核心：把地圖當成元件，不當 API 堆
這篇分享最值得看的，是它呈現的取捨方式。高德 JS API 本身功能齊全，但每個功能都是獨立的類別與事件系統：畫點用 AMap.Marker、畫區域用 Polygon、聚合要掛 MarkerCluster、視覺特效要再載 Loca。如果每個頁面各自呼叫，程式碼很快會變成一份散落各地的新手村筆記。
作者的解法是包一個 TMap 類別，把 initMap、setMapCenter、addMarkers、addPolygons、addCluster、openInfoWindow 等十幾個方法統一收口。頁面端的使用就收斂成三行：new TMap()、initMap 傳入容器與回呼、之後全部透過實例操作。底層用 @amap/amap-jsapi-loader 載入 AMap 2.0 與所需的 MouseTool、PolygonEditor、DistrictSearch 等外掛。
用日常比喻，這就像家裡的影音設備。電視、音響、機上盒各自都有遙控器，能用，但你最後一定會想買一隻萬用遙控器。封裝層就是那隻遙控器：功能沒有變多，換來的是「操作介面統一」與「換設備時不用重學」。
點位渲染的細節，藏在 offset 裡
文章中 addMarkers 的內部實作很短，但有一處很能反映實務經驗：建立 Marker 時設定 offset 為 Pixel(-14, -32)，並把原始資料塞進 extData。前者是讓自訂圖示的錨點對齊座標，而不是讓圖片左上角飄在定點旁邊；後者則是讓點擊事件回呼能直接拿到原始業務資料，頁面不必再維護一份座標與資料的對照表。
這些細節正是多數人第一次串地圖 API 時會踩的坑。封裝的價值之一，就是把踩過的坑固化成預設行為，團隊裡下一個接手的人不必再踩一次。同樣的道理也出現在其他前端領域，例如先前整理過的Vue 加 Three.js 大屏踩坑記，作者同樣把視覺小樣到資料邊界的經驗整理成可複用的判斷。
為什麼後臺系統特別需要這層封裝
把視角拉回工作現場。企業後臺的地圖需求有幾個共同特徵：點位數量常在數百到數萬之間（所以需要聚合）、區域要能畫也要能編輯（所以需要 MouseTool 與各種 Editor）、視覺上要「看起來有即時感」（所以需要 Loca 的流光與脈衝圖層）。這些需求會在不同頁面反覆出現，差別只在資料不同。
如果沒有統一封裝，每個頁面各自載入 API、各自管理圖層生命周期，第一個遇到的問題是記憶體洩漏：頁面切換後舊圖層沒清乾淨，地圖越用越卡。第二個問題是行為不一致：A 頁面的點擊彈窗跟 B 頁面的長得不一樣，使用者會以為是兩套系統。封裝層正好在這兩個層面收口，圖層的新增與移除（如 addPulseLayer 與 removePulseLayer 成對出現）與資訊窗體的開關，都由同一套介面負責。
作者也預告，後續會以這套封裝為基礎，逐項整理後臺地圖頁面的常用功能與範例，並補充底層實作思路。對正在評估要不要自建地圖封裝的團隊，這系列值得追蹤。
給工程師的三個實用判斷
從這篇實戰可以提煉幾個直接可用的原則。第一，封裝的粒度以「業務頁面會叫用的動作」為單位，而不是以 API 的類別為單位；addCluster 比「包一個 MarkerCluster」更貼近頁面需求。第二，回呼參數一律回傳原始業務資料（extData 模式），讓頁面邏輯與地圖邏輯保持分離。第三，載入器統一走 jsapi-loader 並集中宣告外掛清單，避免各頁面分散載入造成版本不一致。
地圖封裝不是新鮮題目，但每個團隊的地獄細節不同。這篇文章的價值在於把一套完整的清單攤開：初始化、樣式、點位、區域、聚合、特效、窗體，等於提供了一份封裝 API 的設計檢查表。照著盤點一次，比事後補洞劃算得多。