cesium-embed-component
Version:
基于Cesium的嵌入式地图组件库，支持Vue和非Vue项目
359 lines (302 loc) • 10.3 kB
Markdown
# Cesium 嵌入式组件库
这个库提供了基于Cesium的地图组件，可以轻松嵌入到Vue或非Vue项目中使用，并支持丰富的交互功能。
## 安装
### NPM 安装
```bash
npm install cesium-embed-component
```
### CDN 引入
通过CDN可以快速在非Vue项目中引入组件库，以下是详细使用方法：
#### 1. 引入脚本和样式
```html
<!-- 引入Cesium库 (必需) -->
<script src="https://cdn.jsdelivr.net/npm/cesium@1.112.0/Build/Cesium/Cesium.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/cesium@1.112.0/Build/Cesium/Widgets/widgets.css">
<!-- 引入组件库脚本和样式 -->
<script src="https://unpkg.com/cesium-embed-component/dist/cesium-embed.umd.js"></script>
<script src="https://unpkg.com/cesium-embed-component/dist/web-components.js"></script>
<link rel="stylesheet" href="https://unpkg.com/cesium-embed-component/dist/style.css">
```
#### 2. 完整HTML示例
```html
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Cesium 嵌入式组件库示例</title>
<!-- 引入Cesium库 -->
<script src="https://cdn.jsdelivr.net/npm/cesium@1.112.0/Build/Cesium/Cesium.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/cesium@1.112.0/Build/Cesium/Widgets/widgets.css">
<!-- 引入组件库脚本和样式 -->
<script src="https://unpkg.com/cesium-embed-component/dist/cesium-embed.umd.js"></script>
<script src="https://unpkg.com/cesium-embed-component/dist/web-components.js"></script>
<link rel="stylesheet" href="https://unpkg.com/cesium-embed-component/dist/style.css">
<style>
body, html {
margin: 0;
padding: 0;
height: 100%;
width: 100%;
}
cesium-home-view {
height: 100vh;
width: 100vw;
}
</style>
</head>
<body>
<!-- 使用组件 -->
<cesium-home-view id="cesiumView"></cesium-home-view>
<script>
// 等待页面加载完成
document.addEventListener('DOMContentLoaded', function() {
// 注册组件
const { registerCesiumComponents, getEventBus } = window.CesiumWebComponents;
registerCesiumComponents({
// 配置选项
cesiumAccessToken: 'YOUR_CESIUM_ACCESS_TOKEN', // 替换为您的Cesium访问令牌
defaultView: {
longitude: 116.397, // 初始经度
latitude: 39.907, // 初始纬度
zoom: 12 // 初始缩放级别
},
showControls: true, // 是否显示控制按钮
enableMarker: true // 是否启用标记功能
});
// 获取事件总线
const eventBus = getEventBus();
// 监听地图点击事件
eventBus.on('mapClick', function(data) {
console.log('地图被点击:', data);
// 在点击位置添加标记
eventBus.emit('addMarker', {
id: Date.now().toString(),
longitude: data.longitude,
latitude: data.latitude,
title: '点击位置',
description: `经度: ${data.longitude.toFixed(6)}, 纬度: ${data.latitude.toFixed(6)}`
});
});
// 监听标记点击事件
eventBus.on('markerClick', function(marker) {
console.log('标记被点击:', marker);
alert(`您点击了标记: ${marker.title}`);
});
// 模拟添加标记
setTimeout(function() {
eventBus.emit('addMarker', {
id: 'marker1',
longitude: 116.397,
latitude: 39.907,
title: '北京天安门',
description: '中国北京的标志性建筑'
});
}, 2000);
// 获取组件实例并调用方法
const cesiumView = document.getElementById('cesiumView');
// 示例: 5秒后缩放到上海
setTimeout(function() {
cesiumView.zoomToPosition(121.4737, 31.2304, 12);
}, 5000);
});
</script>
</body>
</html>
```
#### 3. 配置选项
通过`registerCesiumComponents`方法可以传入以下配置选项：
- `cesiumAccessToken`: Cesium访问令牌 (必需)
- `defaultView`: 初始视角配置 `{ longitude, latitude, zoom }`
- `showControls`: 是否显示控制按钮 (默认: true)
- `enableMarker`: 是否启用标记功能 (默认: true)
- `terrainProvider`: 地形提供商配置
- `imageryProvider`: 影像提供商配置
#### 4. 事件交互
通过`getEventBus()`获取事件总线后，可以监听和触发以下事件：
- 监听事件: `eventBus.on('事件名', 回调函数)`
- 触发事件: `eventBus.emit('事件名', 数据)`
- 移除监听: `eventBus.off('事件名', 回调函数)`
详细事件列表请参考下方的"可用事件"部分。
#### 5. 组件方法调用
通过DOM元素可以直接调用组件的方法：
```javascript
const cesiumView = document.getElementById('cesiumView');
// 缩放到指定位置
cesiumView.zoomToPosition(longitude, latitude, zoom);
// 切换标记显示/隐藏
cesiumView.toggleMarker(markerId);
// 添加新标记
cesiumView.addMarker(markerOptions);
```
## 使用方法
### Vue 2 vs Vue 3 使用差异
#### Vue 3 全局注册
```javascript
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import CesiumEmbed from 'cesium-embed-component'
const app = createApp(App)
// 全局注册组件
app.use(CesiumEmbed, {
// 配置选项
cesiumAccessToken: 'YOUR_CESIUM_ACCESS_TOKEN',
defaultView: { longitude: 116.397, latitude: 39.907, zoom: 12 }
})
app.mount('#app')
```
#### Vue 3 局部注册
```vue
<script setup>
import { HomeView, CesiumMap } from 'cesium-embed-component'
</script>
<template>
<HomeView />
<!-- 或直接使用CesiumMap组件 -->
<CesiumMap />
</template>
```
#### Vue 2 全局注册
```javascript
// main.js
import Vue from 'vue'
import App from './App.vue'
import CesiumEmbed from 'cesium-embed-component'
// 全局注册组件
Vue.use(CesiumEmbed, {
// 配置选项
cesiumAccessToken: 'YOUR_CESIUM_ACCESS_TOKEN',
defaultView: { longitude: 116.397, latitude: 39.907, zoom: 12 }
})
new Vue({
render: h => h(App)
}).$mount('#app')
```
#### Vue 2 局部注册
```vue
<script>
import { HomeView, CesiumMap } from 'cesium-embed-component'
export default {
components: {
HomeView,
CesiumMap
}
}
</script>
<template>
<HomeView />
<!-- 或直接使用CesiumMap组件 -->
<CesiumMap />
</template>
```
### 主要差异点
1. **创建应用实例**: Vue 3使用`createApp()`，Vue 2直接使用`new Vue()`
2. **插件注册**: Vue 3使用`app.use()`，Vue 2使用`Vue.use()`
3. **组件注册**: Vue 3支持`<script setup>`语法，Vue 2使用`components`选项
4. **事件总线**: Vue 3中本库使用`mitt`或自定义响应式对象实现，Vue 2通常使用`Vue.prototype.$bus`或专门的事件总线插件
### 在非Vue项目中使用 (Web Components)
```html
<!-- 引入脚本 -->
<script src="https://unpkg.com/cesium-embed-component/dist/cesium-embed.umd.js"></script>
<script src="https://unpkg.com/cesium-embed-component/dist/web-components.js"></script>
<!-- 在HTML中使用 -->
<body>
<cesium-home-view></cesium-home-view>
<!-- 或直接使用地图组件 -->
<cesium-map></cesium-map>
<script>
// 注册组件
const { registerCesiumComponents, getEventBus } = window.CesiumWebComponents
registerCesiumComponents()
// 获取事件总线并监听事件
const eventBus = getEventBus()
eventBus.on('mapClick', (data) => {
console.log('地图被点击:', data)
})
// 触发事件
setTimeout(() => {
eventBus.emit('addMarker', { longitude: 116.397, latitude: 39.907 })
}, 2000)
</script>
</body>
```
## 组件说明
### HomeView
完整的地图视图组件，包含地图和控制栏。
### CesiumMap
核心地图组件，提供Cesium地图功能。
#### 属性
- `accessToken`: Cesium访问令牌
- `initialView`: 初始视角配置 `{ longitude, latitude, zoom }`
- `showControls`: 是否显示控制按钮
#### 方法
- `toggleMarker(id)`: 切换标记点显示/隐藏
- `zoomToPosition(longitude, latitude, zoom)`: 缩放到指定位置
- `addMarker(options)`: 添加新标记
### HeadBar
顶部导航栏组件。
## 事件交互
通过事件总线可以实现组件间或与外部项目的交互。
### Vue 3 中使用事件总线
```javascript
// 在Vue组件中使用
import { inject } from 'vue'
const eventBus = inject('eventBus')
// 监听事件
eventBus.on('mapClick', (data) => {
console.log('地图点击事件:', data)
})
// 发送事件
eventBus.emit('showInfo', { message: 'Hello from parent' })
```
### Vue 2 中使用事件总线
```javascript
// 在Vue组件中使用
export default {
mounted() {
// 获取事件总线
this.eventBus = this.$bus
// 监听事件
this.eventBus.on('mapClick', this.handleMapClick)
},
methods: {
handleMapClick(data) {
console.log('地图点击事件:', data)
},
sendMessage() {
// 发送事件
this.eventBus.emit('showInfo', { message: 'Hello from component' })
}
},
beforeDestroy() {
// 移除事件监听
this.eventBus.off('mapClick', this.handleMapClick)
}
}
```
### 可用事件
- `mapClick`: 地图点击事件，返回点击位置坐标
- `markerClick`: 标记点点击事件，返回标记信息
- `viewChanged`: 视角改变事件，返回当前视角信息
- `addMarker`: 添加标记事件
- `removeMarker`: 移除标记事件
## 开发指南
### 本地开发
```bash
# 安装依赖
npm install
# 启动开发服务器
npm run dev
```
### 构建
```bash
# 构建库
npm run build
```
## 注意事项
1. 使用前需要获取Cesium访问令牌: [Cesium Ion](https://cesium.com/ion/)
2. 确保在使用Web Components时，浏览器支持Custom Elements
3. 嵌入到其他项目时，注意处理CSS冲突
## 许可证
MIT