底图与服务

无 Key 全球底图

await map.setSource({ type: 'naturalEarth' });

使用 Cesium 自带的 Natural Earth II 地理坐标瓦片（0–2 级），资源由复制 CLI 放入统一 assetBaseUrl。 无需网络地图账户或 ion，但仍需本地 HTTP 服务提供静态图片。只有全球低分辨率影像，城市缩放会模糊；需要城市细节时切换天地图。 保留 Natural Earth / Cesium 署名。示例配置 Key 后默认天地图矢量图及注记，否则使用此底图；网格只作调试。

天地图

const source = {
  type: 'tianditu' as const,
  key: import.meta.env.VITE_TIANDITU_KEY,
  style: 'vector' as const, // 或 'imagery'
};
await map.setSource(source);

key 必填且非空，style 只接受 vector / imagery。矢量组合为 vec_w + cva_w，影像组合为 img_w + cia_w，使用天地图 Web Mercator WMTS 矩阵 w。 此接口没有 Ion token 参数，也不会替你开通天地图服务。

天地图 key 会出现在浏览器请求中。必须由部署方确认账户、域名白名单、服务授权、额度、标识展示要求和商用条件。 “免费可申请”不代表无限额、可离线复制或可任意商用。真实服务可达性列入外部验收。

XYZ

await map.setSource({
  type: 'xyz',
  id: 'company-xyz',
  url: 'https://tiles.example.com/{z}/{x}/{y}.png',
  minimumLevel: 0,
  maximumLevel: 18,
  credit: '请替换为供应商要求的署名',
});

这是地址占位符，不是公共可用瓦片服务。XYZ 默认使用 Web Mercator 瓦片矩阵；若你的服务使用不同矩阵、TMS 行号或私有鉴权， 请先确认当前 provider 支持的 URL 模板和部署方案。SDK 没有通用请求头/服务端密钥配置项。

WMTS

await map.setSource({
  type: 'wmts',
  id: 'company-wmts',
  url: 'https://tiles.example.com/wmts',
  layer: 'basemap',
  style: 'default',
  format: 'image/png',
  tileMatrixSetID: '实际矩阵集标识',
  tilingScheme: 'webMercator', // 或 'geographic'
  // tileMatrixLabels: ['实际第零级标识', '实际第一级标识', ...],
  minimumLevel: 0,
  maximumLevel: 18,
  credit: '供应商署名',
});

layer、style、format、tileMatrixSetID 必填；style 必须是服务公布的非空标识。 从供应商的 GetCapabilities 获取矩阵集、层级标识、分辨率与边界信息，不能直接照抄占位符。 tileMatrixLabels 如有配置，应与实际请求层级逐级对应。SDK 不会自动解析 GetCapabilities 或重投影任意矩阵。

通用字段与切换

所有 source 都支持 id?；天地图、XYZ、WMTS 支持 credit?、maximumLevel?。XYZ / WMTS 另支持 minimumLevel?。Natural Earth 的资源与层级固定。 级别是非负整数，最大值不能小于最小值且不能超过 30。天地图使用第 1–18 级，默认最大 18，并在地图上显示署名；其他类型请显式设置供应商实际覆盖范围。 层级依据天地图官方 WMTS 能力文档，不会请求不存在的第 0 级。

setSource(source) 返回 Promise<void>；必须捕获 rejection。它的完成表示切换流程完成，不保证每一张瓦片已经下载， 之后仍可能出现 TILE_LOAD 事件。连续切换时不要把较早请求的完成误判为当前底图已经就绪。

HTTPS 页面必须使用 HTTPS 瓦片与图片。跨域服务必须允许浏览器访问，反向代理应由服务拥有者授权， 不能通过关闭浏览器安全策略解决 CORS。