vmap-cesium

目录

• 介绍
• 特性
• 安装
• 快速开始
  • 引入组件库
  • 基础地图组件使用
• 核心组件
  • VMap
• 图层组件
  • VMapTdt
  • VMapWms
  • VMapArcgis
  • VMapTile
  • VMapSupermap
  • VMapVector
• 工具组件
  • VMapPositionPick
  • VMapDraw
  • VMapLocation
  • VMapBasemap
  • VMapBar
  • VMapRoll
• 分析组件
  • VMapPmAnalysis
• 地图配置
• API参考
  • CesiumInstance
  • GwVizAPI
• 示例
• 注意事项
• 浏览器兼容性
• 许可证
• 贡献
• 联系我们

介绍

vmap-cesium 是一个基于 Vue 3 和 Cesium 的地图可视化组件库，同时融合了vue-cesium的组件，提供了丰富的地图功能和组件，方便开发者快速构建高性能的三维地理信息系统应用。

特性

• 🎯 基于 Vue 3 Composition API 构建
• 🌍 集成 Cesium 强大的三维地图渲染能力
• 🗺️ 支持多种地图图层类型（WMS、WMTS、ArcGIS、GeoJSON 等）
• 🛠️ 提供丰富的地图工具组件（测量、位置拾取、绘制等）
• 📊 内置空间分析功能（如剖面分析）
• 🎨 支持自定义样式和主题
• 🚀 高性能的地图渲染和数据处理
• 🔧 完整的类型支持（TypeScript）

安装

# 使用 npm
npm install vmap-cesium

# 使用 yarn
yarn add vmap-cesium

# 使用 pnpm
pnpm add vmap-cesium

快速开始

CDN模式引入Cesium静态资源

在使用组件库前，您需要通过CDN方式引入Cesium静态资源：

<script src="https://cesium.com/downloads/cesiumjs/releases/1.132/Build/Cesium/Cesium.js"></script>
<link rel="stylesheet" href="https://cesium.com/downloads/cesiumjs/releases/1.132/Build/Cesium/Widgets/widgets.css">

引入组件库

import { createApp } from 'vue'
import App from './App.vue'
import VMapCesium from 'vmap-cesium'
import 'vmap-cesium/dist/index.css'

// 引入 Element Plus（组件库依赖）
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import 'element-plus/theme-chalk/dark/css-vars.css'
import locale from 'element-plus/es/locale/lang/zh-cn'

const app = createApp(App)
app.use(ElementPlus, { locale })
app.use(VMapCesium)
app.mount('#app')

基础地图组件使用

<template>
  <div class="map-container">
    <VMap :map-config="mapConfig" :use-Plugin="true" @ready="handleMapReady">
      <!-- 天地图图层 -->
      <VMapTdt map-style="img" :visible="true" :opacity="1"></VMapTdt>
      
      <!-- WMS图层 -->
      <VMapWms 
        :url="wmsUrl" 
        :visible="true" 
        :request-params="{ layers: 'nurc:Img_Sample' }" 
        :opacity="0.8" 
      />
      
      <!-- 矢量数据 -->
      <VMapVector 
        :features="geojsonData" 
        :style="vectorStyle" 
        :visible="true" 
      />
      
      <!-- 地图工具 -->
      <VMapBar></VMapBar>
      <VMapPositionPick position="top-right" :offset="[20, 210]"></VMapPositionPick>
      <VMapBasemap position="top-right" :offset="[20, 90]"></VMapBasemap>
      
      <!-- 分析工具 -->
      <VMapPmAnalysis position="top-right" :offset="[20, 60]" :samples="10"></VMapPmAnalysis>

      <!-- 如果使用vue-cesium组件，需要在VMap组件中添加vue-cesium插槽 -->
      <template #vue-cesium>
        <vc-measurements
          ref="measurementsRef2"
          position="top-right"
          active-color="yellow"
        >
        </vc-measurements>

        <vc-drawings
          ref="drawingsRef"
          position="bottom-left"
          :offset="[10, 65]"
        ></vc-drawings>
      </template>
    </VMap>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { VMap ,VMapTdt,VMapWms,VMapVector,VMapPositionPick,VMapDraw,VMapLocation,VMapBasemap,VMapPmAnalysis} from 'vmap-cesium'
import {gwVizAPI} from 'vmap-cesium'

// 地图配置
const mapConfig = {
  prj: "EPSG:3857",
  vcConfig: {
    cesiumPath: '/public/Cesium/Cesium.js',
    accessToken: 'your-cesium-access-token',
    tdtToken: 'your-tdt-token'
  },
  defaultView: {
    camera: {
      lon: 108.84,
      lat: 35.15,
      height: 19500000,
      heading: 0,
      pitch: -89.74,
      roll: 0
    }
  }
}

// WMS服务地址
const wmsUrl = ref('http://ip/geoserver/nurc/wms')

// GeoJSON数据
const geojsonData = ref([/* GeoJSON格式的矢量数据 */])

// 矢量样式
const vectorStyle = ref({
  fill: true,
  fillColor: 'rgba(255, 0, 0, 0.5)',
  stroke: true,
  strokeColor: 'rgba(0, 0, 255, 1)',
  strokeWidth: 2
})

// 地图加载完成回调
const handleMapReady = (cesiumInstance) => {
  // 可以在这里进行地图相关操作
  console.log('地图加载完成', cesiumInstance)

  //地图加载完成后即可使用gwVizAPI功能
  // 添加点
  gwVizAPI.addPoint({
    longitude: 116.4,
    latitude: 39.9,
    name: '测试点'
  })
}
</script>

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

核心组件

VMap

地图主容器组件，是所有其他地图组件的父组件。

属性

• mapConfig: 地图配置对象，包含投影、视图、图层等配置
• usePlugin: 是否使用VueCesium插件，默认为true

事件

• ready: 地图加载完成时触发，返回cesiumInstance实例
• mouse-click: 鼠标点击地图时触发
• mouse-move: 鼠标移动地图时触发

图层组件

VMapTdt

天地图图层组件

属性

• mapStyle: 天地图样式，可选 'img'(影像图), 'vec'(矢量图), 'ter'(地形图)，默认为 'img'
• visible: 是否可见，默认为 true
• opacity: 透明度，范围 0-1，默认为 1

VMapWms

WMS服务图层组件

属性

• url: WMS服务地址，必填
• requestParams: WMS请求参数，如 { layers: '图层名称' }
• visible: 是否可见，默认为 true
• opacity: 透明度，范围 0-1，默认为 1

VMapArcgis

ArcGIS服务图层组件

属性

• mapProvider: 地图提供者类型，可选 'tile' 等
• url: ArcGIS服务地址，必填
• requestParams: 请求参数，如 { layer: '图层名称', tilematrixset: '坐标系' }
• visible: 是否可见，默认为 true
• opacity: 透明度，范围 0-1，默认为 1
• minZoom: 最小缩放级别
• maxZoom: 最大缩放级别

VMapTile

瓦片地图图层组件（支持WMTS、GeoServer WMTS等）

属性

• mapProvider: 地图提供者类型，可选 'wmts', 'geoserverwmts' 等
• url: 瓦片服务地址，必填
• requestParams: 请求参数，如 { layer: '图层名称', tilematrixset: '坐标系' }
• customParams: 自定义参数，如 { k: '密钥' }
• visible: 是否可见，默认为 true
• opacity: 透明度，范围 0-1，默认为 1

VMapSupermap

SuperMap服务图层组件

属性

• mapProvider: 地图提供者类型，可选 'wmts' 等
• url: SuperMap服务地址，必填
• requestParams: 请求参数，如 { layer: '图层名称', tilematrixset: '坐标系' }
• customParams: 自定义参数
• visible: 是否可见，默认为 true
• opacity: 透明度，范围 0-1，默认为 1
• minZoom: 最小缩放级别
• maxZoom: 最大缩放级别

VMapVector

矢量数据图层组件

属性

• sourceId: 数据源ID
• features: GeoJSON格式的矢量数据，必填
• style: 矢量样式配置
• visible: 是否可见，默认为 true
• opacity: 透明度，范围 0-1，默认为 1

工具组件

VMapPositionPick

坐标拾取和定位工具

属性

• position: 工具位置，可选 'top-right', 'top-left', 'bottom-right', 'bottom-left'，默认为 'top-right'
• offset: 位置偏移量，格式为 [x, y]，默认为 [0, 0]

功能

• 坐标拾取：点击地图获取经纬度和高度信息
• 坐标定位：输入经纬度和高度，将地图视角定位到指定位置

VMapDraw

地图绘制工具

功能

• 支持绘制点、线、面等几何图形
• 提供清空绘制内容的功能

VMapLocation

定位工具

属性

• position: 工具位置，可选 'top-right', 'top-left', 'bottom-right', 'bottom-left'，默认为 'top-right'
• offset: 位置偏移量，格式为 [x, y]，默认为 [0, 0]

功能

将地图视角定位到用户当前位置或指定位置

VMapBasemap

底图切换工具

属性

• position: 工具位置，可选 'top-right', 'top-left', 'bottom-right', 'bottom-left'，默认为 'top-right'
• offset: 位置偏移量，格式为 [x, y]，默认为 [0, 0]

功能

• 在多个预设底图之间进行切换
• 底图配置来自地图配置对象中的 baseLayers 数组

VMapBar

工具栏组件（待实现）

VMapRoll

旋转工具组件（待实现）

分析组件

VMapPmAnalysis

剖面分析工具

属性

• position: 工具位置，可选 'top-right', 'top-left', 'bottom-right', 'bottom-left'，默认为 'top-right'
• offset: 位置偏移量，格式为 [x, y]，默认为 [0, 0]
• samples: 采样点数量，默认为 10

功能

• 绘制剖面线，分析地形高程
• 生成高程剖面图（基于ECharts）
• 显示剖面线起点和终点经纬度信息
• 支持导出分析结果为图片

地图配置

地图配置对象包含了地图的各种参数设置，下面是一个完整的配置示例：

const mapConfig = {
  // 投影坐标系
  prj: "EPSG:4326",
  
  // Cesium相关配置
  vcConfig: {
    // Cesium库文件路径
    cesiumPath: '/public/Cesium/Cesium.js',
    // Cesium访问令牌
    accessToken: 'your-cesium-access-token',
    // 天地图Token
    tdtToken: 'your-tdt-token'
  },
  
  // 默认视图设置
  defaultView: {
    camera: {
      lon: 108.84,  // 经度
      lat: 35.15,   // 纬度
      height: 9500000,  // 高度
      heading: 0,   // 朝向角
      pitch: -89.74,  // 俯仰角
      roll: 0      // 翻滚角
    },
    zoom: 4,       // 默认缩放级别
    minZoom: 0,    // 最小缩放级别
    maxZoom: 18    // 最大缩放级别
  },
  
  // 默认底图层ID
  defaultBaseLayerId: "1",
  
  // 地形设置
  terrainProvider: {
    enabled: false, // 是否开启地形
    requestVertexNormals: false, // 是否开启顶点法线
    requestWaterMask: false // 是否开启水面遮罩
  },
  
  // 底图层配置
  baseLayers: [
    // 影像底图配置
    {
      id: "1",
      label: "影像",
      type: "tdt",
      children: [
        {
          id: "TDT_IMG",
          zIndex: 0,
          visible: true,
          type: "tdt",
          alpha: 1
        },
        {
          id: "TDT_IMG_LABEL",
          zIndex: 1,
          visible: true,
          type: "tdt",
          alpha: 1
        }
      ]
    },
    // 矢量底图配置
    {
      id: "2",
      label: "矢量",
      type: "tdt",
      children: [
        // 矢量底图图层配置...
      ]
    }
  ]
}

API参考

CesiumInstance

地图加载完成后返回的Cesium实例对象，提供了丰富的地图操作方法：

获取viewer实例对象

• CesiumInstance.viewer: Cesium的Viewer实例对象，提供了地图的各种操作方法。

地图控制方法

• setViewExtent(extent): 设置地图视野
• flyToView(view): 平滑飞行到指定视野
• getExtent(): 获取当前地图范围
• getLonLatByPosition(position): 根据屏幕坐标获取经纬度

图层管理方法

• addLayer(layerConfig): 添加图层
• removeLayer(layerId): 移除图层
• setLayerVisible(layerId, visible): 设置图层可见性
• setLayerOpacity(layerId, opacity): 设置图层透明度
• removeAllLayers(): 移除所有图层
• loadBaseLayer(layers): 加载底图图层

事件管理方法

• registerMouseClick(callback): 注册鼠标点击事件
• registerMouseMove(callback): 注册鼠标移动事件
• releaseMouseClick(): 释放鼠标点击事件
• releaseMouseMove(): 释放鼠标移动事件

GwVizAPI

主要方法

| 方法名 | 描述 | 参数 | |--------|------|------| | addPoint | 添加entity到viewer-点 | PointOptions | | addPolyline | 添加entity到viewer-线 | PolylineOptions | | addPolygon | 添加entity到viewer-多边形 | PolygonOptions | | setEntityVisibility | 显示隐藏实体 | option: {entityId: string, visible: boolean} | | getAllEntities | 获取所有实体 | | | `removeEntity` | 移除实体 | `entityId: string` | | `clearAllEntities` | 移除所有实体 | | | getCurrentView | 获取当前视图 | `` | | setView | 设置视图 | ViewOptions | | onDrawComplete | 监听绘制完成事件 | callback: DrawCallback | | createCustomLayer | 创建图层 | id: string, visible: boolean |添加实体|add| | setCustomLayerVisible | 图层显隐 | id: string, visible: boolean | | removeCustomLayer | 删除图层 | id: string | | createPoint | 创建实体-点 | PointOptions | | createPolyline | 创建实体-线 | PolylineOptions | | createPolygon | 创建实体-多边形 | PolygonOptions | | addMask | 添加遮罩 | maskOptions | | getMaskById | 获取遮罩对象 | id: string | | setMaskVisible | 遮罩显隐控制 | id: string,v: boolean | | removeMaskById | 删除遮罩 | id: string |

事件类型

• draw-complete: 绘制完成事件
• measurement-complete: 测量完成事件
• map-click: 地图点击事件
• entity-select: 实体选择事件
• camera-move: 相机变化
• error-occurred: 错误事件
• entity-removed: 移除实体成功
• entities-cleared: 移除所有实体成功

类型定义

interface PointOptions {
  id: string
  longitude: number
  latitude: number
  height?: number
  name?: string
  description?: string
  color?: string
  pixelSize?: number
  clampToGround?: boolean
  outlineColor?: string
  outlineWidth?: number
  image?: string
  imageScale?: number
  font?: string
  labelColor?: string
  labelBackgroundColor?: string
  labelPixelOffset?: number[],
  showLabelBackground: boolean
  entityType?: string
  // ... 其他属性
}
interface PolylineOptions {
  id?: string
  coordinates?: number[][]
  name?: string
  description?: string
  color?: string
  width?: number
  clampToGround?: boolean
  font?: string
  labelColor?: string
  labelBackgroundColor?: string
  labelPixelOffset?: number[],
  showLabelBackground: boolean
  entityType?: string
  customProperties?: Record<string, any>
}
interface PolygonOptions {
  id?: string
  coordinates?: number[][][]
  name?: string
  description?: string
  color?: string
  opacity?: number
  showOutline?: boolean
  outlineColor?: string
  outlineWidth?: number
  clampToGround?: boolean
  font?: string
  labelColor?: string
  labelBackgroundColor?: string
  labelPixelOffset?: number[],
  showLabelBackground: boolean
  entityType?: string
  customProperties?: Record<string, any>
  height?: number
  extrudedHeight?: number
}
interface maskOptions {
  id: string
  type:string
  coordinates: any
  maskColor:string
  areaColor:string
  outline:boolean
  outlineColor:string
  outlineWidth:number
  height:number
  extrudedHeight:number
}
interface ViewOptions {
  longitude: number
  latitude: number
  height: number
  duration?: number
  heading?: number
  pitch?: number
  roll?: number
}
interface EntityOptions {
  entityId: string
  visible?: boolean
  properties?: Record<string, any>
}

示例

基本使用

import { gwVizAPI } from 'gw-viz-cesium'

# 添加点
gwVizAPI.addPoint({
    id: "point", //id
    longitude: 108, //经度
    latitude: 38, //纬度
    height: 1000000, //高度
    name: "测试", //显示文字
    description: "测试", //描述
    color: "#df1919", //点颜色
    pixelSize: 10, //标注大小
    clampToGround: true, //是否贴地
    outlineColor: "#ef1a1a", //边框颜色
    outlineWidth: 2, //边框宽度
    image: "path", //图片路径
    imageScale: 0.1, //图片放大比例
    font: "14px Arial", //字体样式
    labelColor: "#f2f4f4", //标签文字颜色
    labelBackgroundColor: "#ffffff", //标签背景颜色
    showLabelBackground:true, //是否显示标签背景颜色
    labelPixelOffset: [0,-25], //标签偏移量
}.then(entity)=>{
    console.log(entity)
    console.log("添加成功")
})

#添加线
gwVizAPI.addPolyline({
    id:"polyline", //id
    coordinates:[[100,50,10],[100,10,1000]], //线数据经度、纬度、高度
    name: '测试线',//标签名称
    description: '测试线',//描述
    clampToGround:true,//是否贴地
    color: '#df3434', //线颜色
    width: 3, //线宽
    font: "14px Arial", //字体样式
    labelColor: "#f6e317", //标签字体颜色
    labelBackgroundColor: "#EC0000FC",//标签背景颜色
    showLabelBackground:true, //是否显示标签背景色
    labelPixelOffset: [0,-20], //偏移量
}.then(entity)=>{
    console.log(entity)
    console.log("添加成功")
})

#添加面
gwVizAPI.addPolygon({
    id:"polygon", //id
    //面数据
    coordinates:[],
    name: '北京', //标签文字
    description: '这是北京', //描述
    clampToGround:false,//是否贴地
    color: '#e61818',//面颜色
    outlineColor: '#77e82b',//边框线颜色
    outlineWidth:10000, //边框线宽度
    showOutline:true, //是否显示边框线
    height:1000000,//高度
    extrudedHeight:100,//多边形的挤压面与椭球面之间的距离
    font: "18px Arial",//字体样式
    labelColor: "#f6d817",//标签颜色
    labelBackgroundColor: "#0056d8",//标签背景色
    showLabelBackground:true,//是否显示标签背景色
    labelPixelOffset: [0,-20],//标签偏移量
}.then(entity)=>{
    console.log(entity)
    console.log("添加成功")
})

创建图层
const layer = gwVizAPI.createCustomLayer("layerId",true)  //参数1:图层id,参数2：图层是否显示 默认 true

#创建点实体
const entity = gwVizAPI.createPoint({
    id: "point", //id
    longitude: 108, //经度
    latitude: 38, //纬度
    height: 1000000, //高度
    name: "测试", //显示文字
    description: "测试", //描述
    color: "#df1919", //点颜色
    pixelSize: 10, //标注大小
    clampToGround: true, //是否贴地
    outlineColor: "#ef1a1a", //边框颜色
    outlineWidth: 2, //边框宽度
    image: "path", //图片路径
    imageScale: 0.1, //图片放大比例
    font: "14px Arial", //字体样式
    labelColor: "#f2f4f4", //标签文字颜色
    labelBackgroundColor: "#ffffff", //标签背景颜色
    showLabelBackground:true, //是否显示标签背景颜色
    labelPixelOffset: [0,-25], //标签偏移量
})
layer.add(entity) //把创建的点实体添加到图层layer中

#创建线实体
const entity = gwVizAPI.createPolyline({
    id:"polyline", //id
    coordinates:[[100,50,10],[100,10,1000]], //线数据经度、纬度、高度
    name: '测试线',//标签名称
    description: '测试线',//描述
    clampToGround:true,//是否贴地
    color: '#df3434', //线颜色
    width: 3, //线宽
    font: "14px Arial", //字体样式
    labelColor: "#f6e317", //标签字体颜色
    labelBackgroundColor: "#EC0000FC",//标签背景颜色
    showLabelBackground:true, //是否显示标签背景色
    labelPixelOffset: [0,-20], //偏移量
})
layer.add(entity) //把创建的线实体添加到layer图层中

#创建面实体
const entity = gwVizAPI.createPolygon({
    id:"polygon",//id
    //面数据
    coordinates:[],
    name: '北京', //标签文字
    description: '这是北京', //描述
    clampToGround:false,//是否贴地
    color: '#e61818',//面颜色
    outlineColor: '#77e82b',//边框线颜色
    outlineWidth:10000, //边框线宽度
    showOutline:true, //是否显示边框线
    height:1000000,//高度
    extrudedHeight:100,//多边形的挤压面与椭球面之间的距离
    font: "18px Arial",//字体样式
    labelColor: "#f6d817",//标签颜色
    labelBackgroundColor: "#0056d8",//标签背景色
    showLabelBackground:true,//是否显示标签背景色
    labelPixelOffset: [0,-20],//标签偏移量
})
layer.add(entity) //把创建的面实体添加到layer中

gwVizAPI.setCustomLayerVisible("layerId",true) //根据id设置图层显示隐藏

gwVizAPI.removeCustomLayer("layerId") //根据id移除图层

#添加地图遮罩
gwVizAPI.addMask({
    id:"mask", //id
    type:"Polygon", //类型  Polygon | MultiPolygon
    //遮罩挖空区域面数据
    coordinates:[],
    maskColor:'#00000082', //遮罩颜色
    areaColor: '#ffffff',//挖空区域颜色
    outline:false,//是否显示边框线
    outlineColor: '#e82bdf',//边框线颜色
    outlineWidth:0,//边框线宽度
    height: 0,//边框线高度
    extrudedHeight: 0 //多边形的挤压面与椭球面之间的距离
})

gwVizAPI.setMaskVisible("mask",true) //根据id设置地图遮罩显示隐藏

gwVizAPI.removeMaskById("mask") //根据id移除地图遮罩

注意事项

• 使用前请确保已正确配置Cesium和天地图的访问令牌
• 组件需要在支持WebGL的浏览器中运行
• 处理大量数据时，请注意性能优化
• 如需自定义组件样式，请使用深度选择器 :deep()
• 部分组件（如VMapBar、VMapRoll）正在开发中，功能可能不完整

浏览器兼容性

| 浏览器 | 支持版本 | |--------|----------| | Chrome | 最新2个稳定版本 | | Firefox | 最新2个稳定版本 | | Safari | 最新2个稳定版本 | | Edge | 最新2个稳定版本 |

许可证

MIT

贡献

欢迎提交Issue和Pull Request来帮助改进这个项目。

联系我们

如有任何问题或建议，请通过以下方式联系我们：

• Email:
• GitHub:

感谢使用 VMap-cesium！希望这个组件能够帮助您快速构建出功能强大的地图应用。