簡介
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 類別前綴
});
核心配置選項完整表
| 選項 | 類型 | 預設 | 說明 |
| id | string | - | 目標 <img> 元素 ID (必填) |
| width | number | 圖片寬度 | 視窗寬度 (px) |
| height | number | 圖片高度 | 視窗高度 (px) |
| startX | number | 0 | 初始視窗中心 X 座標 (圖片座標系) |
| startY | number | 0 | 初始視窗中心 Y 座標 |
| cssClass | string | 'sprymap' | 生成容器的 CSS 類別前綴 |
| smooth | boolean | true | 是否啟用平滑拖拽動畫 |
| zoom | number | 1 | 初始縮放比例 |
| minZoom | number | 0.5 | 最小縮放 |
| maxZoom | number | 3 | 最大縮放 |
| showNavigation | boolean | false | 顯示內建導航控制器 |
| onMove | function | null | 拖拽/移動時回調 fn(x, y, zoom) |
| onZoom | function | null | 縮放時回調 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 JS | WebGL 渲染、向量瓦片、視覺效果極佳 | 高顏值商業地圖、3D |
| Panzoom | 通用平移縮放、無地圖概念、支援任意元素 | 圖片查看器、圖表、圖紙 |
總結
SpryMap 以「零依賴、極簡 API」切入輕量大圖拖拽需求,適合快速整合、舊專案、無建構流程環境。現代專案若涉及地理座標、瓦片圖層、大量標記、移動端觸控,建議直接上 Leaflet 或 Mapbox GL JS。理解其「容器裁切 + 內層位移/縮放」核心原理,有助於自行實作客製化圖片查看器。