API 参考

本页列出 JS SDK（版本 0.1.0）导出的全部类、方法与工具函数。用 <script> 引入时，下文的导出都挂在全局变量 GeoBridge 上，如 GeoBridge.GeoBridgeClient、GeoBridge.maskToken。

约定：

服务路径（参数 path）为服务名，服务在目录中时为 目录/服务名，如 'demo/city-roads'。SDK 会逐段编码，不要自己编码。
生成地址的方法（名称以 Url 结尾）只拼字符串，不发请求、不带 Key；要给地址补 Key 用 client.withKey()。
发请求的方法都返回 Promise，失败时抛 GeoBridgeError。

GeoBridgeClient

构造函数

new GeoBridgeClient(options: GeoBridgeClientOptions)

选项	类型	默认	说明
`baseUrl`	`string`	必填	平台根地址，http(s)，含上下文路径；不能带用户信息、查询串与片段；尾部 `/` 会去掉
`apiKey`	`string`	无	API Key；不给则匿名
`keyTransport`	`'header' \| 'query'`	`'header'`	Key 用请求头 `X-GeoBridge-Token` 还是查询参数 `token` 传递
`platformUrls`	`string[]`	`[]`	其他也属于本平台的地址前缀（规则同 `baseUrl`）；Key 同样会发往这些地址
`timeoutMs`	`number`	`30000`	单次尝试的超时，正数，不超过 2147483647
`retries`	`number`	`2`	GET 的重试次数，非负整数
`fetch`	`typeof fetch`	全局 `fetch`	自定义 `fetch`

抛出：TypeError，选项不合法时。

const client = new GeoBridge.GeoBridgeClient({ baseUrl: 'https://map-demo.geobridge.cn/geobridge-mapserver', apiKey: 'gb_xxx…' })

各选项的用法见 SDK 指南。

属性

属性	类型	说明
`baseUrl`	`string`	规范化后的平台根地址（无尾部 `/`）
`platformUrls`	`readonly string[]`	规范化后的其他平台地址前缀
`keyTransport`	`'header' \| 'query'`	Key 的传递方式
`hasApiKey`	`boolean`	是否配置了 Key（不暴露 Key 本身）
`services`	`ServicesApi`	服务接口，见 client.services
`maplibre`	`MaplibreApi`	MapLibre 集成，见 client.maplibre
`query`	`QueryApi`	要素查询，见 client.query
`cesium`	`CesiumApi`	CesiumJS 集成，见 client.cesium
`ogcApi`	`OgcApi`	OGC API（Features、Tiles）的读取，见 client.ogcApi
`openlayers`	`OpenLayersApi`	OpenLayers 集成，见 client.openlayers

String(client) 返回 GeoBridgeClient(<baseUrl>)，JSON.stringify(client) 只含 baseUrl 与 keyTransport，都不含 Key。

client.transformRequest

client.transformRequest(url: string, resourceType?: string): { url: string; headers?: Record<string, string> }

可直接交给 MapLibre 的 transformRequest 选项。平台地址按 keyTransport 加请求头或补 token；其他地址与匿名客户端原样返回。它是绑定好的箭头函数，可以直接传，不需要 .bind(client)。

new maplibregl.Map({ container: 'map', style, transformRequest: client.transformRequest })

client.withKey()

client.withKey(url: string): string

给平台地址补上查询参数 token（已有则替换），供不能加请求头的库使用。只做字符串处理，{z}/{y}/{x} 等模板占位符原样保留。匿名客户端或平台外的地址原样返回。

new ol.source.XYZ({ url: client.withKey(client.services.tileUrl('city-roads')) })

client.url()

client.url(path: string, query?: Record<string, string | number | boolean | null | undefined>): string

把相对路径接在 baseUrl 之后，并追加查询参数（值为 null、undefined 的项忽略）。不添加 Key。

client.url('rest/geodata/catalog', { f: 'json' }) // → 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/catalog?f=json'

client.isPlatformUrl()

client.isPlatformUrl(url: string): boolean

地址是否属于本平台（等于 baseUrl 或 platformUrls 中的某一项，或以「前缀/」开头）。先规范化地址再判断；相对地址与无法解析的地址返回 false。Key 只会发往返回 true 的地址。

client.request()

client.request<T = unknown>(path: string, options?: RequestOptions): Promise<T>

直接调用平台接口，SDK 没有封装的接口可以用它。按 keyTransport 自动带 Key，按重试规则重试。

参数	类型	说明
`path`	`string`	相对 `baseUrl` 的路径，或属于平台的绝对地址
`options.query`	`object`	查询参数
`options.method`	`'GET' \| 'POST'`	默认 `'GET'`
`options.body`	`URLSearchParams \| string`	POST 的表单体；GET 带 `body` 抛 `TypeError`
`options.signal`	`AbortSignal`	中止后抛 `ABORTED`
`options.as`	`'json' \| 'text'`	响应解析方式，默认 `'json'`

返回：解析后的响应。错误码：FOREIGN_URL（地址不属于平台）、TIMEOUT、ABORTED、NETWORK、REDIRECT、BAD_RESPONSE（不是有效 JSON）、SERVICE_ERROR、平台错误码与 HTTP_<状态>。'query' 模式下 POST 的 token 也放在地址的查询参数里，不放进表单体。

const meta = await client.request('rest/geodata/services/city-roads/FeatureServer/0', { query: { f: 'json' } })

client.services

服务的元数据、目录与各类地址。

services.list()

client.services.list(): Promise<ServiceSummary[]>

列出当前 Key（或登录用户）可访问的服务，调用服务目录接口。

返回：ServiceSummary[]，每项为 { path, name, folder, title, types, accessLevel }：path 为服务路径，folder 不在目录中时为 null，types 为已开启的服务能力，accessLevel 为 'PUBLIC'、'KEY' 或 'PRIVATE'。

错误码：匿名（不带 Key 且未登录）为 TOKEN_REQUIRED；Key 无效为 TOKEN_INVALID；响应缺少 services 为 BAD_RESPONSE。

限制：最多 1000 条，超出部分不返回，不分页；已停止的服务也会列出；摘要不含数据范围，请用 services.extent()。在线沙箱里不填 Key 时，即使已登录平台也会被拒绝（沙箱的预览不带登录状态）。

const list = await client.services.list()
console.log(list.map((s) => s.path))

services.extent()

client.services.extent(path: string): Promise<[number, number, number, number] | undefined>

服务的数据范围，经纬度 [minx, miny, maxx, maxy]，可直接交给 map.fitBounds()；得不到时为 undefined。

只读服务自身的元数据，不走目录接口，匿名访问公开服务即可。依次尝试：矢量瓦片 tiles.json 的 bounds（平台在没有数据范围时写的全球范围跳过）→ MapServer 元数据的 fullExtent → VectorTileServer 元数据的 fullExtent → 全球范围。fullExtent 只认 EPSG:4326 与 Web 墨卡托（3857、102100），其他坐标系的服务得不到范围。最多发 3 个请求。

错误码：需要 Key、无权限、网络错误等直接抛出；各类元数据都不可用（如服务不存在）时抛第一个错误。

const bounds = await client.services.extent('city-roads')
if (bounds) map.fitBounds(bounds, { padding: 20 })

services.get()

client.services.get(path: string, type: ServiceType): Promise<ServiceMetadata>

服务元数据（<类型>?f=json 的原样 JSON）。type 为 'MapServer'、'FeatureServer'、'VectorTileServer'，或三维服务类型（实验功能）。

const meta = await client.services.get('city-roads', 'MapServer')

services.layers()

client.services.layers(path: string): Promise<ServiceMetadata>

MapServer 的图层列表（MapServer/layers?f=json）。

services.tileJson()

client.services.tileJson(path: string): Promise<ServiceMetadata>

VectorTileServer 的 tiles.json。

services.styleUrl()

client.services.styleUrl(path: string): string

矢量瓦片服务的样式地址 …/VectorTileServer/resources/styles。要取样式内容请用 maplibre.serviceStyle()。

services.tileUrl()

client.services.tileUrl(path: string): string

MapServer 切片地址模板 …/MapServer/tile/{z}/{y}/{x}，行号 {y} 在前。

map.addSource('roads', { type: 'raster', tiles: [client.services.tileUrl('city-roads')], tileSize: 256 })

services.vectorTileUrl()

client.services.vectorTileUrl(path: string): string

矢量瓦片地址模板 …/VectorTileServer/tile/{z}/{y}/{x}.pbf。

services.wmtsCapabilitiesUrl()

client.services.wmtsCapabilitiesUrl(path: string): string

WMTS 能力文档地址 …/MapServer/WMTS/1.0.0/WMTSCapabilities.xml。服务需要在发布时开启 WMTS。在地图库中加载 WMTS 请用 maplibre.addWmtsService()、openlayers.wmtsSource() 或 cesium.wmtsImageryProvider()。

services.wmsUrl()、services.wfsUrl()

client.services.wmsUrl(path: string): string
client.services.wfsUrl(path: string): string

WMS、WFS 入口 …/MapServer/WMSServer、…/MapServer/WFSServer。服务需要在发布时开启 WMS 或 WFS，见 WMS 与 WFS。

services.wmtsUrl()、services.wcsUrl()

client.services.wmtsUrl(path: string): string
client.services.wcsUrl(path: string): string

WMTS 的 KVP 入口 …/MapServer/WMTS，WCS 2.0.1 入口 …/MapServer/WCS（能力文档为 …/MapServer/WCS?SERVICE=WCS&REQUEST=GetCapabilities）。服务需要在发布时开启 WMTS 或 WCS（WCS 只对栅格图层提供）。

bash

# 用 GDAL 列出覆盖并下载（API Key 级别的服务在地址后加 &token=<API Key>）
gdalinfo "WCS:https://gis.example.com/geobridge-mapserver/rest/geodata/services/dem/MapServer/WCS?version=2.0.1"

services.tmsUrl()

client.services.tmsUrl(path: string, tileMatrixSet?: string, format?: string): string

TMS 1.0.0 地址。服务需要在发布时开启 TMS。

参数	说明
`path`	服务路径
`tileMatrixSet`	不给时返回 TileMapService 文档地址 `…/MapServer/tms/1.0.0`；给出时返回该 TileMap 的瓦片模板 `…/tms/1.0.0/<服务名>@<矩阵集>@<格式>/{z}/{x}/{y}.<格式>`，矩阵集如 `WebMercatorQuad`、`WorldCRS84Quad`
`format`	瓦片格式扩展名：`png`（默认）、`jpg`、`pbf`（矢量瓦片）

TMS 的行号自下而上：MapLibre 的数据源写 scheme: 'tms'，OpenLayers 的 XYZ 源用 {-y}。TileMap 中的瓦片地址不带 Key，API Key 级别的服务请用 client.transformRequest（MapLibre）或 client.withKey() 补上。

map.addSource('tms', { type: 'raster', scheme: 'tms', tileSize: 256, tiles: [client.services.tmsUrl('city-basemap', 'WebMercatorQuad')] })

services.ogcApiUrl()

client.services.ogcApiUrl(path: string, tail?: string): string

OGC API 地址：不给 tail 时为 landing 页 …/ogcapi，否则为其下的相对路径，如 ogcApiUrl('poi', 'collections')。服务需要在发布时开启 OGC API。读取 OGC API 的内容请用 client.ogcApi。

services.wmtsCapabilities()

client.services.wmtsCapabilities(path: string, options?: { signal?: AbortSignal }): Promise<WmtsCapabilities>

读取并解析 WMTS 能力文档，返回其中的图层（identifier、formats、styles、tileMatrixSets、resourceUrls、wgs84BoundingBox）与矩阵集（identifier、supportedCrs、tileMatrices）。解析需要 DOMParser：浏览器中可直接使用，Node 中请先提供全局 DOMParser。

错误码：响应不是 WMTS 能力文档时为 BAD_RESPONSE；其他同 client.request()。

const caps = await client.services.wmtsCapabilities('city-basemap')
console.log(caps.layers.map((l) => l.identifier), caps.tileMatrixSets.map((s) => s.identifier))

services.legendUrl()

client.services.legendUrl(path: string, layer: string): string

WMS GetLegendGraphic 图例地址（1.3.0、PNG、20×20）。layer 为 WMS 图层名，可用 wmsLayerNames() 从图层列表生成。需要服务开启 WMS。

img.src = client.withKey(client.services.legendUrl('city-roads', '道路_线'))

地址不带 SCALE，图例列出样式中的全部等级（同名规则合并为一行）。只想显示当前缩放级别下可见的等级时，追加比例尺分母并在缩放结束后更新：

const update = () => {
  const scale = Math.round(279541132 / 2 ** map.getZoom())
  img.src = client.withKey(`${client.services.legendUrl('city-roads', '道路_线')}&SCALE=${scale}`)
}
map.on('moveend', update)
update()

参数含义见 WMS 的 GetLegendGraphic。

三维服务的地址与元数据

实验功能

三维服务需要平台开启三维开关（GEOBRIDGE_FEATURE_3D=true，见功能开关）。开关关闭时三维服务的接口不存在，下列请求得到 404。

ServiceType 另有四种三维类型：'Cesium3DTileServer'（3D Tiles，含点云与高斯泼溅）、'MeshTerrainServer'（网格地形）、'RasterTerrainServer'（栅格地形）、'3DModelServer'（三维模型），可用于 services.get()。

方法	返回	说明
`tilesetUrl(path)`	`string`	3D Tiles 服务的 `…/Cesium3DTileServer/tile/tileset.json`
`tilesetMetadata(path)`	`Promise<TilesetServiceMetadata>`	3D Tiles 服务的元数据，见下文
`meshTerrainUrl(path)`	`string`	网格地形的根地址 `…/MeshTerrainServer/tile/`（以 `/` 结尾，Cesium 在其下读取 `layer.json`）
`layerJson(path)`	`Promise<MeshTerrainLayerJson>`	网格地形的 `layer.json`
`terrainTileJsonUrl(path)`	`string`	栅格地形的 `…/RasterTerrainServer/tile/tiles.json`
`terrainTileJson(path)`	`Promise<RasterTerrainTileJson>`	栅格地形的 `tiles.json`
`terrainTileUrl(path, png?)`	`string`	栅格地形切片模板 `…/RasterTerrainServer/tile/{z}/{x}/{y}`，列号 `{x}` 在前（与 MapServer 切片相反）；`png` 为 `true` 时为 `…/{y}.png`（由高程图层生成的服务）
`models(path)`	`Promise<ServiceModel3D[]>`	三维模型服务的模型清单，见下文
`extent3d(path, type?)`	`Promise<[number, number, number, number] \| undefined>`	三维服务的经纬度范围，见下文

tilesetMetadata() 的返回：{ name, extent, center, tilesetUrl, pointCloud? }。extent 为 { xmin, ymin, xmax, ymax }（经纬度），center 为 { lng, lat, height }（椭球高，米），无法计算时为 null；tilesetUrl 为绝对地址。由 LAS / LAZ 点云发布的服务另有 pointCloud：

字段	说明
`status`	`'none'` 尚未生成、`'processing'` 生成中、`'ready'` 可用、`'failed'` 失败
`progress`、`error`	进度（0–100）与失败原因
`points`、`tiles`	点数与瓦片数（可用时）
`crs`	源数据的坐标系，如 `'EPSG:2992'`
`attributes`	逐点属性名，如 `['Intensity', 'Classification', 'ReturnNumber', 'NumberOfReturns']`，可用于点云着色
`rgb`	点是否带颜色

models() 的每一项（ServiceModel3D）：

字段	说明
`file`、`name`	服务内的文件路径与显示名
`kind`	`'gltf'`（glTF / glb）、`'splat'`（高斯泼溅 .ply / .splat / .spz）或 `'unsupported'`
`url`、`thumbUrl`	原始文件与缩略图的绝对地址（不带 Key）
`placement`	默认位置 `{ lng, lat, alt, heading, pitch, roll, scale }`，角度为度（heading 从正北顺时针），未设置时为 `null`
`tilesStatus`、`tilesProgress`、`tilesError`	泼溅转换为 3D Tiles 的状态、进度与失败原因
`tilesetUrl`	泼溅转换出的 3D Tiles 地址；转换完成且设置了默认位置时才有

extent3d() 的来源：3D Tiles 取元数据的 extent；三维模型取各模型默认位置的范围；网格地形取 layer.json 的 bounds（全球范围除外）或可用瓦片的范围；栅格地形只对由高程图层生成的服务给出范围。不给 type 时按上述顺序逐类尝试，最后退回 services.extent()；已知类型时请给出，避免多余的请求。

const meta = await client.services.tilesetMetadata('pointcloud')
if (meta.pointCloud && meta.pointCloud.status !== 'ready') console.log('点云还在生成：', meta.pointCloud.progress, '%')

client.maplibre

maplibre.serviceStyle()

client.maplibre.serviceStyle(path: string): Promise<Record<string, unknown>>

取矢量瓦片服务的 MapLibre 样式 JSON，可直接作为地图的 style 或交给 map.setStyle()。

错误码：响应不是对象时为 BAD_RESPONSE；其他同 client.request()。'header' 模式且带 Key 时，样式中有不属于平台的地址会在控制台警告一次，见 SDK 指南。

const map = new maplibregl.Map({ container: 'map', style: await client.maplibre.serviceStyle('city-roads'), transformRequest: client.transformRequest })

maplibre.mapStyleUrl()

client.maplibre.mapStyleUrl(mapId: string): string

地图方案的公开样式地址 …/rest/geodata/maps/<方案 id>/style.json，见地图方案与工作台。

const map = new maplibregl.Map({ container: 'map', style: client.maplibre.mapStyleUrl('<方案 id>'), transformRequest: client.transformRequest })

maplibre.addVectorTileService()

client.maplibre.addVectorTileService(map: MapLike, path: string, options?: { sourceId?: string; beforeId?: string }): Promise<LayerHandle>

把矢量瓦片服务的数据源与图层加进已有地图。

参数	说明
`map`	MapLibre 地图；需在 `load` 事件之后调用
`path`	服务路径
`options.sourceId`	数据源与图层 id 的前缀，默认 `'gb:' + path`；服务样式中的数据源与图层 id 变为 `<sourceId>:<原 id>`
`options.beforeId`	插到该图层之前；不给时加在最上面

返回：LayerHandle，{ sourceId, layerIds, remove() }。layerIds 只含实际加进地图的图层；remove() 移除本次加入的图层与数据源，可重复调用。

行为：

服务样式中的 background 图层被跳过。
地图上已有同 id 的数据源或图层时抛 ID_CONFLICT，地图不做任何改动。中途 addLayer 抛错时撤销本次的全部改动后抛出原错误。
字体：地图没有 glyphs 时设为服务样式的；地图已有且不同时保留地图的。只有服务里有文字注记图层（symbol 且设置了 text-field）时才警告，服务注记用到地图字体中没有的字体时显示不出来；只有线、面或图标的服务不警告。同一平台各服务的字体地址只差服务路径，实际是平台统一的字体，视为相同，叠加同一平台的多个服务不会因此警告。
图标：地图没有 sprite 时设为服务样式的；地图已有且不同时，跳过引用图标的图层（icon-image 与 fill-pattern、line-pattern 等）并警告列出被跳过的图层。
MapLibre 校验不通过的图层不会加入（MapLibre 只发 error 事件），也不计入 layerIds。
remove() 不撤销已设置的字体与图标（地图上其他图层可能在用）。

错误码：ID_CONFLICT；INVALID_STYLE（服务样式中有图层缺少 id）；其他同 serviceStyle()。

map.on('load', async () => {
  const handle = await client.maplibre.addVectorTileService(map, 'city-roads', { sourceId: 'roads' })
  // 之后移除：handle.remove()
})

maplibre.addRasterService()

client.maplibre.addRasterService(map: MapLike, path: string, options?: { sourceId?: string; beforeId?: string; tileSize?: number }): LayerHandle

把 MapServer 切片作为栅格数据源与图层加进已有地图。数据源 id 为 sourceId（默认 'gb:' + path），图层 id 为 <sourceId>:raster，tileSize 默认 256。同步返回 LayerHandle。

错误码：同 id 已存在时抛 ID_CONFLICT。

const basemap = client.maplibre.addRasterService(map, 'city-basemap', { beforeId: 'roads:道路' })

maplibre.addWmtsService()

client.maplibre.addWmtsService(map: MapLike, path: string, options?: MaplibreWmtsOptions): Promise<LayerHandle>

把服务的 WMTS 图层作为栅格数据源与图层加进已有地图。先读取 WMTS 能力文档，选出图层、矩阵集与格式，用图层的瓦片地址模板生成 {z}/{y}/{x} 地址；级别范围取矩阵集中实际有的级别，数据范围取图层的经纬度范围。服务需要开启 WMTS。

参数	说明
`map`	MapLibre 地图；需在 `load` 事件之后调用
`path`	服务路径
`options.layer`	WMTS 图层标识，默认第一个图层（服务的地图整体）；按需出图的服务另有每个子图层
`options.tileMatrixSet`	矩阵集，默认 `WebMercatorQuad`，其次 `GoogleMapsCompatible`
`options.format`	瓦片格式（媒体类型），如 `image/jpeg`；默认图层的第一种
`options.sourceId`	数据源 id，默认 `'gb:' + path + ':wmts'`；图层 id 为 `<sourceId>:raster`
`options.beforeId`	插到该图层之前

行为：

MapLibre 只支持 Web 墨卡托四叉树网格。矩阵集为 WorldCRS84Quad、CGCS2000Quad 或预切服务按切片方案推导的矩阵集时抛 WMTS_UNSUPPORTED，消息中列出可用的 Web 墨卡托矩阵集；这些矩阵集请用 openlayers.wmtsSource() 或 cesium.wmtsImageryProvider()。
图层格式为矢量瓦片时抛 WMTS_UNSUPPORTED，请改用 addVectorTileService() 或 addOgcApiTiles()。
瓦片地址按 baseUrl 生成（能力文档里的地址以平台对外地址为前缀，可能与 baseUrl 不同），由地图的 transformRequest: client.transformRequest 带上 Key。

错误码：ID_CONFLICT、WMTS_UNSUPPORTED（图层、矩阵集或格式不存在，或不受支持）；能力文档请求失败时同 client.request()。

map.on('load', async () => {
  const wmts = await client.maplibre.addWmtsService(map, 'city-basemap', { format: 'image/jpeg' })
  // 之后移除：wmts.remove()
})

maplibre.addOgcApiTiles()

client.maplibre.addOgcApiTiles(map: MapLike, path: string, options: MaplibreOgcTilesOptions): Promise<LayerHandle>

把 OGC API - Tiles 的瓦片加进已有地图。读取 WebMercatorQuad 瓦片集的元数据，从中取瓦片地址模板、级别范围与数据范围。服务需要开启 OGC API。

参数	说明
`options.kind`	必填。`'vector'`：矢量瓦片（MVT，服务需同时提供矢量切片）；`'map'`：服务端渲染的地图瓦片（PNG / JPEG）
`options.collection`	集合 id；不给时为整个服务
`options.format`	地图瓦片的格式，默认 `image/png`，可选 `image/jpeg`
`options.layers`	矢量瓦片的图层定义（MapLibre 图层，不写 `source`，须有 `source-layer`）。不给时按元数据中的图层生成默认样式：点为圆点，线为线，面为填充加轮廓
`options.sourceId`	数据源 id，默认 `'gb:' + path + ':ogc…'`；图层 id 以 `<sourceId>:` 为前缀
`options.beforeId`	插到该图层之前

错误码：ID_CONFLICT；OGC_UNSUPPORTED（要矢量瓦片而服务只有地图瓦片、没有该格式的瓦片、元数据中没有图层且未给 layers）；kind 不合法时抛 TypeError。

map.on('load', async () => {
  // 矢量瓦片，按默认样式显示
  await client.maplibre.addOgcApiTiles(map, 'city-roads', { kind: 'vector' })
  // 某个集合的地图瓦片
  await client.maplibre.addOgcApiTiles(map, 'city-basemap', { kind: 'map', collection: 'dem' })
})

maplibre.setRasterTerrain()

实验功能

需要平台开启三维开关，见功能开关。

client.maplibre.setRasterTerrain(map: TerrainMapLike, path: string, options?: RasterTerrainOptions): Promise<LayerHandle>

把栅格地形服务作为 MapLibre 的三维地形：加入 raster-dem 数据源并调用 map.setTerrain()，可选加山体阴影图层。

参数	说明
`map`	MapLibre 地图（maplibre-gl 5 或 6）；需在 `load` 事件之后调用
`path`	栅格地形服务的路径
`options.sourceId`	地形数据源 id，默认 `'gb:' + path + ':terrain'`
`options.exaggeration`	地形夸张系数，默认 `1`
`options.hillshade`	是否加山体阴影图层，默认 `false`
`options.hillshadeExaggeration`	山体阴影的强度（0–1），默认 `0.5`
`options.beforeId`	山体阴影图层插到该图层之前

行为：

先读取服务的 tiles.json：由高程图层生成的服务采用其中的高程编码、切片尺寸、级别范围与数据范围；预生成切片的服务按 Mapbox 编码、512 像素、最大 14 级加载，更高级别由 MapLibre 放大。
山体阴影使用单独的数据源 <sourceId>:hillshade（与地形共用一个数据源时 MapLibre 会给出精度警告），图层 id 也是 <sourceId>:hillshade。
已有同 id 的数据源或图层时抛 ID_CONFLICT，不发请求、不改动地图；addLayer 或 setTerrain 抛错时撤销本次的改动后抛出原错误。
切片请求由地图的 transformRequest: client.transformRequest 带上 Key。

返回：LayerHandle。remove() 撤销地形（地图当前的地形仍是本次设置的才撤销）并移除山体阴影图层与数据源，可重复调用。

错误码：ID_CONFLICT；tiles.json 不可用时同 client.request()；tiles.json 不是对象为 BAD_RESPONSE。exaggeration 不是非负有限数时抛 TypeError。

const map = new maplibregl.Map({ container: 'map', style: client.maplibre.mapStyleUrl('<方案 id>'), transformRequest: client.transformRequest, pitch: 60 })
map.on('load', async () => {
  const terrain = await client.maplibre.setRasterTerrain(map, 'dem', { exaggeration: 1.5, hillshade: true })
  // 之后移除：terrain.remove()
})

client.cesium

实验功能

需要平台开启三维开关，见功能开关。引入 CesiumJS 的方式见 SDK 指南：在 Cesium 中使用。

在 CesiumJS 中加载平台的三维服务。SDK 不包含 Cesium：每个方法的第一个参数是你的 Cesium 命名空间对象（import * as Cesium from 'cesium'，或用 <script> 引入后的全局变量 Cesium），需要 CesiumJS 1.146 及以上。使用 TypeScript 并传入真实的 Cesium 时，返回值是 Cesium 自己的类型（Cesium3DTileset、Model 等）。

参数 viewerOrScene 可以是 Viewer、CesiumWidget 或 Scene。加载失败时抛 GeoBridgeError：Cesium 请求失败为 HTTP_<状态>（如 HTTP_401、HTTP_404），网络不通为 NETWORK，内容无法解析为 BAD_RESPONSE。

cesium.resource()

client.cesium.resource(Cesium, url: string): Cesium.Resource

带 Key 的 Cesium.Resource：平台地址按 keyTransport 加 X-GeoBridge-Token 请求头（'header'）或 token 查询参数（'query'）；平台外的地址与没有 Key 的客户端不带 Key。由它派生的请求（3D Tiles 的子瓦片、地形瓦片）沿用同样的 Key。下面的方法内部都用它加载数据；自行用 Cesium 加载平台地址时也请用它。

const url = client.services.tilesetUrl('city-3d')
const tileset = await Cesium.Cesium3DTileset.fromUrl(client.cesium.resource(Cesium, url))

cesium.terrainProvider()

client.cesium.terrainProvider(Cesium, path: string, options?: { requestVertexNormals?: boolean; requestWaterMask?: boolean; requestMetadata?: boolean }): Promise<Cesium.CesiumTerrainProvider>

网格地形服务的地形提供者。requestVertexNormals 默认 true（地形光照需要），requestWaterMask 默认 false，requestMetadata 默认 true。

viewer.terrainProvider = await client.cesium.terrainProvider(Cesium, 'terrain-mesh')
// 或者不等待：viewer.scene.setTerrain(new Cesium.Terrain(client.cesium.terrainProvider(Cesium, 'terrain-mesh')))

cesium.addTileset()

client.cesium.addTileset(Cesium, viewerOrScene, path: string, options?: CesiumTilesetOptions): Promise<Cesium.Cesium3DTileset>

加载 3D Tiles 服务（三维网格、点云、高斯泼溅）并加入场景。高斯泼溅由 Cesium 自动识别，不需要额外设置。

参数	说明
`options.maximumScreenSpaceError`	最大屏幕空间误差，越小越精细，默认 `16`
`options.heightOffset`	沿数据中心处的竖直方向整体平移（米），默认 `0`；可用于把数据抬到地形之上
`options.flyTo`	加载后飞到数据，默认 `false`
`options.duration`	飞行时长（秒）
`options.tilesetOptions`	其他交给 `Cesium3DTileset.fromUrl` 的选项（上面的同名项优先）

const tileset = await client.cesium.addTileset(Cesium, viewer, 'city-3d', { flyTo: true })

cesium.pointCloudStyle()

client.cesium.pointCloudStyle(Cesium, tileset, by: 'rgb' | 'classification' | 'intensity' | 'height', options?: PointCloudStyleOptions): Cesium.Cesium3DTileStyle

点云的着色样式，赋给 tileset.style 即可。

`by`	着色
`'rgb'`	点自带的颜色（只设点大小）
`'classification'`	按 ASPRS LAS 标准分类配色：地面、低 / 中 / 高植被、建筑、噪点、水体、桥梁，其余为浅灰（配色见常量 `CLASSIFICATION_COLORS`）
`'intensity'`	按强度灰度拉伸，范围取瓦片集 `properties` 中的最小、最大值，没有时为 0–255
`'height'`	按椭球高从蓝到红渐变，范围取瓦片集记录的高程范围，没有时按包围体估算

参数	说明
`options.pointSize`	点大小（像素，1–20），默认 `2`
`options.property`	分类或强度所用的属性名；默认在瓦片集的属性中不区分大小写地查找 `Classification`、`Intensity`
`options.range`	强度的拉伸范围 `{ min, max }`
`options.heightRange`	高程渐变的范围 `{ min, max }`（米，椭球高）
`options.classificationColors`	覆盖或补充分类配色，如 `{ 2: '#8b5a2b', 6: 'orange' }`

可用的着色方式取决于数据：点带颜色才有 'rgb'，有对应属性才有分类、强度，高程总是可用。可从 tilesetMetadata() 返回的 pointCloud.rgb 与 pointCloud.attributes 判断。

抛出：TypeError，by 不认识或颜色写法不支持时。

const tileset = await client.cesium.addTileset(Cesium, viewer, 'pointcloud', { flyTo: true })
tileset.style = client.cesium.pointCloudStyle(Cesium, tileset, 'classification', { pointSize: 3 })

cesium.addModels()

client.cesium.addModels(Cesium, viewerOrScene, path: string, options?: CesiumModelsOptions): Promise<{ models, tilesets, skipped, remove() }>

加载三维模型服务中的模型并加入场景：

glTF / glb 按默认位置（经纬度、高度、heading / pitch / roll、缩放）放置，与平台控制台中看到的位置与朝向一致；
高斯泼溅转换出 3D Tiles 后按 3D Tiles 加载（已按默认位置定位）；
没有默认位置、泼溅尚未转换完成、格式不支持或单个模型加载失败时不中断，列在 skipped 中。

参数	说明
`options.files`	只加载这些文件（清单中的 `file`）；默认全部
`options.flyTo`	加载后飞到模型所在范围，默认 `false`
`options.duration`	飞行时长（秒）
`options.maximumScreenSpaceError`	泼溅 3D Tiles 的最大屏幕空间误差，默认 `16`

字段	说明
`models`	`[{ file, name, model }]`，`model` 为 `Cesium.Model`
`tilesets`	`[{ file, name, tileset }]`，泼溅的 `Cesium.Cesium3DTileset`
`skipped`	`[{ file, name, kind, reason, message, error? }]`；`reason` 为 `'no-placement'`（没有默认位置）、`'splat-no-tiles'`（泼溅还没有可用的 3D Tiles）、`'unsupported'`（格式不支持）、`'load-failed'`（加载失败，`error` 为 `GeoBridgeError`）
`remove()`	从场景中移除本次加入的全部模型与瓦片集，可重复调用

错误码：模型清单不可用时抛出，同 client.request()；服务不存在为 SERVICE_ERROR。

const { models, tilesets, skipped } = await client.cesium.addModels(Cesium, viewer, 'models', { flyTo: true })
for (const s of skipped) console.warn(s.name, s.message)

cesium.flyToExtent()

client.cesium.flyToExtent(Cesium, camera, path: string, options?: { type?: ServiceType3D; duration?: number; pitch?: number }): Promise<[number, number, number, number] | undefined>

按服务的数据范围斜视飞行（范围来自 services.extent3d()，过小的范围适当扩大）。camera 可以是 viewer.camera，也可以直接传 Viewer、CesiumWidget 或 Scene。options.type 为服务类型，已知时请给出；options.pitch 为俯仰角（度），默认 -35。

返回：所用的范围；得不到范围时为 undefined，不飞行。

await client.cesium.flyToExtent(Cesium, viewer, 'terrain-mesh', { type: 'MeshTerrainServer' })

cesium.wmtsImageryProvider()

client.cesium.wmtsImageryProvider(Cesium, path: string, options?: CesiumWmtsOptions): Promise<Cesium.WebMapTileServiceImageryProvider>

服务的 WMTS 图层作为 Cesium 影像。读取 WMTS 能力文档，选出图层、矩阵集与格式：矩阵集为 Web 墨卡托时用 WebMercatorTilingScheme，为 WorldCRS84Quad、CGCS2000Quad 等经纬度网格时用 GeographicTilingScheme；tileMatrixLabels 取能力文档中的矩阵标识，级别范围取矩阵集中实际有的级别，影像范围取图层的经纬度范围。瓦片请求经 cesium.resource() 带上 Key。服务需要开启 WMTS；不需要三维开关。

参数	说明
`Cesium`	Cesium 命名空间（用到 `Resource`、`WebMapTileServiceImageryProvider`、`WebMercatorTilingScheme`、`GeographicTilingScheme`、`Rectangle`）
`options.layer`	图层标识，默认第一个图层
`options.tileMatrixSet`	矩阵集，默认依次取 `WebMercatorQuad`、`GoogleMapsCompatible`、`WorldCRS84Quad`、`CGCS2000Quad` 中图层有的第一个
`options.format`	瓦片格式（媒体类型），默认图层的第一种
`options.providerOptions`	其他交给 `WebMapTileServiceImageryProvider` 的选项，如 `credit`
`options.signal`	读取能力文档的中止信号

错误码：WMTS_UNSUPPORTED（图层、矩阵集或格式不存在；矩阵集不是 Web 墨卡托或经纬度四叉树网格，如预切服务按切片方案推导的矩阵集）；能力文档请求失败时同 client.request()。

const provider = await client.cesium.wmtsImageryProvider(Cesium, 'city-basemap', { tileMatrixSet: 'CGCS2000Quad' })
viewer.imageryLayers.addImageryProvider(provider)

placementLocalMatrix()

placementLocalMatrix(placement: ModelPlacement): number[]

模型默认位置在东-北-上局部坐标中的旋转与缩放矩阵（列主序 4×4，平移为 0），已抵消 Cesium 对 glTF 的 y 轴向上校正。完整的模型矩阵为 Transforms.eastNorthUpToFixedFrame(位置) × 本矩阵；addModels() 内部即如此计算，自行加载模型时可以使用。

const p = model.placement
const frame = Cesium.Transforms.eastNorthUpToFixedFrame(Cesium.Cartesian3.fromDegrees(p.lng, p.lat, p.alt))
const modelMatrix = Cesium.Matrix4.multiply(frame, Cesium.Matrix4.fromArray(GeoBridge.placementLocalMatrix(p)), new Cesium.Matrix4())

client.ogcApi

读取服务的 OGC API（Features 与 Tiles）。服务需要在发布时开启 OGC API。请求带 Key 的方式同 client.request()；所有请求都带 f=json。OGC API 的错误响应为 application/problem+json，同样转为 GeoBridgeError。

ogcApi.landing()、ogcApi.conformance()

client.ogcApi.landing(path: string): Promise<{ title?: string; description?: string; links: OgcLink[] }>
client.ogcApi.conformance(path: string): Promise<{ conformsTo: string[] }>

landing 页（标题、描述与链接）与一致性声明。

ogcApi.collections()、ogcApi.collection()、ogcApi.queryables()

client.ogcApi.collections(path: string): Promise<OgcCollections>
client.ogcApi.collection(path: string, collection: string): Promise<OgcCollection>
client.ogcApi.queryables(path: string, collection: string): Promise<Record<string, unknown>>

集合列表、单个集合的描述与可查询属性（JSON Schema）。要素集合（itemType 为 feature）对应服务中的矢量图层，可读取要素；栅格等图层也列为集合，只有地图与瓦片。

const { collections } = await client.ogcApi.collections('poi')
const features = collections.filter((c) => c.itemType === 'feature').map((c) => c.id)

ogcApi.items()

client.ogcApi.items(path: string, collection: string, params?: OgcItemsParams): Promise<OgcFeatureCollection>

读取一页要素，返回 GeoJSON FeatureCollection，另有 links（rel: 'next' 为下一页）、numberReturned 与 timeStamp。

`params`	类型	说明
`bbox`	`number[]`	`[minx, miny, maxx, maxy]`（或含高程的 6 个数），按 `bboxCrs` 的坐标轴顺序；缺省坐标系为经纬度（经度在前）
`bboxCrs`	`string`	`bbox` 的坐标系 URI，如 `http://www.opengis.net/def/crs/EPSG/0/3857`
`limit`	`number`	每页条数；缺省 10，超过图层的每页上限时按上限返回
`offset`	`number`	起始偏移
`filter`	`string`	CQL2 文本过滤条件，如 `"name LIKE '学%' AND S_INTERSECTS(geometry, BBOX(113,22,114,23))"`
`filterCrs`	`string`	`filter` 中几何的坐标系 URI
`crs`	`string`	输出坐标系 URI，缺省经纬度
`datetime`	`string`	时刻或区间，如 `2024-01-05`、`2024-01-01/..`
`properties`	`Record<string, string \| number \| boolean>`	属性等值过滤，字段为可查询属性中列出的字段
`signal`	`AbortSignal`	中止信号

bbox 不是 4 个或 6 个有限数、limit 不是正整数、offset 不是非负整数、properties 的字段与标准参数同名时抛 TypeError。支持的 CQL2 运算与坐标系见 OGC API。

const fc = await client.ogcApi.items('poi', 'pois', { bbox: [113.8, 22.1, 114.4, 22.6], filter: "类别 = '学校'", limit: 100 })

ogcApi.allItems()

client.ogcApi.allItems(path: string, collection: string, params?: OgcItemsParams, options?: OgcAllItemsOptions): Promise<OgcFeatureCollection>

沿 next 链接依次读取，直到没有下一页或达到 maxFeatures，合并为一个 FeatureCollection。params 同 ogcApi.items()，其中 offset 为起点，limit 不生效（用 pageSize）。

`options`	类型	默认	说明
`pageSize`	`number`	`1000`	每页条数（服务端按图层的每页上限截断）
`maxFeatures`	`number`	`10000`	最多取回的要素数
`signal`	`AbortSignal`	无	中止后抛 `code === 'ABORTED'` 的错误

达到 maxFeatures 时停止；此时还有下一页的，结果的 properties.exceededTransferLimit 为 true。next 链接以平台的对外地址为前缀，与 baseUrl 不同时按 baseUrl 改写，Key 只发往本平台。

const all = await client.ogcApi.allItems('poi', 'pois', { filter: "类别 = '学校'" }, { maxFeatures: 50000 })

ogcApi.item()、ogcApi.itemsUrl()

client.ogcApi.item(path: string, collection: string, featureId: string | number, options?: { crs?: string; signal?: AbortSignal }): Promise<Feature>
client.ogcApi.itemsUrl(path: string, collection: string, params?: OgcItemsParams): string

item() 读取单个要素；itemsUrl() 只生成 items 地址（不发请求、不带 Key），交给第三方库读取时用 client.withKey() 补 Key。

ogcApi.tileMatrixSets()、ogcApi.tileMatrixSet()

client.ogcApi.tileMatrixSets(path: string): Promise<OgcTileMatrixSets>
client.ogcApi.tileMatrixSet(path: string, id: string): Promise<Record<string, unknown>>

矩阵集列表与定义：内置 WebMercatorQuad、WorldCRS84Quad、CGCS2000Quad，预切服务另有按切片方案推导的矩阵集。

ogcApi.tilesets()、ogcApi.tileset()

client.ogcApi.tilesets(path: string, collection?: string, kind?: 'vector' | 'map'): Promise<OgcTileSets>
client.ogcApi.tileset(path: string, tileMatrixSet: string, options?: { collection?: string; kind?: 'vector' | 'map' }): Promise<OgcTileSet>

瓦片集列表与元数据。collection 不给时为整个服务；kind 为 'vector'（默认，矢量瓦片；服务没有矢量瓦片时同地图瓦片）或 'map'（地图瓦片）。元数据中有瓦片地址模板（links 中 rel: 'item'）、各级行列范围 tileMatrixSetLimits、经纬度范围 boundingBox 与矢量瓦片的图层 layers。在 MapLibre 中直接加载请用 maplibre.addOgcApiTiles()。

const meta = await client.ogcApi.tileset('city-roads', 'WebMercatorQuad')
console.log(meta.dataType, meta.layers?.map((l) => l.id))

client.openlayers

在 OpenLayers 中使用 WMTS 与 OGC API Features。SDK 不包含 OpenLayers：每个方法的第一个参数是你用到的 ol 模块成员（见各方法的示例），使用 TypeScript 时返回值是 OpenLayers 自己的类型。

openlayers.wmtsSource()

client.openlayers.wmtsSource(ol, path: string, options?: OlWmtsOptions): Promise<WMTS>

读取 WMTS 能力文档，用 OpenLayers 的 WMTSCapabilities 与 optionsFromCapabilities 生成 WMTS 源，支持能力文档中的全部矩阵集。服务需要开启 WMTS。

参数	说明
`ol`	`{ WMTSCapabilities, WMTS, optionsFromCapabilities }`；用 `<script>` 引入 OpenLayers 全量包时也可以直接传全局变量 `ol`
`options.layer`	图层标识，默认第一个图层
`options.matrixSet`	矩阵集：`GoogleMapsCompatible` / `WebMercatorQuad`（EPSG:3857）、`WorldCRS84Quad`（经纬度）、`CGCS2000Quad`（EPSG:4490）或预切服务推导的矩阵集；默认 `GoogleMapsCompatible`
`options.format`	瓦片格式（媒体类型），默认图层的第一种
`options.config`	其他交给 `optionsFromCapabilities` 的配置，如 `crossOrigin`
`options.sourceOptions`	合并进 WMTS 源的选项，如 `wrapX`
`options.signal`	读取能力文档的中止信号

行为：

只使用所选格式的瓦片地址（多格式图层不会混用格式）；瓦片地址按 baseUrl 生成。
配置了 Key 时瓦片地址带 token 查询参数（图片请求无法加请求头）。
CGCS2000Quad 需要先用 proj4 在 OpenLayers 中注册 EPSG:4490，否则抛 WMTS_UNSUPPORTED。

错误码：WMTS_UNSUPPORTED（图层或矩阵集不存在、无法生成选项）；能力文档请求失败时同 client.request()。ol 缺少成员时抛 TypeError。

import Map from 'ol/Map'
import View from 'ol/View'
import TileLayer from 'ol/layer/Tile'
import WMTSCapabilities from 'ol/format/WMTSCapabilities'
import WMTS, { optionsFromCapabilities } from 'ol/source/WMTS'

const source = await client.openlayers.wmtsSource({ WMTSCapabilities, WMTS, optionsFromCapabilities }, 'city-basemap', { matrixSet: 'WorldCRS84Quad' })
new Map({ target: 'map', layers: [new TileLayer({ source })], view: new View({ projection: 'EPSG:4326', center: [114.1, 22.4], zoom: 9 }) })

openlayers.ogcApiVectorSource()

client.openlayers.ogcApiVectorSource(ol, path: string, collection: string, options?: OlOgcVectorOptions): VectorSource

OGC API Features 的矢量源：加载时用 ogcApi.allItems() 读取要素（带 Key 的方式同其他请求），转换到视图的投影。服务需要开启 OGC API。

参数	说明
`ol`	`{ VectorSource, GeoJSON }`；按视野加载时另加 `bboxStrategy`（`ol/loadingstrategy` 的 `bbox`）
`options.params`	查询条件，同 `ogcApi.items()` 的 `filter`、`properties`、`datetime` 等
`options.strategy`	`'all'`（默认）一次读取；`'bbox'` 按视野范围读取，视图投影须为 EPSG:3857 或 EPSG:4326
`options.maxFeatures`	每次加载最多读取的要素数，默认 10000
`options.pageSize`	每页条数，默认 1000
`options.sourceOptions`	合并进矢量源的选项
`options.onError`	加载失败时的回调，默认 `console.warn`

抛出：strategy: 'bbox' 但没有给 bboxStrategy 时抛 TypeError。

import VectorLayer from 'ol/layer/Vector'
import VectorSource from 'ol/source/Vector'
import GeoJSON from 'ol/format/GeoJSON'
import { bbox } from 'ol/loadingstrategy'

const source = client.openlayers.ogcApiVectorSource({ VectorSource, GeoJSON, bboxStrategy: bbox }, 'poi', 'pois', { strategy: 'bbox', params: { filter: "类别 = '学校'" } })
map.addLayer(new VectorLayer({ source }))

client.query

query.features()

client.query.features(path: string, layerId: number, params?: QueryParams): Promise<FeatureCollection>

按属性与空间条件查询要素，返回 GeoJSON FeatureCollection。

`params`	类型	默认	说明
`where`	`string`	`'1=1'`	属性条件
`outFields`	`string \| string[]`	`'*'`	返回的字段
`returnGeometry`	`boolean`	`true`	是否返回几何
`geometry`	GeoJSON 几何或 `[minx, miny, maxx, maxy]`	无	空间条件
`spatialRel`	`'intersects' \| 'contains' \| 'within' \| 'envelopeIntersects'`	`'intersects'`	空间关系；也可以直接写 `esriSpatialRel…` 原值
`inSR`	`number`	`4326`	`geometry` 的坐标系（EPSG）
`outSR`	`number`	`4326`	输出坐标系（EPSG）
`orderByFields`	`string`	无	排序，如 `'长度 DESC'`
`objectIds`	`Array<number \| string>`	无	按要素 ID 查询
`resultOffset`	`number`	`0`	分页起点：跳过的要素个数（非负整数）
`resultRecordCount`	`number`	图层上限	本页最多返回的要素个数（正整数），超过图层上限时按上限返回

限制：

单次有上限、可分页：单次最多返回图层的最大要素数（未设置时 1000）。结果被截断时返回值的 properties.exceededTransferLimit 为 true，增大 resultOffset 取下一页；要一次取全请用 query.allFeatures()。未给 orderByFields 时按要素 ID 升序，各页首尾相接。
resultOffset 不是非负整数、resultRecordCount 不是正整数时抛 TypeError。
查询参数编码后超过 2000 个字符时自动改用 POST 表单提交。
geometry 不支持 GeometryCollection，也不支持含多个多边形的 MultiPolygon（抛 TypeError）：请拆分为多次查询，或改用外包框。只含一个多边形的 MultiPolygon 按 Polygon 处理。
layerId 必须是非负整数，否则抛 TypeError。

const fc = await client.query.features('city-roads', 0, { where: "类型 = '主干道'", outFields: ['名称', '长度'] })

// 第 3 页，每页 50 条
const page = await client.query.features('city-roads', 0, { orderByFields: '名称', resultOffset: 100, resultRecordCount: 50 })
if (page.properties?.exceededTransferLimit) console.log('还有下一页')

query.allFeatures()

client.query.allFeatures(path: string, layerId: number, params?: QueryParams, options?: AllFeaturesOptions): Promise<FeatureCollection>

按页依次请求，直到没有更多要素或达到 maxFeatures，把各页合并为一个 FeatureCollection。params 同 query.features()，其中 resultOffset 为起点，resultRecordCount 不生效（用 pageSize）。

`options`	类型	默认	说明
`pageSize`	`number`	图层上限	每页条数（正整数）
`maxFeatures`	`number`	`10000`	最多取回的要素总数（正整数），防止误取整个大图层
`signal`	`AbortSignal`	无	中止后抛 `code === 'ABORTED'` 的错误

达到 maxFeatures 时停止；此时服务端若还有更多，结果的 properties.exceededTransferLimit 为 true。各页串行请求，任一页失败即抛出该页的错误。

const controller = new AbortController()
const schools = await client.query.allFeatures('poi', 0, { where: "类别 = '学校'", outFields: ['名称'] }, { maxFeatures: 50000, signal: controller.signal })
console.log(schools.features.length, schools.properties.exceededTransferLimit)

query.count()

client.query.count(path: string, layerId: number, params?: QueryParams): Promise<number>

满足条件的要素数，不受单次返回上限约束。params 中的 where、geometry、spatialRel、inSR、objectIds 生效。

错误码：响应中没有数字 count 时为 BAD_RESPONSE。

const n = await client.query.count('city-roads', 0, { geometry: [116.3, 39.8, 116.5, 40.0] })

query.feature()

client.query.feature(path: string, layerId: number, id: number | string): Promise<Feature>

按 ID 取单个要素（GeoJSON Feature）。ID 含 % 时会被平台拒绝（400 BAD_PATH）。

const f = await client.query.feature('city-roads', 0, 42)

query.identify()

client.query.identify(path: string, options: IdentifyOptions): Promise<unknown>

MapServer 点击识别，返回平台的 JSON 结果（ArcGIS 风格，results 数组），不是 GeoJSON。

`options`	说明
`point`	点击位置 `[经度, 纬度]`，必填
`map`	MapLibre 地图；给出时从中取当前视野与画布尺寸
`mapExtent`	地图范围 `[minx, miny, maxx, maxy]`（经纬度）；不给 `map` 时必填
`imageDisplay`	画面 `[宽, 高, dpi]`；不给 `map` 时必填
`tolerance`	容差像素，默认 3
`layers`	识别哪些图层，默认 `'visible'`；可写 `'top'`、`'all'` 或 `'visible:0,1'`

抛出：TypeError，既没有 map 也没有同时给出 mapExtent 与 imageDisplay，或 point 不是两个有限数时。

map.on('click', async (e) => {
  const result = await client.query.identify('city-roads', { point: [e.lngLat.lng, e.lngLat.lat], map })
  console.log(result)
})

GeoBridgeError

SDK 的所有请求失败都抛 GeoBridgeError（继承 Error）。

属性	类型	说明
`name`	`'GeoBridgeError'`
`status`	`number`	HTTP 状态码；网络错误、超时、取消等没有响应时为 0。服务以 HTTP 200 返回 `SERVICE_ERROR` 时，取响应体中的数字错误码
`code`	`string`	错误码，见下表
`message`	`string`	说明，其中的 Key 已替换为 `***`
`url`	`string`	请求地址，`token` 参数的值已替换为 `***`

`code`	含义
`TOKEN_REQUIRED`、`TOKEN_INVALID`、`UNAUTHORIZED`、`FORBIDDEN`、`BAD_PATH`、`METHOD_NOT_ALLOWED` 等	平台返回的错误码，原样作为 `code`，见错误码
`SERVICE_ERROR`	服务以 `{"error": …}` 形式返回的错误（可能是 HTTP 200），如服务不存在或已停止
`HTTP_<状态>`	其他非 2xx 响应，且响应体中没有平台错误码，如 `HTTP_404`、`HTTP_500`
`NETWORK`	网络错误或读取响应失败；跨域被浏览器拒绝时也是这个错误
`TIMEOUT`	超过 `timeoutMs`
`ABORTED`	调用方的 `signal` 已中止
`BAD_RESPONSE`	响应不是有效的 JSON，或缺少必要字段
`FOREIGN_URL`	地址不属于本平台，SDK 拒绝发送
`REDIRECT`	平台地址发生了重定向，请把 `baseUrl` 写成最终地址
`ID_CONFLICT`	往地图上加服务或地形时，已有同 id 的数据源或图层
`INVALID_STYLE`	服务样式中有图层缺少 id

try {
  await client.services.list()
} catch (e) {
  if (e instanceof GeoBridge.GeoBridgeError && e.code === 'TOKEN_INVALID') console.warn('Key 无效或不在白名单内')
  else throw e
}

参数不合法（如 layerId 为负数、identify 缺少视野）抛的是 TypeError，不是 GeoBridgeError。区分错误原因的完整示例见访问控制示例。

工具函数

maskToken()

maskToken(url: string): string

把地址中 token 参数（不区分大小写）的值替换为 ***，用于日志与错误上报。

GeoBridge.maskToken('…/tiles.json?token=gb_xxx…') // → '…/tiles.json?token=***'

encodeServicePath()

encodeServicePath(path: string): string

服务路径按 / 分段逐段编码，保留目录分隔的 /（整体编码会得到 %2F，平台不认）。

GeoBridge.encodeServicePath('演示/道路 网') // → '%E6%BC%94%E7%A4%BA/%E9%81%93%E8%B7%AF%20%E7%BD%91'

wmsLayerNames()

wmsLayerNames(layers: ReadonlyArray<{ name?: string } | null | undefined>): string[]

按平台的规则生成 WMS 图层名，与输入的下标对齐：空白、:、, 换成 _；名称为空时为 layer_<下标>；重名的追加 _<下标>。规则见 OGC 服务的名称规则。

const meta = await client.services.layers('city-roads')
const names = GeoBridge.wmsLayerNames(meta.layers) // 与 meta.layers 的顺序一致

toEsriGeometry()

toEsriGeometry(g: Geometry | [number, number, number, number]): { geometry: object; geometryType: string }

把 GeoJSON 几何或外包框转换为平台查询接口使用的 geometry 与 geometryType 参数，供直接调用 REST 接口时使用。限制同 query.features()，不支持的几何抛 TypeError。

GeoBridge.toEsriGeometry([116.3, 39.8, 116.5, 40.0])
// → { geometryType: 'esriGeometryEnvelope', geometry: { xmin: 116.3, ymin: 39.8, xmax: 116.5, ymax: 40.0 } }

spatialRelParam()

spatialRelParam(rel?: 'intersects' | 'contains' | 'within' | 'envelopeIntersects' | string): string

把空间关系的简写转为平台参数值：缺省为 esriSpatialRelIntersects，esriSpatialRel… 原样返回。

GeoBridge.spatialRelParam('within') // → 'esriSpatialRelWithin'

parseWmtsCapabilities()

parseWmtsCapabilities(xml: string): WmtsCapabilities

解析 WMTS 1.0.0 能力文档文本，结果同 services.wmtsCapabilities()。需要 DOMParser；不是 WMTS 能力文档时抛 BAD_RESPONSE。

wmtsGrid()

wmtsGrid(tileMatrixSet: WmtsTileMatrixSet): WmtsGrid | null

判断 WMTS 矩阵集是不是标准网格（Web 墨卡托四叉树，或第 0 级为 2×1 的经纬度四叉树），是则返回网格类别 kind（'webmercator' 或 'geographic'）、每个矩阵对应的级别 levels 与瓦片尺寸；不是时返回 null。

const caps = await client.services.wmtsCapabilities('city-basemap')
for (const s of caps.tileMatrixSets) console.log(s.identifier, GeoBridge.wmtsGrid(s)?.kind ?? '非标准网格')

类型

SDK 附带 TypeScript 类型声明，导出的类型有：GeoBridgeClientOptions、KeyTransport、RequestOptions、RequestQuery、TransformedRequest、ServiceType、AccessLevel、ServiceSummary、ServiceMetadata、MapServerMetadata、LayerMetadata、BBox、Position、Geometry、Feature、FeatureCollection、QueryParams、AllFeaturesOptions、SpatialRel、IdentifyOptions、AddServiceOptions、LayerHandle、MapLike、MapViewLike。

三维（实验功能）相关的类型：ServiceType3D、ProcessingStatus、TilesetServiceMetadata、PointCloudStatus、MeshTerrainLayerJson、RasterTerrainTileJson、ModelPlacement、ServiceModel3D、TerrainMapLike、RasterTerrainOptions，以及 client.cesium 用到的 CesiumLike（SDK 用到的 Cesium 命名空间的最小结构）、CesiumValue、CesiumSceneHost、CesiumSceneLike、CesiumCameraHost、CesiumCameraLike、CesiumTilesetLike、CesiumCartesian3Like、CesiumBoundingSphereLike、CesiumTerrainOptions、CesiumTilesetOptions、PointCloudColorBy、PointCloudStyleOptions、CesiumModelsOptions、CesiumModelsResult、SkippedModel、CesiumFlyToOptions。

OGC 相关的类型：WmtsCapabilities、WmtsLayer、WmtsResourceUrl、WmtsTileMatrixSet、WmtsTileMatrix、WmtsSelectOptions、WmtsGrid、WmtsGridKind、MaplibreWmtsOptions、MaplibreOgcTilesOptions、OgcLink、OgcCollection、OgcCollections、OgcFeatureCollection、OgcItemsParams、OgcAllItemsOptions、OgcTileKind、OgcTileMatrixSets、OgcTileSet、OgcTileSets、CesiumWmtsLike、CesiumWmtsOptions，以及 client.openlayers 用到的 OlWmtsModules、OlWmtsNamespace、OlWmtsOptions、OlVectorModules、OlOgcVectorOptions、OlValue。

ServicesApi、MaplibreApi、QueryApi、CesiumApi、OgcApi、OpenLayersApi 六个类也被导出，它们分别是 client.services、client.maplibre、client.query、client.cesium、client.ogcApi、client.openlayers 的类型，通常不需要自己创建。

API 参考 ​

GeoBridgeClient ​

构造函数 ​

属性 ​

client.transformRequest ​

client.withKey() ​

client.url() ​

client.isPlatformUrl() ​

client.request() ​

client.services ​

services.list() ​

services.extent() ​

services.get() ​

services.layers() ​

services.tileJson() ​

services.styleUrl() ​

services.tileUrl() ​

services.vectorTileUrl() ​

services.wmtsCapabilitiesUrl() ​

services.wmsUrl()、services.wfsUrl() ​

services.wmtsUrl()、services.wcsUrl() ​

services.tmsUrl() ​

services.ogcApiUrl() ​

services.wmtsCapabilities() ​

services.legendUrl() ​

三维服务的地址与元数据 ​

client.maplibre ​

maplibre.serviceStyle() ​

maplibre.mapStyleUrl() ​

maplibre.addVectorTileService() ​

maplibre.addRasterService() ​

maplibre.addWmtsService() ​

maplibre.addOgcApiTiles() ​

maplibre.setRasterTerrain() ​

client.cesium ​

cesium.resource() ​

cesium.terrainProvider() ​

cesium.addTileset() ​

cesium.pointCloudStyle() ​

cesium.addModels() ​

cesium.flyToExtent() ​

cesium.wmtsImageryProvider() ​

placementLocalMatrix() ​

client.ogcApi ​

ogcApi.landing()、ogcApi.conformance() ​

ogcApi.collections()、ogcApi.collection()、ogcApi.queryables() ​

ogcApi.items() ​

ogcApi.allItems() ​

ogcApi.item()、ogcApi.itemsUrl() ​

ogcApi.tileMatrixSets()、ogcApi.tileMatrixSet() ​

ogcApi.tilesets()、ogcApi.tileset() ​

client.openlayers ​

openlayers.wmtsSource() ​

openlayers.ogcApiVectorSource() ​

client.query ​

query.features() ​

query.allFeatures() ​

query.count() ​

query.feature() ​

query.identify() ​

GeoBridgeError ​

工具函数 ​

maskToken() ​

encodeServicePath() ​

wmsLayerNames() ​

toEsriGeometry() ​

spatialRelParam() ​

parseWmtsCapabilities() ​

wmtsGrid() ​

类型 ​

API 参考

GeoBridgeClient

构造函数

属性

client.transformRequest

client.withKey()

client.url()

client.isPlatformUrl()

client.request()

client.services

services.list()

services.extent()

services.get()

services.layers()

services.tileJson()

services.styleUrl()

services.tileUrl()

services.vectorTileUrl()

services.wmtsCapabilitiesUrl()

services.wmsUrl()、services.wfsUrl()

services.wmtsUrl()、services.wcsUrl()

services.tmsUrl()

services.ogcApiUrl()

services.wmtsCapabilities()

services.legendUrl()

三维服务的地址与元数据

client.maplibre

maplibre.serviceStyle()

maplibre.mapStyleUrl()

maplibre.addVectorTileService()

maplibre.addRasterService()

maplibre.addWmtsService()

maplibre.addOgcApiTiles()

maplibre.setRasterTerrain()

client.cesium

cesium.resource()

cesium.terrainProvider()

cesium.addTileset()

cesium.pointCloudStyle()

cesium.addModels()

cesium.flyToExtent()

cesium.wmtsImageryProvider()

placementLocalMatrix()

client.ogcApi

ogcApi.landing()、ogcApi.conformance()

ogcApi.collections()、ogcApi.collection()、ogcApi.queryables()

ogcApi.items()

ogcApi.allItems()

ogcApi.item()、ogcApi.itemsUrl()

ogcApi.tileMatrixSets()、ogcApi.tileMatrixSet()

ogcApi.tilesets()、ogcApi.tileset()

client.openlayers

openlayers.wmtsSource()

openlayers.ogcApiVectorSource()

client.query

query.features()

query.allFeatures()

query.count()

query.feature()

query.identify()

GeoBridgeError

工具函数

maskToken()

encodeServicePath()

wmsLayerNames()

toEsriGeometry()

spatialRelParam()

parseWmtsCapabilities()

wmtsGrid()

类型