---
title: "MaplibreTiandituLayer"
description: "以天地图 WMTS 瓦片作底图，支持矢量/影像/地形及对应注记叠加。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/extensions/tianditu"
---
# MaplibreTiandituLayer

> 以天地图 WMTS 瓦片作底图，支持矢量/影像/地形及对应注记叠加。

## 简介

`MaplibreTiandituLayer` 以天地图 WMTS 瓦片作底图：`layer` 选类型（`vec` 矢量 / `img` 影像 / `ter` 地形，及注记 `cva`/`cia`/`cta`），`annotation` 叠加对应注记层，`tk` 缺省时回退运行时配置 `maplibre.tk`。

> [!NOTE]
> 
> 天地图坐标系为 WGS84（CGCS2000），自有 WGS84 数据可直接叠加，无需 
> 
> 坐标转换
> 
> ；只有高德 / 腾讯（GCJ02）、百度（BD09）的数据叠加时才需要先转换。

## 用法

切换 `layer` 查看矢量/影像/地形底图（均叠加注记）：

```vue [TiandituLayerExample.vue]
<script setup lang="ts">
withDefaults(defineProps <{
  layer?: 'vec' | 'img' | 'ter'
  annotation?: boolean
}> (), {
  layer: 'vec',
  annotation: true
})
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ center: [116.397, 39.908], zoom: 10 }">
      <MaplibreTiandituLayer
        :layer="layer"
        :annotation="annotation"
      />
    </MaplibreMap>
  </div>
</template>
```

## 作为底图样式

`tiandituStyle(layer, { annotation, tk })` 把天地图底图与注记组装成完整的样式对象，可以直接作为 `MaplibreMap` 的 `options.style`，或放进 [MaplibreBasemapControl](https://maplibre.mhaibaraai.cn/docs/controls/basemap-control) 与矢量样式一起切换。样式中的 `glyphs` 取自运行时配置，便于叠加文字图层。

```ts
import { tiandituStyle } from '@movk/maplibre/utils/tianditu'

const imagery = tiandituStyle('img', { annotation: true })
```

样式中的图层 id 为 `tianditu-<type>`：底图是 `tianditu-vec` / `tianditu-img` / `tianditu-ter`，注记是 `tianditu-cva` / `tianditu-cia` / `tianditu-cta`。在 [MaplibreLayerGroup](https://maplibre.mhaibaraai.cn/docs/core/layer-group) 的 `styleLayers` 中按 id 匹配，就能把注记纳入图层组控制：

```vue
<script setup lang="ts">
import type { LayerSpecification } from 'maplibre-gl'

const isAnnotation = (layer: LayerSpecification) => /^tianditu-c[vit]a$/.test(layer.id)
</script>

<template>
  <MaplibreLayerGroup title="注记" :style-layers="isAnnotation" :legend="[]" />
</template>
```

> [!NOTE]
> 
> 天地图是栅格瓦片，道路等要素直接绘制在底图瓦片中，无法像矢量样式那样单独控制。

> [!TIP]
> 
> 需要在其他底图上叠加天地图时使用 
> 
> MaplibreTiandituLayer
> 
> ；需要把天地图作为可切换的底图时使用 
> 
> tiandituStyle
> 
> 。

## API

### Props

```ts
/**
 * Props for the MaplibreTiandituLayer component
 */
interface MaplibreTiandituLayerProps {
  /**
   * 天地图图层类型（vec 矢量底图）
   * @default 'vec'
   */
  layer?: "vec" | "img" | "ter" | "cva" | "cia" | "cta" | undefined;
  /**
   * 天地图 token；缺省时回退运行时配置
   */
  tk?: string | undefined;
  /**
   * 叠加对应注记图层（vec→cva / img→cia / ter→cta）
   * @default false
   */
  annotation?: boolean | undefined;
  /**
   * 插入到该图层之前
   */
  beforeId?: string | undefined;
}
```

## Changelog

See commit history for [src/runtime/components/extensions/TiandituLayer.vue](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/components/extensions/TiandituLayer.vue).


## Sitemap

See the full [sitemap](https://maplibre.mhaibaraai.cn/sitemap.md) for all pages.