第七篇：告别手动拼 URL！我们封装自己的“地图超市”

📘 专栏说明

本专栏旨在手把手带你从零开始，基于开源三维地球引擎 Cesium 封装一套功能完善、可复用的 WebGIS 增强型 SDK。内容涵盖核心封装思路、关键代码实现、常用 GIS 功能抽象，以及基于该 SDK 构建的 UI 组件库开发。如果你更关注结果而非实现过程，也可直接使用已发布的成果：

🌟 GitHub仓库 📦 NPM 包 ✨ 公众号：经纬码客（欢迎关注）

💡 建议：即便你打算直接使用 SDK，也推荐订阅本专栏 -- 理解设计思路，才能更灵活地扩展属于你自己的专属 GIS 能力！

由于作者需兼顾全职工作，更新主要安排在晚间或节假日，无法保证高频发布，但会持续迭代，直至 SDK 达到实际项目落地标准。届时将完整开源所有源码，供学习与商用（遵循许可证协议）。

大家好，我是 Cesium 酱（也可以叫我“本猿”），一名在 WebGIS 领域摸爬滚打多年的前端开发者。前几期，我们封装了 Viewer、增强了事件系统。

但还有一个高频痛点没解决：底图和地形的初始化太繁琐！

比如用天地图影像，原生要写：

const provider = new WebMapTileServiceImageryProvider({url: "https://t0.tianditu.gov.cn/img_w/wmts?SERVICE=WMTS&REQUEST=GetTile&...&tk=你的密钥",layer: "img",tileMatrixSetID: "w",// ... 还有七八个参数
})

不仅冗长，还容易出错，更别说换图时要重写整个配置。

今天，我们就把这一切简化成：

viewer.baseImagery = BaseLayer.DefaultTdtImg

准备好了吗？打开你的编辑器，继续我们的SDK建设之旅，我们一起来建这个“地图超市”！

🧱 第一步：明确目标 —— 我们要支持哪些图源？

国内开发者最常用的底图/地形包括：

✅ 单张静态图（用于离线或简单场景）
✅ ArcGIS Online 全球影像/街道图（现在链接好像失效了）
✅ 天地图影像 / 矢量 / 注记（需 token）
✅ Cesium 官方全球地形
✅ 自定义 TMS 地形（如本地部署的 terrain）

我们的 BaseLayer 就要为这些场景提供预设快捷方式。

📦 第二步：创建工具函数 —— 天地图参数生成器

首先，在 src/utils/imagery/ImageryOption.ts 中，封装天地图的 URL 拼接逻辑：

// src/utils/imagery/ImageryOption.ts
import { TDT_KEY } from "../def/Default" // 这里是我申请的默认 token
/*** 生成天地图 WMTS 服务配置* @param type 'img' 影像, 'vec' 矢量, 'cva' 矢量注记, 'cia' 影像注记* @param token 天地图开发者密钥*/
export function getTdtOption(type: "img" | "vec" | "cva" | "cia",token = TDT_KEY
) {const url = `https://{s}.tianditu.gov.cn/${type}_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=${type}&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILECOL={TileCol}&TILEROW={TileRow}&TILEMATRIX={TileMatrix}&tk=${token}`return {url,layer: type,style: "default",format: "tiles",tileMatrixSetID: "w",maximumLevel: 18,subdomains: ["t0", "t1", "t2", "t3", "t4", "t5", "t6", "t7"],token,}
}

✅ 从此以后，不用再手拼天地图 URL！

✅ 支持四种图层类型，自动适配子域名和最大层级。

💡 提示：TDT_KEY 可在 src/utils/def/Default.ts 中定义为你的默认 token，方便团队共享。

🏗️ 第三步：实现 BaseLayer 核心模块

新建 src/core/layers/BaseLayer.ts，这是我们的“地图超市”货架：

// src/core/layers/BaseLayer.ts
import {ImageryLayer,SingleTileImageryProvider,ArcGisMapServerImageryProvider,WebMapTileServiceImageryProvider,createWorldTerrainAsync,Terrain,CesiumTerrainProvider,
} from "cesium"
// 引入本地静态图（sdk里面就是一张蓝色地球背景）
import globeImg from "src/static/globe-img"
// 引入天地图配置生成器
import { getTdtOption } from "src/utils/imagery/ImageryOption"
/*** 基础图层类，包括影像底图和地形底图*/
const BaseLayer = {/*** 默认单图像底图（适用于离线或兜底场景）*/get DefaultSingleImg() {return ImageryLayer.fromProviderAsync(SingleTileImageryProvider.fromUrl(globeImg),{})},/*** 默认 ArcGIS 全球街道图*/get DefaultArcgisImg() {return ImageryLayer.fromProviderAsync(ArcGisMapServerImageryProvider.fromUrl("https://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"),{})},/*** 默认天地图影像地图*/get DefaultTdtImg() {const option = getTdtOption("img")return ImageryLayer.fromProviderAsync(Promise.resolve(new WebMapTileServiceImageryProvider(option)),{})},/*** 默认天地图矢量地图*/get DefaultTdtVec() {const option = getTdtOption("vec")return ImageryLayer.fromProviderAsync(Promise.resolve(new WebMapTileServiceImageryProvider(option)),{})},/*** 默认 Cesium 全球地形（带水体和法线）*/get DefaultTerrain() {const terrainProvider = createWorldTerrainAsync({requestWaterMask: true,requestVertexNormals: true,})return new Terrain(terrainProvider)},/*** 加载自定义 TMS 格式地形（如本地部署的 terrain）* @param url 地形服务根路径，如 "http://localhost:8080/terrain/"*/getTerrain(url: string): Terrain {return new Terrain(CesiumTerrainProvider.fromUrl(url))},
}
export default BaseLayer

✅ 所有图层都通过 getter 或方法暴露，使用时自动初始化。

✅ fromProviderAsync + Promise.resolve 确保异步兼容性。

✅ getTerrain() 支持任意 TMS 地形路径，灵活适配私有部署。

🔌 第四步：导出模块，让别人能用

修改 src/index.ts，将 BaseLayer 加入主入口：

// src/index.ts
export { Viewer } from "./core/Viewer"
export { default as BaseLayer } from "./core/layers/BaseLayer"
// 后续继续添加...

然后运行：

npm run build

构建成功后，BaseLayer 就可以在外部使用了！

🧪 第五步：本地测试 —— 一键切换底图！

<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1.0" /><title>003-底图调整</title><script src="./Cesium/Cesium.js"></script><link rel="stylesheet" href="./Cesium/Widgets/widgets.css" /><script src="./lib/arc3dlab.umd.js"></script><script src="./assests/dat.gui.min.js"></script><style>html,body {margin: 0;padding: 0;width: 100%;height: 100%;}#cesiumContainer {width: 100%;height: 100%;position: relative;}#gui-box {position: absolute;left: 5px;top: 5px;z-index: 99;}</style></head><body><div id="cesiumContainer"><div id="gui-box"></div></div><script>const viewer = new Arc3DLab.Viewer("cesiumContainer", {fpsShow: true,mapboxController: true,})initGui()function initGui() {const params = { message: "GUI面板-底图调整", "base-imagery": 0 }const gui = new dat.GUI({ autoPlace: false })const customContainer = document.getElementById("gui-box")customContainer.appendChild(gui.domElement)gui.add(params, "message")const baseImg = gui.add(params, "base-imagery", {SingleImage: 0,TDTImagery: 1,TDTVector: 2,ArcgisImagery: 3,})baseImg.onChange((val) => {const baseLayer = Arc3DLab.BaseLayerconst option = {0: baseLayer.DefaultSingleImg,1: baseLayer.DefaultTdtImg,2: baseLayer.DefaultTdtVec,3: baseLayer.DefaultArcgisImg,}const imagery = viewer.imageryLayers.add(option[val])viewer.baseImagery = option[val]})}</script></body>
</html>

刷新页面——

🎉 地球瞬间变成高清卫星影像！

✅ 无需拼 URL，无需查文档，一行代码搞定！