萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

SpryMap 輕量級地圖拖拽庫:獨立無依賴、Google Maps 風格交互

簡介

SpryMap 是一個**零依賴**、輕量級 (壓縮後約 3KB) 的 JavaScript 地圖拖拽庫,不依賴 jQuery/Prototype 等框架,可輕鬆實現類 Google Maps/百度地圖的平移、縮放、標記功能,適合大圖瀏覽、平面圖導覽、簡易 GIS 應用。

快速開始

1. 引入腳本

<script src="spryMap-min.js"></script>
<!-- 或 ES Module -->
<script type="module">
import SpryMap from './spryMap.esm.js';
</script>

2. HTML 結構

<div id="map-container" style="width: 800px; height: 400px; overflow: hidden; position: relative;">
    <img id="worldMap" src="map.jpg" alt="大圖">
</div>

3. 初始化

const map = new SpryMap({
    id: 'worldMap',        // 目標圖片 ID (必填)
    width: 800,            // 視窗寬度
    height: 400,           // 視窗高度
    startX: 200,           // 初始中心點 X (圖片座標)
    startY: 200,           // 初始中心點 Y
    cssClass: 'mappy'      // 容器 CSS 類別前綴
});

核心配置選項完整表

選項類型預設說明
idstring-目標 <img> 元素 ID (必填)
widthnumber圖片寬度視窗寬度 (px)
heightnumber圖片高度視窗高度 (px)
startXnumber0初始視窗中心 X 座標 (圖片座標系)
startYnumber0初始視窗中心 Y 座標
cssClassstring'sprymap'生成容器的 CSS 類別前綴
smoothbooleantrue是否啟用平滑拖拽動畫
zoomnumber1初始縮放比例
minZoomnumber0.5最小縮放
maxZoomnumber3最大縮放
showNavigationbooleanfalse顯示內建導航控制器
onMovefunctionnull拖拽/移動時回調 fn(x, y, zoom)
onZoomfunctionnull縮放時回調 fn(zoom)

API 方法

方法參數說明
moveTo(x, y, animate)number, number, boolean移動視窗中心到圖片座標 (x,y)
zoomTo(level, animate)number, boolean設定縮放等級
zoomIn/zoomOut()-放大/縮小一級
getCenter()-回傳 {x, y} 當前中心座標
getZoom()-回傳當前縮放比例
addMarker(id, x, y, html)string, number, number, string添加標記 (HTML 字串)
removeMarker(id)string移除標記
destroy()-銷毀實例、恢復原圖

完整範例:帶標記、導航、事件監聽

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>SpryMap Demo</title>
    <style>
        #map-wrap { width: 100%; max-width: 1000px; margin: 0 auto; }
        #map-container { width: 100%; height: 500px; border: 1px solid #ddd; }
        .info { margin-top: 10px; padding: 10px; background: #f5f5f5; font-family: monospace; }
        .marker { 
            position: absolute; 
            padding: 4px 8px; 
            background: rgba(255,0,0,0.8); 
            color: white; 
            border-radius: 4px; 
            font-size: 12px; 
            white-space: nowrap;
            transform: translate(-50%, -100%);
            pointer-events: none;
        }
    </style>
</head>
<body>
    <div id="map-wrap">
        <div id="map-container"></div>
    </div>
    <div class="info" id="info">載入中...</div>

    <script src="spryMap-min.js"></script>
    <script>
        const map = new SpryMap({
            id: 'mapImg', // 注意:需在容器內有此 ID 的 img
            width: 800,
            height: 500,
            startX: 1000,
            startY: 800,
            smooth: true,
            zoom: 1,
            minZoom: 0.3,
            maxZoom: 4,
            showNavigation: true,
            onMove: (x, y, z) => updateInfo(x, y, z),
            onZoom: (z) => updateInfo(null, null, z)
        });

        // 動態建立圖片元素 (SpryMap 會尋找 id="mapImg")
        const img = new Image();
        img.id = 'mapImg';
        img.src = 'large-map.jpg'; // 大圖 (如 3000x2000)
        document.getElementById('map-container').appendChild(img);

        // 添加標記
        map.addMarker('poi1', 1200, 900, '📍 台北 101');
        map.addMarker('poi2', 800, 600, '🏛️ 故宮');

        function updateInfo(x, y, z) {
            document.getElementById('info').textContent = 
                `中心: ${x?.toFixed(0) ?? '?'}, ${y?.toFixed(0) ?? '?'} | 縮放: ${z?.toFixed(2) ?? '?'}`;
        }
    </script>
</body>
</html>

原理分析

  • DOM 結構:建立外層容器 overflow:hidden,內層 position:absolute 承載大圖與標記。
  • 拖拽:mousedown 記錄起始點 → mousemove 計算位移 → 更新內層 left/top 或 transform: translate()。
  • 縮放:滾輪/雙擊/按鈕觸發 → 修改 scale() → 同時調整座標映射保持視覺中心不變。
  • 平滑動畫:requestAnimationFrame 插值過渡。

遷移與替代方案

方案特點適用場景
SpryMap零依賴、極輕量、API 簡單簡單大圖瀏覽、舊專案、無建構工具環境
Leaflet標準地圖庫、插件豐富、支援瓦片圖層真實地理地圖、GIS 應用
OpenLayers功能最強、企業級、學習曲線陡專業 GIS、空間分析
Mapbox GL JSWebGL 渲染、向量瓦片、視覺效果極佳高顏值商業地圖、3D
Panzoom通用平移縮放、無地圖概念、支援任意元素圖片查看器、圖表、圖紙

總結

SpryMap 以「零依賴、極簡 API」切入輕量大圖拖拽需求,適合快速整合、舊專案、無建構流程環境。現代專案若涉及地理座標、瓦片圖層、大量標記、移動端觸控,建議直接上 Leaflet 或 Mapbox GL JS。理解其「容器裁切 + 內層位移/縮放」核心原理,有助於自行實作客製化圖片查看器。

copyright © 萬盛學電腦網 all rights reserved