multi-map-engine
v1.0.0
Published
统一API的多地图引擎适配框架，支持Leaflet、OpenLayers、Cesium无缝切换
Maintainers
zhaofjReadme
multi-map-engine
统一API的多地图引擎适配框架，支持Leaflet、OpenLayers、Cesium无缝切换
特性
- 统一API: 一套代码适配多个地图引擎
- 无缝切换: 只需修改一行代码即可切换引擎
- 完整支持: 支持Leaflet(2D)、OpenLayers(2D)、Cesium(3D)
- TypeScript友好: 提供完整的类型定义
- 轻量级: 外部化依赖，按需引入
安装
npm install multi-map-engine还需要安装对应的地图引擎：
npm install leaflet ol cesium快速开始
使用 Leaflet
import { MapFactory } from 'multi-map-engine';
import 'leaflet/dist/leaflet.css';
const engine = MapFactory.create('leaflet');
engine.createMap('map', {
lng: 117.1205,
lat: 36.6509,
zoom: 12
});
engine.addLayer({
id: 'base-layer',
type: 'tile',
url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
attribution: '© OpenStreetMap'
});切换到 OpenLayers
import { MapFactory } from 'multi-map-engine';
import 'ol/ol.css';
// 只需改一行！
const engine = MapFactory.create('openlayers');
// 其他代码完全一样
engine.createMap('map', {
lng: 117.1205,
lat: 36.6509,
zoom: 12
});切换到 Cesium 3D
import { MapFactory } from 'multi-map-engine';
// 切换到 3D 地球 - 还是一样！
const engine = MapFactory.create('cesium');
engine.createMap('map', {
lng: 117.1205,
lat: 36.6509,
zoom: 12
});浏览器直接使用
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>multi-map-engine</title>
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css" />
<style>
#map { width: 100%; height: 100vh; }
</style>
</head>
<body>
<div id="map"></div>
<script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
<script type="module">
import { MapFactory } from 'https://unpkg.com/[email protected]/dist/index.js';
const engine = MapFactory.create('leaflet');
engine.createMap('map', {
lng: 117.1205,
lat: 36.6509,
zoom: 12
});
engine.addLayer({
id: 'osm',
type: 'tile',
url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
});
// 监听点击事件
engine.on('click', (e) => {
console.log('点击了地图:', e);
});
</script>
</body>
</html>API 文档
MapFactory
工厂类，用于创建地图引擎实例。
create(engineType)
创建地图引擎实例。
参数:
engineType(string|MapEngineType): 引擎类型'leaflet'- Leaflet 2D地图'openlayers'- OpenLayers 2D地图'cesium'- Cesium 3D地图
返回: IMapEngine - 地图引擎实例
示例:
const engine = MapFactory.create('leaflet');IMapEngine
统一接口的地图引擎实例。
createMap(containerId, options)
创建地图。
参数:
containerId(string): 容器DOM元素IDoptions(Object): 地图配置lng(number): 中心经度lat(number): 中心纬度zoom(number): 缩放级别minZoom(number): 最小缩放级别（可选）maxZoom(number): 最大缩放级别（可选）
addLayer(layerConfig)
添加图层。
参数:
layerConfig(Object): 图层配置id(string): 图层IDtype(string): 图层类型，支持 'tile'url(string): 瓦片URLattribution(string): 版权信息（可选）
setCenter(lng, lat, zoom)
设置地图中心。
参数:
lng(number): 经度lat(number): 纬度zoom(number): 缩放级别（可选）
getBounds()
获取地图范围。
返回: Object - 范围信息
minLng(number): 最小经度maxLng(number): 最大经度minLat(number): 最小纬度maxLat(number): 最大纬度
on(event, callback)
注册事件监听。
参数:
event(string): 事件名称，支持 'click', 'mousemove' 等callback(Function): 回调函数
destroy()
销毁地图实例。
引擎切换示例
import { MapFactory, MapEngineType } from 'multi-map-engine';
// 初始化
let engine = MapFactory.create(MapEngineType.LEAFLET);
engine.createMap('map', { lng: 117.1205, lat: 36.6509, zoom: 12 });
// 添加图层
engine.addLayer({
id: 'base-layer',
type: 'tile',
url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
});
// 监听事件
engine.on('click', (e) => {
console.log('地图点击:', e);
});
// 切换引擎（例如切换到3D）
function switchTo3D() {
engine.destroy();
engine = MapFactory.create(MapEngineType.CESIUM);
engine.createMap('map', { lng: 117.1205, lat: 36.6509, zoom: 12 });
engine.addLayer({
id: 'base-layer',
type: 'tile',
url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
});
engine.on('click', (e) => {
console.log('3D地图点击:', e);
});
}支持的地图引擎
Leaflet
- 轻量级开源2D地图库
- 文档: https://leafletjs.com/
OpenLayers
- 功能强大的2D地图库
- 文档: https://openlayers.org/
Cesium
- 开源3D地球引擎
- 文档: https://cesium.com/
注意事项
Cesium 配置
使用 Cesium 引擎时，需要确保正确配置资源路径：
window.CESIUM_BASE_URL = './node_modules/cesium/Build/Cesium/';或在构建时配置 webpack 复制 Cesium 资源文件。
样式引入
不同引擎需要引入对应的CSS：
// Leaflet
import 'leaflet/dist/leaflet.css';
// OpenLayers
import 'ol/ol.css';
// Cesium
import 'cesium/Build/Cesium/Widgets/widgets.css';开源协议
贡献
欢迎提交 Issue 和 Pull Request！
更新日志
1.0.0 (2024-XX-XX)
- 初始版本发布
- 支持 Leaflet、OpenLayers、Cesium
- 统一的API接口
- 完整的事件系统