@ctrs/mapload-utils/utils-npm

A Clean and Powerful Leaflet Toolkit for Fast Map Creation

安装

# 使用前先下载leaflet 并在项目中引入leaflet和样式 全局引入leaflet.css
npm install leaflet

# 安装本工具
npm install @ctrs/mapload-utils/utils-npm

枚举对象

为了方便使用和避免拼写错误，提供了两个枚举对象：MapLoadEnum 和 MapDownloadEnum。

MapLoadEnum（地图加载枚举）

const { MapLoadEnum } = require('@ctrs/mapload-utils');

/**
 * 地图类型
 */
MapLoadEnum.MapType
// 值：'TianDiTu', 'GaoDe', 'Google', 'Geoq', 'Yandex', 'MapBox', 'MapABC', 'OpenStreetMap', 'OSM', 'Offline'

/**
 * 地图模式
 */
MapLoadEnum.MapMode
// 值：{ NORMAL: 'normal', SATELLITE: 'satellite' }

/**
 * 坐标类型
 */
MapLoadEnum.CoordType
// 值：{ WGS84: 'wgs84', GCJ02: 'gcj02', BD09: 'bd09' }

MapDownloadEnum（地图下载枚举）

const { MapDownloadEnum } = require('@ctrs/mapload-utils');

/**
 * 地图提供商
 */
MapDownloadEnum.Provider
// 值：{ OPEN_STREET_MAP: 'OpenStreetMap', YANDEX: 'Yandex', GAO_DE: 'GaoDe', GOOGLE: 'Google' }

/**
 * 地图类型
 */
MapDownloadEnum.MapType
// 值：{ NORMAL: 'Normal.Map', SATELLITE: 'Satellite.Map' }

/**
 * 下载状态
 */
MapDownloadEnum.Status
// 值：{ DOWNLOADING: 'downloading', PAUSED: 'paused', COMPLETED: 'completed', CANCELLED: 'cancelled' }

基本使用

Node.js 环境使用

const { loadMap, MapLoadEnum } = require('@ctrs/mapload-utils');

// 创建地图（使用枚举）
const map = loadMap('mapContainer', MapLoadEnum.MapType.GAO_DE, {
  center: [39.9042, 116.4074], // 地图中心点 [纬度, 经度]
  zoom: 15, // 初始缩放级别
  mapMode: MapLoadEnum.MapMode.NORMAL // 地图模式：NORMAL 平面图, SATELLITE 卫星图
});

// 创建地图并显式指定坐标系
const map2 = loadMap('mapContainer', MapLoadEnum.MapType.GOOGLE, {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: MapLoadEnum.MapMode.NORMAL,
  corrdType: MapLoadEnum.CoordType.WGS84 // 强制使用 WGS84 坐标系
});

使用枚举加载地图示例

const { loadMap, MapLoadEnum } = require('@ctrs/mapload-utils');

// 使用高德地图 - 平面图
const map1 = loadMap('mapContainer', MapLoadEnum.MapType.GAO_DE, {
  mapMode: MapLoadEnum.MapMode.NORMAL,
  center: [39.9042, 116.4074],
  zoom: 15
});

// 使用高德地图 - 卫星图
const map2 = loadMap('mapContainer', MapLoadEnum.MapType.GAO_DE, {
  mapMode: MapLoadEnum.MapMode.SATELLITE,
  center: [39.9042, 116.4074],
  zoom: 15
});

// 使用离线地图 - 指定坐标系
const map3 = loadMap('mapContainer', MapLoadEnum.MapType.OFFLINE, {
  offlineTileUrl: 'http://localhost:8080/tiles/{z}/{x}/{y}.png',
  offlineCoordType: MapLoadEnum.CoordType.GCJ02,
  center: [39.9042, 116.4074],
  zoom: 15
});

// 使用谷歌地图 - 显式指定坐标系
const map4 = loadMap('mapContainer', MapLoadEnum.MapType.GOOGLE, {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: MapLoadEnum.MapMode.NORMAL,
  corrdType: MapLoadEnum.CoordType.WGS84 // 强制使用 WGS84 坐标系
});

使用枚举下载地图示例

const { downloadMap, MapDownloadEnum } = require('@ctrs/mapload-utils');

// 使用枚举下载地图
const downloadControl = downloadMap({
  provider: MapDownloadEnum.Provider.GAO_DE,           // 地图提供商
  mapType: MapDownloadEnum.MapType.NORMAL,             // 地图类型：平面图
  minZoom: 15,
  maxZoom: 15,
  bounds: {
    minLat: 39.90,
    maxLat: 39.92,
    minLng: 116.35,
    maxLng: 116.37
  },
  outputDir: './download',
  onProgress: (progress) => {
    console.log(`进度: ${progress.progress}% (${progress.status})`);
  }
});

// 根据下载状态枚举处理不同状态
downloadControl.getPromise().then(result => {
  if (result.cancelled) {
    console.log('下载已取消');
  } else {
    console.log(`下载完成: ${result.downloaded}/${result.total}`);
  }
});

浏览器环境使用

如果在浏览器环境中使用，可以通过以下方式导入：

<!-- 先引入 Leaflet -->
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css" />
<script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>

<!-- 然后引入本模块 -->
<script src="./index.js"></script>

<script>
  // 在浏览器环境中，模块会暴露到全局变量 window.MaploadUtils
  const { loadMap, MapLoadEnum, MapDownloadEnum, downloadMap } = window.MaploadUtils;
  
  // 使用枚举创建地图
  const map = loadMap('mapContainer', MapLoadEnum.MapType.GAO_DE, {
    center: [39.9042, 116.4074],
    zoom: 15,
    mapMode: MapLoadEnum.MapMode.NORMAL
  });

  // 创建地图并显式指定坐标系
  const map2 = loadMap('mapContainer', MapLoadEnum.MapType.GOOGLE, {
    center: [39.9042, 116.4074],
    zoom: 15,
    mapMode: MapLoadEnum.MapMode.NORMAL,
    corrdType: MapLoadEnum.CoordType.WGS84 // 强制使用 WGS84 坐标系
  });
</script>

支持的地图类型

| 地图类型 | 支持模式 | 坐标系 | 说明 | |---------|---------|--------|------| | TianDiTu | 平面图、卫星图、地形图、云南地图 | wgs84 | 天地图 | | GaoDe | 平面图、卫星图 | gcj02 | 高德地图 | | Google | 平面图、卫星图 | wgs84 | 谷歌地图（支持备用 URL 切换） | | Geoq | 平面图（多种风格）| gcj02 | Geoq 地图 | | Yandex | 平面图、卫星图 | wgs84 | Yandex 地图 | | MapBox | 平面图 | wgs84 | MapBox 地图 | | MapABC | 平面图 | gcj02 | MapABC 地图 | | OpenStreetMap | 平面图、卫星图 | wgs84 | OpenStreetMap | | Offline | 自定义 | 自定义 | 离线地图 |

每种地图的使用示例

1. 天地图

// 天地图 - 平面图
const map = loadMap('mapContainer', 'TianDiTu', {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: 'normal'
});

// 天地图 - 卫星图
const map = loadMap('mapContainer', 'TianDiTu', {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: 'satellite'
});

2. 高德地图

// 高德地图 - 平面图
const map = loadMap('mapContainer', 'GaoDe', {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: 'normal'
});

// 高德地图 - 卫星图
const map = loadMap('mapContainer', 'GaoDe', {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: 'satellite'
});

3. 谷歌地图

谷歌地图支持自动备用 URL 切换功能。当主 URL 加载失败时，会自动尝试备用 URL，如果所有 Google URL 都不可用，最后会切换到 OpenStreetMap。

// 谷歌地图 - 平面图（自动判断是否需要纠偏，支持备用 URL）
const map = loadMap('mapContainer', 'Google', {
  center: [39.9042, 116.4074], // 中国境内，自动使用 gcj02 坐标系
  zoom: 15,
  mapMode: 'normal'
});

// 谷歌地图 - 卫星图（自动判断是否需要纠偏，支持备用 URL）
const map = loadMap('mapContainer', 'Google', {
  center: [40.7128, -74.0060], // 国外，自动使用 wgs84 坐标系
  zoom: 15,
  mapMode: 'satellite'
});

// 谷歌地图 - 显式指定坐标系（优先使用 corrdType 参数）
const map = loadMap('mapContainer', 'Google', {
  center: [39.9042, 116.4074], // 中国境内，但强制使用 wgs84 坐标系
  zoom: 15,
  mapMode: 'normal',
  corrdType: 'wgs84' // 显式指定坐标系，优先级高于自动判断
});

4. Geoq 地图

// Geoq 地图 - 平面图
const map = loadMap('mapContainer', 'Geoq', {
  center: [39.9042, 116.4074],
  zoom: 15
});

5. Yandex 地图

// Yandex 地图 - 平面图
const map = loadMap('mapContainer', 'Yandex', {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: 'normal'
});

// Yandex 地图 - 卫星图
const map = loadMap('mapContainer', 'Yandex', {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: 'satellite'
});

6. MapBox 地图

// MapBox 地图
const map = loadMap('mapContainer', 'MapBox', {
  center: [39.9042, 116.4074],
  zoom: 15
});

7. MapABC 地图

// MapABC 地图
const map = loadMap('mapContainer', 'MapABC', {
  center: [39.9042, 116.4074],
  zoom: 15
});

8. OpenStreetMap

// OpenStreetMap - 平面图
const map = loadMap('mapContainer', 'OpenStreetMap', {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: 'normal'
});

// OpenStreetMap - 卫星图
const map = loadMap('mapContainer', 'OpenStreetMap', {
  center: [39.9042, 116.4074],
  zoom: 15,
  mapMode: 'satellite'
});

9. 离线地图

// 离线地图 - WGS84 坐标系
const map = loadMap('mapContainer', 'Offline', {
  center: [39.9042, 116.4074],
  zoom: 15,
  offlineTileUrl: 'http://localhost:8080/tiles/{z}/{x}/{y}.png',
  offlineCoordType: 'wgs84'
});

// 离线地图 - GCJ02 坐标系
const map = loadMap('mapContainer', 'Offline', {
  center: [39.9042, 116.4074],
  zoom: 15,
  offlineTileUrl: 'http://localhost:8080/tiles/{z}/{x}/{y}.png',
  offlineCoordType: 'gcj02'
});

// 离线地图 - BD09 坐标系
const map = loadMap('mapContainer', 'Offline', {
  center: [39.9042, 116.4074],
  zoom: 15,
  offlineTileUrl: 'http://localhost:8080/tiles/{z}/{x}/{y}.png',
  offlineCoordType: 'bd09'
});

参数说明

必需参数

• containerId - DOM 容器 ID（字符串）
• mapType - 地图类型（字符串）

可选参数

• options.center - 地图中心点，默认 [39.9042, 116.4074]
• options.zoom - 初始缩放级别，默认 13
• options.mapMode - 地图模式，默认 'normal'（'normal' 平面图, 'satellite' 卫星图）
• options.offlineTileUrl - 离线地图瓦片 URL（仅 mapType='Offline' 时使用）
• options.offlineCoordType - 离线地图坐标类型，默认 'wgs84'（'gcj02', 'bd09', 'wgs84'）
• options.corrdType - 坐标系类型，优先使用此参数，未提供时根据地图类型自动判断（'gcj02', 'bd09', 'wgs84'）

特殊功能

1. 智能纠偏

• 谷歌地图：根据中心位置自动判断是否在中国境内，中国境内使用 gcj02 坐标系，国外使用 wgs84 坐标系
• 其他地图：根据地图类型固定使用对应坐标系
• 自定义坐标系：可通过 corrdType 参数显式指定坐标系类型，优先级高于自动判断

2. 自动清理

• 当多次调用 loadMap 使用同一个容器时，会自动清理已存在的地图实例，避免重复初始化错误

3. 离线地图支持

• 支持自定义瓦片 URL 和坐标系类型
• 可根据离线地图的实际坐标系选择合适的 offlineCoordType

坐标系说明

| 坐标系 | 适用地图 | 说明 | |---------|---------|------| | wgs84 | TianDiTu, Yandex, OSM, 国外 Google | 标准 WGS84 坐标系 | | gcj02 | GaoDe, Geoq, Tencent, 国内 Google | 火星坐标系（中国标准） | | bd09 | Baidu | 百度坐标系 |

地图瓦片操作

1. getTileUrl 方法

用于获取指定地图提供商的瓦片 URL，可用于地图下载等场景。

const { getTileUrl } = require('@ctrs/mapload-utils');

// 获取高德地图瓦片 URL
const gaodeUrl = getTileUrl('GaoDe', 'Normal.Map', 15, 12345, 67890);
console.log('高德地图瓦片 URL:', gaodeUrl);

// 获取谷歌地图瓦片 URL
const googleUrl = getTileUrl('Google', 'Satellite.Map', 10, 1000, 2000);
console.log('谷歌地图瓦片 URL:', googleUrl);

// 获取 Yandex 地图瓦片 URL
const yandexUrl = getTileUrl('Yandex', 'Normal.Map', 12, 5000, 8000);
console.log('Yandex 地图瓦片 URL:', yandexUrl);

// 获取 OpenStreetMap 瓦片 URL
const osmUrl = getTileUrl('OpenStreetMap', 'Satellite.Map', 8, 100, 200);
console.log('OpenStreetMap 瓦片 URL:', osmUrl);

参数说明

• provider - 地图提供商（'OpenStreetMap', 'Yandex', 'GaoDe', 'Google'）
• mapType - 地图类型（'Normal.Map' 平面图, 'Satellite.Map' 卫星图）
• z - 缩放级别
• x - 瓦片 X 坐标
• y - 瓦片 Y 坐标

返回值

• 瓦片图片的完整 URL

2. downloadMap 方法

用于批量下载地图瓦片，使用经纬度边界（四点位）指定下载范围。

使用示例

const { downloadMap } = require('@ctrs/mapload-utils/utils-npm');

function downloadWithControl() {
  // 定义经纬度边界（例如：北京市中心区域）
  const bounds = {
    minLat: 39.90,  // 最小纬度
    maxLat: 39.95,  // 最大纬度
    minLng: 116.35, // 最小经度
    maxLng: 116.45  // 最大经度
  };
  
  // 开始下载并获取控制对象
  const downloadControl = downloadMap({
    provider: 'GaoDe',
    mapType: 'Normal.Map',
    minZoom: 12,
    maxZoom: 14,
    bounds: bounds,  // 直接传入经纬度边界
    outputDir: './downloaded_maps/beijing',
    onProgress: (progress) => {
      console.log(`下载进度: ${progress.progress}% (${progress.downloaded}/${progress.total})`);
      if (progress.current) {
        console.log(`当前下载: z=${progress.current.z}, x=${progress.current.x}, y=${progress.current.y}`);
      }
      console.log(`下载状态: ${progress.status}`);
    },
    onError: (error, tile) => {
      console.error(`下载瓦片失败 (${tile.z}, ${tile.x}, ${tile.y}):`, error.message);
    }
  });

  // 示例：5秒后暂停下载
  setTimeout(() => {
    console.log('暂停下载...');
    downloadControl.pause();
  }, 5000);

  // 示例：10秒后恢复下载
  setTimeout(() => {
    console.log('恢复下载...');
    downloadControl.resume();
  }, 10000);

  // 示例：15秒后取消下载
  // setTimeout(() => {
  //   console.log('取消下载...');
  //   downloadControl.cancel();
  // }, 15000);

  // 获取下载状态
  setInterval(() => {
    const status = downloadControl.getStatus();
    console.log(`当前状态: ${status}`);
  }, 2000);

  // 等待下载完成
  downloadControl.getPromise().then(result => {
    console.log('下载完成:', result);
  }).catch(error => {
    console.error('下载失败:', error.message);
  });
}

downloadWithControl();

3. latLngBoundsToTileBounds 方法

用于将经纬度范围转换为瓦片坐标范围，适用于只有经纬度点位的场景。

const { latLngBoundsToTileBounds } = require('@ctrs/mapload-utils/utils-npm');

// 定义经纬度范围（例如：北京市中心区域）
const bounds = {
  minLat: 39.90,
  maxLat: 39.95,
  minLng: 116.35,
  maxLng: 116.45
};

// 计算不同缩放级别的瓦片范围
const zoom = 12;
const tileBounds = latLngBoundsToTileBounds(bounds, zoom);
console.log('瓦片坐标范围:', tileBounds);

// 计算其他缩放级别的瓦片范围
const zoom10 = 10;
const tileBounds10 = latLngBoundsToTileBounds(bounds, zoom10);
console.log('缩放级别 10 的瓦片坐标范围:', tileBounds10);

// 计算缩放级别 14 的瓦片范围
const zoom14 = 14;
const tileBounds14 = latLngBoundsToTileBounds(bounds, zoom14);
console.log('缩放级别 14 的瓦片坐标范围:', tileBounds14);

参数说明

downloadMap 参数

• options.provider - 地图提供商（'OpenStreetMap', 'Yandex', 'GaoDe', 'Google'）
• options.mapType - 地图类型（'Normal.Map' 平面图, 'Satellite.Map' 卫星图）
• options.minZoom - 最小缩放级别
• options.maxZoom - 最大缩放级别
• options.bounds - 经纬度边界对象：
  • minLat - 最小纬度
  • maxLat - 最大纬度
  • minLng - 最小经度
  • maxLng - 最大经度
• options.outputDir - 输出目录
• options.onProgress - 进度回调函数（可选）
• options.onError - 错误回调函数（可选）

latLngBoundsToTileBounds 参数

• bounds - 经纬度边界对象：
  • minLat - 最小纬度
  • maxLat - 最大纬度
  • minLng - 最小经度
  • maxLng - 最大经度
• zoom - 缩放级别

返回值

downloadMap 返回值

• 返回下载控制对象，包含以下方法：
  • pause() - 暂停下载
  • resume() - 恢复下载
  • cancel() - 取消下载
  • getStatus() - 获取当前下载状态
  • getPromise() - 获取下载 Promise，resolve 后返回下载结果对象：
    • downloaded - 成功下载的瓦片数
    • total - 总瓦片数
    • cancelled - 是否被取消

latLngBoundsToTileBounds 返回值

• 返回瓦片坐标范围对象：
  • minX - 最小 X 坐标
  • maxX - 最大 X 坐标
  • minY - 最小 Y 坐标
  • maxY - 最大 Y 坐标

下载目录结构

下载的瓦片会按照以下目录结构组织：

outputDir/
├── 10/           # 缩放级别
│   ├── 5000/     # X 坐标
│   │   ├── 2000.png  # Y 坐标
│   │   ├── 2001.png
│   │   └── ...
│   ├── 5001/
│   └── ...
├── 11/
└── 12/

版本管理

如果修改了代码，需要更新版本并发布：

# 升版本
npm version patch

# 上传命令
npm publish --access public