Package Exports
- vmap-cesium
- vmap-cesium/style
Readme
vmap-cesium
目录
介绍
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"
/>
<!-- 地图工具 -->
<VMapPositionPick position="top-right" :offset="[20, 210]"></VMapPositionPick>
<VMapDraw position="top-right" :offset="[20, 150]"></VMapDraw>
<VMapLocation position="top-right" :offset="[20, 120]"></VMapLocation>
<VMapBasemap position="top-right" :offset="[20, 90]"></VMapBasemap>
<!-- 分析工具 -->
<VMapPmAnalysis position="top-right" :offset="[20, 60]" :samples="10"></VMapPmAnalysis>
</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:4326",
vcConfig: {
cesiumPath: '/public/Cesium/Cesium.js',
accessToken: 'your-cesium-access-token',
tdtToken: 'your-tdt-token'
},
defaultView: {
camera: {
lon: 108.84,
lat: 35.15,
height: 9500000,
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: 是否可见,默认为 trueopacity: 透明度,范围 0-1,默认为 1
VMapWms
WMS服务图层组件
属性
url: WMS服务地址,必填requestParams: WMS请求参数,如 { layers: '图层名称' }visible: 是否可见,默认为 trueopacity: 透明度,范围 0-1,默认为 1
VMapArcgis
ArcGIS服务图层组件
属性
mapProvider: 地图提供者类型,可选 'tile' 等url: ArcGIS服务地址,必填requestParams: 请求参数,如 { layer: '图层名称', tilematrixset: '坐标系' }visible: 是否可见,默认为 trueopacity: 透明度,范围 0-1,默认为 1minZoom: 最小缩放级别maxZoom: 最大缩放级别
VMapTile
瓦片地图图层组件(支持WMTS、GeoServer WMTS等)
属性
mapProvider: 地图提供者类型,可选 'wmts', 'geoserverwmts' 等url: 瓦片服务地址,必填requestParams: 请求参数,如 { layer: '图层名称', tilematrixset: '坐标系' }customParams: 自定义参数,如 { k: '密钥' }visible: 是否可见,默认为 trueopacity: 透明度,范围 0-1,默认为 1
VMapSupermap
SuperMap服务图层组件
属性
mapProvider: 地图提供者类型,可选 'wmts' 等url: SuperMap服务地址,必填requestParams: 请求参数,如 { layer: '图层名称', tilematrixset: '坐标系' }customParams: 自定义参数visible: 是否可见,默认为 trueopacity: 透明度,范围 0-1,默认为 1minZoom: 最小缩放级别maxZoom: 最大缩放级别
VMapVector
矢量数据图层组件
属性
sourceId: 数据源IDfeatures: GeoJSON格式的矢量数据,必填style: 矢量样式配置visible: 是否可见,默认为 trueopacity: 透明度,范围 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 |
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], //标签偏移量
},(e)=>{
console.log(e)
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], //偏移量
},(e)=>{
console.log(e)
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],//标签偏移量
},(e)=>{
console.log(e)
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!希望这个组件能够帮助您快速构建出功能强大的地图应用。