地图 SDK

基于 Mapbox GL JS 的轻量级地图开发工具包，专为 UniApp 应用提供基础地图功能。

主要特性

• 🗺️ 基础地图功能: 地图移动、缩放、旋转、底图切换
• 🎬 丰富动画效果: 提供 6 种动画过渡（flyTo、easeTo、jumpTo、panTo、zoomTo、rotateTo）
• 🏔️ 3D 地形支持: 支持添加和移除 3D 地形效果
• 📐 面积计算: 基于 turf.js 的精确面积、周长和中心点计算
• ✏️ 区域绘制: 支持多边形绘制、编辑和管理
• 📱 UniApp 完美兼容: 支持 WebView 与 App 的双向通信
• 🔧 事件系统: 统一的事件订阅机制
• 🎈 弹窗功能: 内置 Popup 弹窗支持

系统要求

• Android: 7.0 及以上
• iOS: 13.0 及以上
• 浏览器: Chrome、Edge、360、UC、Firefox（Chromium 66.0+）
• 坐标系: WGS84 (EPSG:4326)

快速开始

安装

npm install map-sdk

基础用法

import MapSDK from "map-sdk";
import "map-sdk/style.css";

// 创建 SDK 实例
const mapSDK = new MapSDK({
  container: "map-container",
  style: {
    name: "OpenStreetMap",
    tiles: "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    tileSize: 256,
    maxzoom: 19,
  },
  center: [116.404, 39.915],
  zoom: 10,
  draw: true, // 启用绘制功能
});

// 初始化地图
const mapInstance = await mapSDK.initialize();

核心功能

1. 地图基础操作

// 设置中心点
mapInstance.setCenter([120.1551, 30.2741]);

// 设置缩放级别
mapInstance.setZoom(14);

// 飞行动画
mapInstance.flyTo({
  center: [121.4737, 31.2304],
  zoom: 12,
  duration: 2000,
});

2. 3D 地形

// 添加地形
mapInstance.addTerrain({
  name: "NASA 地形",
  tiles: ["https://your-tiles/3dterrain/nasa/tiles/{z}/{x}/{y}.png"],
  tileSize: 512,
  exaggeration: 1.5,
});

// 移除地形
mapInstance.removeTerrain();

3. 区域绘制

// 开始绘制多边形
mapInstance.drawPolygon();

// 监听绘制完成
mapInstance.on("draw:create", (feature) => {
  console.log("绘制完成:", feature);
});

4. 面积和中心点计算

这是 SDK 的核心功能之一，基于 turf.js 库实现精确的地理计算。

计算单个多边形

// 获取选中的多边形
const selected = mapInstance.getSelectedFeatures();
const feature = selected.features[0];

// 计算面积（平方米）
const area = mapInstance.calculateFeatureArea(feature);
console.log(`面积: ${(area / 1000000).toFixed(2)} km²`);

// 计算周长（米）
const perimeter = mapInstance.calculateFeaturePerimeter(feature);
console.log(`周长: ${(perimeter / 1000).toFixed(2)} km`);

获取完整信息

// 通过要素 ID 获取完整信息
const info = mapInstance.getFeatureInfo("polygon-id-123");

if (info) {
  console.log(`面积: ${info.area} m²`);
  console.log(`周长: ${info.perimeter} m`);
  console.log(`中心点: [${info.center[0]}, ${info.center[1]}]`);
  
  // 在中心点显示弹窗
  mapInstance.showPopup(
    info.center,
    `<div>
      <h3>多边形信息</h3>
      <p>面积: ${(info.area / 1000000).toFixed(2)} km²</p>
      <p>周长: ${(info.perimeter / 1000).toFixed(2)} km</p>
    </div>`
  );
}

计算所有多边形的总面积

const allFeatures = mapInstance.getAllFeatures();
let totalArea = 0;

allFeatures.features.forEach(feature => {
  const area = mapInstance.calculateFeatureArea(feature);
  totalArea += area;
});

console.log(`总面积: ${(totalArea / 1000000).toFixed(2)} km²`);

5. 高级地理计算

SDK 提供了对 turf.js 库的直接访问，支持更多高级地理计算：

const turf = MapSDK.getTurf();

// 计算两点距离
const point1 = turf.point([116.404, 39.915]);
const point2 = turf.point([121.473, 31.230]);
const distance = turf.distance(point1, point2, { units: "kilometers" });

// 判断点是否在多边形内
const isInside = turf.booleanPointInPolygon(point, polygon);

// 创建缓冲区
const buffered = turf.buffer(point, 5, { units: "kilometers" });

// 合并多边形
const union = turf.union(polygon1, polygon2);

// 计算边界框
const bbox = turf.bbox(feature);

示例文件

项目包含多个示例文件，展示不同功能的使用：

• sdk-test/demo-area-calculation.html - 面积和中心点计算示例
• sdk-test/demo-draw.html - 区域绘制示例
• sdk-test/demo-error-handling.html - 错误处理示例
• sdk-test/index.html - 基础功能示例

文档

详细文档请参考：

• 基础功能与通信文档 - 完整的 API 文档和使用指南
• 测试使用文档 - 测试和开发指南
• 构建文档 - 构建和部署说明

UniApp 集成

<template>
  <web-view src="http://your-map-url/" @message="handleMessage"></web-view>
</template>

<script>
export default {
  methods: {
    sendToMap(action, data) {
      const webview = this.$scope?.$getAppWebview()?.children()[0];
      const jsCode = `
        if (window.handleAppMessage) {
          window.handleAppMessage('${action}', ${JSON.stringify(data)});
        }
      `;
      webview.evalJS(jsCode);
    },
    
    handleMessage(event) {
      const { action, data } = event.detail?.data?.[0] || {};
      
      switch (action) {
        case "draw:create":
          console.log("绘制完成:", data);
          // 自动计算面积
          console.log(`面积: ${(data.properties.area / 1000000).toFixed(2)} km²`);
          break;
      }
    }
  }
};
</script>

技术栈

• 核心: Mapbox GL JS
• 绘制: @mapbox/mapbox-gl-draw
• 地理计算: @turf/turf
• 构建: Vite + TypeScript

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 预览
npm run preview

注意事项

1. 坐标系: SDK 使用 WGS84 坐标系，输入和输出都是真实经纬度
2. 生命周期: 使用完毕后调用 mapSDK.destroy() 释放资源
3. 事件监听: 使用统一的 on/off 接口管理事件
4. 性能优化: 大量数据时建议使用批量操作方法

License

MIT