Scene Mapping GIS

外观

3D · 快速开始 ​

3D 文档 · 从 Viewer 到第一个场景

3D 模块基于 Cesium，使用 CesiumMap 创建 Viewer，并通过默认插槽组合影像、实体、业务标记、动态墙和 3D Tiles。建议先完成本页，再按业务需要阅读其他专题。

安装与静态资源 ​

ts
import { CesiumMap, CesiumImagery } from "scene-mapping-gis/3d";

Cesium 的 Workers、Assets、Widgets 和 ThirdParty 必须部署到浏览器可访问的位置，并通过 CESIUM_BASE_URL 指向该目录。出现 Worker、wasm 或纹理 404 时，应先检查静态资源路径。

创建地图 ​

vue
<template>
  <div class="map-container">
    <CesiumMap :options="viewerOptions" @load="onLoad" @error="onError">
      <CesiumImagery
        type="xyz"
        url="https://server.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"
      />
    </CesiumMap>
  </div>
</template>

<script setup lang="ts">
import { shallowRef } from "vue";
import { CesiumImagery, CesiumMap } from "scene-mapping-gis/3d";
import type { Viewer } from "scene-mapping-gis/3d";

const viewerRef = shallowRef<Viewer | null>(null);
const viewerOptions = { baseLayer: false, homeButton: true };
const onLoad = (viewer: Viewer) => { viewerRef.value = viewer; };
const onError = (error: Error) => console.error(error);
</script>

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

地图没有画面

首先检查父容器高度。CesiumMap 填满父容器，但父容器高度为 0 时不会显示地图。

API ​

属性 ​

名称类型默认值说明
ionTokenstring—Cesium ion Token；普通 XYZ 影像不需要
optionsCesiumMapOptions{}与组件默认 Viewer 配置浅合并

事件 ​

事件返回内容说明
load(viewer: Viewer) => void—
error(error: Error) => void—
left-click(result: PickResult) => void—
right-click(result: PickResult) => void—
double-click(result: PickResult) => void—
mouse-move(result: PickResult) => void—

插槽 ​

插槽名说明
defaultViewer 初始化完成后渲染的地图子组件，例如影像、实体、多边形和动态墙

暴露方法 ​

方法返回内容说明
getViewer()Viewer | null—

Viewer 就绪后才能调用相机、拾取等 API；页面卸载时，组件会销毁自己创建的 Viewer。

常用 Viewer 配置 ​

CesiumMap 默认关闭大部分 Cesium 自带控件，下面这些配置默认都是 false，业务需要时再打开：

配置作用
animation左下角动画控件
timeline页面底部时间轴
baseLayerPickerCesium 自带底图选择器
fullscreenButton全屏按钮
geocoder地理位置搜索框
homeButton返回初始视角按钮
infoBoxEntity 默认信息框
sceneModePicker2D、3D 和哥伦布模式切换
selectionIndicatorEntity 选中指示器
navigationHelpButton鼠标操作帮助按钮

其他 Cesium Viewer 构造参数也可以通过 options 透传。使用 CesiumImagery 自己加载底图时，推荐传入 { baseLayer: false }。

3D 公开能力索引 ​

分类公开能力文档位置
地图与图层CesiumMap、CesiumImagery、Cesium3DTileset快速开始、影像与三维模型
HTML 覆盖物CesiumHtmlOverlay：将 Vue/HTML 内容定位到三维坐标HTML 覆盖物
点、线、面和 MarkerCesiumEntity、CesiumPolygon、CesiumDropMarker、useEntityManager实体与业务标记、多边形
相机useCamera：单点飞入、立即定位、保存视角、按坐标或实体范围飞入相机飞入与屏幕交互
鼠标事件CesiumMap 的单击、右击、双击和移动事件相机与屏幕交互
业务效果CesiumDynamicWall动态墙
坐标与拾取工具toCartesian3、toDegrees、pickPosition、pickEntity直接使用工具函数
Cesium 原生能力Cesium、Viewer、Entity 等导出按需从 scene-mapping-gis/3d 引入

常用组合式函数 ​

名称什么时候使用
useCamera页面中需要飞入园区、定位地块、保存或恢复相机视角
useEntityManager接口返回多个实体，需要在业务代码中批量新增、更新、删除或查询
useCesium自定义子组件放在 CesiumMap 内部，需要获取当前 Viewer

自定义 3D 子组件可以直接获取父级 CesiumMap 提供的 Viewer：

vue
<script setup lang="ts">
import { onMounted } from "vue";
import { useCesium } from "scene-mapping-gis/3d";

const viewer = useCesium();

onMounted(() => {
  if (!viewer) return;
  // 在这里添加自定义 Primitive、数据源或其他 Cesium 内容。
});
</script>

<template><div style="display: none" /></template>

useCesium() 只适用于 CesiumMap 默认插槽内的子组件；普通业务页面应保存 load 事件返回的 Viewer。

哪些内部能力不需要业务调用 ​

名称说明
provideCesium / CESIUM_KEYCesiumMap 向子组件传递 Viewer 的内部上下文，业务页面不用重复提供
resolveViewer供组合式函数统一解析 Viewer 或 Viewer Ref，正常业务不需要直接调用
useScreenEventsCesiumMap 内部事件管理器；业务直接监听 left-click、right-click、double-click 和 mouse-move

这些文件保留是为了组件内部复用和清理生命周期，不代表业务接入时需要把所有 hooks 都调用一遍。

CesiumMap 组件实例 ​

通过组件 ref 可以调用 getViewer() 获取原生 Viewer。日常相机操作优先使用 useCamera，只有组件库暂未封装的 Cesium 功能才需要直接操作 Viewer。

vue
<script setup lang="ts">
import { ref } from "vue";
import { CesiumMap } from "scene-mapping-gis/3d";

const mapRef = ref<InstanceType<typeof CesiumMap>>();

function getOriginalViewer() {
  const viewer = mapRef.value?.getViewer();
  console.log(viewer);
}
</script>

<template>
  <CesiumMap ref="mapRef" />
</template>

下一步 ​

复杂类型可在 3D 类型声明 中查看完整声明。