Frost-Map

一个基于 Cesium 的地图工具包，用于在 Web 上创建 3D 地图应用。

功能特性

• 🗺️ 地图核心：封装 Cesium Viewer，提供地图初始化和管理
• 🎨 Vue 组件：提供 Vue 3 地图组件，支持响应式绑定
• 📍 视图控制：支持飞行定位、缩放、视角切换
• 📐 测量工具：支持距离测量功能
• ✏️ 绘制工具：支持点、线、多边形绘制
• 💬 弹窗工具：支持在地图上显示自定义弹窗

安装

npm install frost-map

快速开始

在 Vue 项目中使用

<template>
  <div style="width: 100%; height: 600px;">
    <FrostMap :options="mapOptions" @ready="onMapReady" />
  </div>
</template>

<script setup>
import { FrostMap } from 'frost-map';

const mapOptions = {
  animation: false,
  baseLayerPicker: true
};

const onMapReady = (mapInstance) => {
  console.log('Map is ready:', mapInstance);
};
</script>

在 JavaScript 中使用

import { MapClass } from 'frost-map';

const map = new MapClass({
  animation: false
});

map.init(document.getElementById('map-container'));

API 文档

1. MapClass - 地图核心类

封装 Cesium Viewer，提供地图初始化、销毁等基础操作。

构造函数

new MapClass(options)

方法

示例

const map = new MapClass({
  baseLayerPicker: false,
  fullscreenButton: true
});

const viewer = map.init(document.getElementById('map'));
const cesiumViewer = map.getViewer();

// 页面销毁时
map.destroy();

2. FrostMap - Vue 地图组件

基于 MapClass 封装的 Vue 3 组件，提供响应式地图绑定。

Props

Events

方法

示例

<template>
  <FrostMap 
    ref="mapRef" 
    :options="options" 
    @ready="onReady" 
  />
</template>

<script setup>
import { ref } from 'vue';
import { FrostMap } from 'frost-map';

const mapRef = ref(null);
const options = {
  timeline: false
};

const onReady = (map) => {
  console.log('Map ready:', map);
};

const getMapInstance = () => {
  return mapRef.value?.getMap();
};
</script>

3. ViewController - 视图控制器

提供相机控制功能，如飞行定位、缩放、视角切换等。

构造函数

new ViewController(viewer)

方法

参数说明

position / target 对象结构：

flyTo options：

示例

import { MapClass, ViewController } from 'frost-map';

const map = new MapClass();
map.init(document.getElementById('map'));

const viewer = map.getViewer();
const viewController = new ViewController(viewer);

// 飞行到北京
viewController.flyTo({
  longitude: 116.4074,
  latitude: 39.9042,
  height: 5000
}, {
  duration: 2
});

// 放大
viewController.zoomIn(500);

// 获取当前位置
const pos = viewController.getCurrentPosition();
console.log(pos); // { longitude, latitude, height }

// 看向目标
viewController.lookAt({
  longitude: 116.4074,
  latitude: 39.9042
});

4. CesiumMeasure - 测量工具

提供距离测量功能，支持鼠标交互绘制测量线。

构造函数

new CesiumMeasure(viewer)

方法

使用说明

1. 调用 start() 开始测量
2. 左键点击地图添加测量点
3. 鼠标移动预览测量线
4. 右键点击结束测量

示例

import { MapClass, CesiumMeasure } from 'frost-map';

const map = new MapClass();
map.init(document.getElementById('map'));

const viewer = map.getViewer();
const measure = new CesiumMeasure(viewer);

// 开始测量
measure.start();

// 测量完成后停止
// measure.stop();

// 清除测量线
// measure.clear();

5. CesiumDrawer - 绘制工具

支持在地图上绘制点、线、多边形。

构造函数

new CesiumDrawer(viewer)

方法

绘制模式

使用说明

1. 调用 start(mode) 开始绘制
2. 左键点击地图添加点
3. 鼠标移动预览绘制结果
4. 右键点击结束绘制

示例

import { MapClass, CesiumDrawer } from 'frost-map';

const map = new MapClass();
map.init(document.getElementById('map'));

const viewer = map.getViewer();
const drawer = new CesiumDrawer(viewer);

// 绘制点
drawer.start('point');

// 绘制线
// drawer.start('polyline');

// 绘制多边形
// drawer.start('polygon');

// 清除所有绘制
// drawer.clear();

6. Popup - 弹窗工具

用于在地图上显示自定义弹窗信息。

构造函数

new Popup(viewer)

方法

参数说明

options 对象：

示例

import { MapClass, Popup } from 'frost-map';

const map = new MapClass();
map.init(document.getElementById('map'));

const viewer = map.getViewer();
const popup = new Popup(viewer);

// 创建位置
const position = Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 0);

// 显示弹窗
popup.show(position, '<h3>Hello World</h3><p>This is a popup</p>');

// 隐藏弹窗
// popup.hide();

7. mapConfig - 地图配置

包含默认的 Cesium Viewer 配置选项和相机位置。

配置项

{
  // 默认 Viewer 配置
  defaultOptions: {
    animation: false,
    baseLayerPicker: true,
    fullscreenButton: true,
    geocoder: true,
    homeButton: true,
    infoBox: true,
    sceneModePicker: true,
    selectionIndicator: true,
    timeline: false,
    navigationHelpButton: false,
    navigationInstructionsInitiallyVisible: false
  },
  
  // 默认相机位置（北京）
  defaultCameraPosition: {
    longitude: 116.4074,
    latitude: 39.9042,
    height: 10000
  },
  
  imageryProvider: null,  // 影像图层提供者
  terrainProvider: null   // 地形提供者
}

示例

import { mapConfig, MapClass } from 'frost-map';

// 使用默认配置
const map = new MapClass(mapConfig.defaultOptions);
map.init(document.getElementById('map'));

// 使用默认相机位置
const viewController = new ViewController(map.getViewer());
viewController.flyTo(mapConfig.defaultCameraPosition);

完整示例

<template>
  <div class="map-container">
    <FrostMap ref="mapRef" :options="options" @ready="onMapReady" />
    
    <!-- 控制按钮 -->
    <div class="controls">
      <button @click="flyToBeijing">飞行到北京</button>
      <button @click="startMeasure">开始测量</button>
      <button @click="drawPolygon">绘制多边形</button>
      <button @click="showPopup">显示弹窗</button>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { 
  FrostMap, 
  ViewController, 
  CesiumMeasure, 
  CesiumDrawer, 
  Popup,
  mapConfig 
} from 'frost-map';

const mapRef = ref(null);
let viewController = null;
let measure = null;
let drawer = null;
let popup = null;

const options = {
  ...mapConfig.defaultOptions,
  timeline: false
};

const onMapReady = (map) => {
  const viewer = map.getViewer();
  
  // 初始化控制器
  viewController = new ViewController(viewer);
  measure = new CesiumMeasure(viewer);
  drawer = new CesiumDrawer(viewer);
  popup = new Popup(viewer);
};

const flyToBeijing = () => {
  viewController?.flyTo(mapConfig.defaultCameraPosition);
};

const startMeasure = () => {
  measure?.start();
};

const drawPolygon = () => {
  drawer?.start('polygon');
};

const showPopup = () => {
  const position = Cesium.Cartesian3.fromDegrees(
    mapConfig.defaultCameraPosition.longitude,
    mapConfig.defaultCameraPosition.latitude,
    0
  );
  popup?.show(position, '<h3>北京</h3><p>中国首都</p>');
};
</script>

<style scoped>
.map-container {
  width: 100%;
  height: 100vh;
  position: relative;
}

.controls {
  position: absolute;
  top: 20px;
  left: 20px;
  z-index: 100;
  display: flex;
  gap: 10px;
}

.controls button {
  padding: 10px 20px;
  background: white;
  border: 1px solid #ccc;
  border-radius: 4px;
  cursor: pointer;
}

.controls button:hover {
  background: #f5f5f5;
}
</style>

天地图集成

frost-map 提供了便捷的天地图底图配置功能，支持影像图、矢量图和地形图。

使用方式

在 Vue 组件中使用

<template>
  <FrostMap 
    :options="mapOptions"
    :tianditu-config="tiandituConfig"
    @ready="onMapReady"
  />
</template>

<script setup>
import { ref } from 'vue';
import { FrostMap } from 'frost-map';

const mapOptions = {
  baseLayerPicker: false  // 禁用默认底图选择器
};

const tiandituConfig = ref({
  token: 'your-tianditu-token',  // 替换为你的天地图 token
  type: 'img',                    // img: 影像, vec: 矢量, ter: 地形
  enableLabel: true               // 显示标注层
});

const onMapReady = (map) => {
  console.log('Map ready:', map);
};
</script>

在 JavaScript 中使用

import { MapClass } from 'frost-map';

const map = new MapClass({
  baseLayerPicker: false
});

map.init('#map-container').then(() => {
  // 设置天地图底图
  map.setTiandituImageryProvider({
    token: 'your-tianditu-token',
    type: 'img',
    enableLabel: true
  });
});

天地图配置选项

获取天地图 Token

1. 访问 天地图官网
2. 注册账号并登录
3. 进入控制台 -> 我的应用 -> 创建应用
4. 获取 Token

依赖说明

由于 cesium 和 vue 被配置为外部依赖（externals），使用时需要确保在项目中正确引入：

通过 CDN 引入

<script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js"></script>
<script src="https://cesium.com/downloads/cesiumjs/releases/1.100/Build/Cesium/Cesium.js"></script>
<link href="https://cesium.com/downloads/cesiumjs/releases/1.100/Build/Cesium/Widgets/widgets.css" rel="stylesheet">

通过 npm 安装

npm install cesium vue

许可证

MIT License