3D · 影像与三维模型

3D 文档 · CesiumImagery 与 Cesium3DTileset

影像图层负责地球表面的底图，3D Tiles 负责建筑、倾斜摄影等三维模型。二者都应放在 CesiumMap 的默认插槽中。

影像图层

API

属性

vue

<CesiumImagery
  type="xyz"
  url="https://server.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"
  :options="{ maximumLevel: 18 }"
  :show="true"
  :alpha="1"
/>

名称	类型	默认值	说明
`type`	`'xyz' \| 'tms' \| 'wmts' \| 'ion' \| 'default'`	`default`	Provider 类型
`url`	`string`	—	XYZ、TMS 或 WMTS 服务地址
`assetId`	`number`	`1`	Cesium ion 影像资源 ID
`show`	`boolean`	`true`	图层显隐
`alpha`	`number`	`1`	透明度，范围 0–1
`options`	`CesiumImageryOptions["options"]`	—	Provider 原生配置

不同类型最少需要的配置：

type	必填内容	实际使用的 Cesium Provider
`xyz`	`url`	`UrlTemplateImageryProvider`
`tms`	`url`	`TileMapServiceImageryProvider`
`wmts`	`url`，以及 `options` 中的 `layer`、`style`、`tileMatrixSetID`	`WebMapTileServiceImageryProvider`
`ion`	`assetId`，并给 `CesiumMap` 配置 `ionToken`	`IonImageryProvider`
`default`	无	不创建额外图层

type、url 或 assetId 改变时会重建图层；show 和 alpha 只更新现有图层。options 在创建 Provider 时读取，运行中修改它不会单独触发重建；确实需要切换参数时，可以同时更新 url 或通过 Vue key 重新挂载组件。示例使用公开的 ArcGIS World Imagery，生产环境应确认服务授权、限额和可用性。

天地图影像与中文注记

当前 3D 通过 CesiumImagery 的 WMTS 能力接入天地图，不需要额外安装插件。影像和中文注记是两个独立图层，需要同时添加；Key 由业务项目提供，组件库不会保存 Key。

text

VITE_TDT_KEY=你的天地图Key

vue

<template>
  <div class="map-container">
    <CesiumMap :options="{ baseLayer: false }">
      <!-- 影像底图 -->
      <CesiumImagery
        type="wmts"
        :url="`https://t{s}.tianditu.gov.cn/img_w/wmts?tk=${tdtKey}`"
        :options="imageryOptions"
      />

      <!-- 中文道路和地名注记，放在影像图层后面 -->
      <CesiumImagery
        type="wmts"
        :url="`https://t{s}.tianditu.gov.cn/cia_w/wmts?tk=${tdtKey}`"
        :options="labelOptions"
      />
    </CesiumMap>
  </div>
</template>

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

const tdtKey = import.meta.env.VITE_TDT_KEY;
const commonOptions = {
  style: "default",
  format: "tiles",
  tileMatrixSetID: "w",
  subdomains: ["0", "1", "2", "3", "4", "5", "6", "7"],
  maximumLevel: 18,
};

const imageryOptions = { ...commonOptions, layer: "img" };
const labelOptions = { ...commonOptions, layer: "cia" };
</script>

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

常用天地图组合如下：

底图	对应注记	用途
`img_w` / `layer: "img"`	`cia_w` / `layer: "cia"`	卫星影像与影像中文注记
`vec_w` / `layer: "vec"`	`cva_w` / `layer: "cva"`	矢量地图与矢量中文注记
`ter_w` / `layer: "ter"`	`cta_w` / `layer: "cta"`	地形晕渲与地形中文注记

w 表示 Web Mercator 瓦片方案。Cesium 中的点、线、面仍传经纬度，不需要因为换成天地图而改变组件数据格式；如果数据来自腾讯地图等 GCJ-02 地图，仍应先在业务层转换为适合 Cesium 展示的坐标。

天地图没有显示

依次检查 Key 是否有效、浏览器 Network 中是否出现 401/403、当前网络是否拦截 *.tianditu.gov.cn，并确认 CesiumMap 使用了 baseLayer: false，避免默认底图覆盖或重复加载。

XYZ、TMS 与 Cesium ion

vue

<!-- 通用 XYZ，URL 中使用 {z}/{x}/{y} -->
<CesiumImagery
  type="xyz"
  url="https://example.com/tiles/{z}/{x}/{y}.png"
  :options="{ maximumLevel: 18 }"
/>

<!-- 标准 TMS 服务 -->
<CesiumImagery type="tms" url="https://example.com/tms/" />

<!-- Cesium ion 影像；CesiumMap 需要配置 ionToken -->
<CesiumImagery type="ion" :asset-id="1" />

type="default" 或不传 type 时，CesiumImagery 不创建图层。需要完全使用 Cesium Viewer 自己的底图时，可以不放置该组件。

CesiumImagery 当前没有单独的 load 和 error 事件。图层服务异常时应在浏览器 Network 和控制台中检查请求；如果业务必须展示加载失败提示，可以通过原生 Viewer 获取图层 Provider 后监听 Cesium 原生错误事件。

WMTS 示例

vue

<CesiumImagery type="wmts" :url="wmtsUrl" :options="{
  layer: 'img', style: 'default', format: 'tiles',
  tileMatrixSetID: 'w', maximumLevel: 18,
}" />

3D Tiles 模型

API

属性

vue

<Cesium3DTileset
  url="https://example.com/tileset.json"
  :show="showBuildings"
  :maximum-screen-space-error="16"
  fly-to-on-load
  @load="onTilesetLoad"
  @error="onTilesetError"
/>

名称	类型	默认值	说明
`url`	`string`	—	`tileset.json` 地址，优先于 `assetId`
`assetId`	`number`	—	Cesium ion 资源 ID
`show`	`boolean`	`true`	是否显示
`flyToOnLoad`	`boolean`	`false`	加载后自动飞行定位
`maximumScreenSpaceError`	`number`	`16`	越小越清晰，性能开销越大

事件

事件	返回内容	说明
`load`	`Cesium3DTileset`	模型加载完成并加入场景后触发
`error`	`unknown`	地址、鉴权或模型资源加载失败时触发

插槽

插槽名	说明
`default`	无作用域的默认插槽，用于需要跟随该组件组织的自定义内容

类型声明

url 和 assetId 二选一，同时传入时优先使用 url。二者变化会异步重建模型；show 和 maximumScreenSpaceError 直接更新现有模型。加载失败时，应在 Network 面板检查跨域、证书、鉴权以及模型内部资源地址。

3D · 影像与三维模型 ​

影像图层 ​

API ​

属性 ​

天地图影像与中文注记 ​

XYZ、TMS 与 Cesium ion ​

WMTS 示例 ​

3D Tiles 模型 ​