---
title: "MaplibreTiandituLayer"
description: "Render Tianditu WMTS basemaps (vector, imagery, terrain) with optional matching annotation overlays."
canonical_url: "https://maplibre.mhaibaraai.cn/en/docs/extensions/tianditu"
---
# MaplibreTiandituLayer

> Render Tianditu WMTS basemaps (vector, imagery, terrain) with optional matching annotation overlays.

## Introduction

`MaplibreTiandituLayer` renders Tianditu WMTS tiles as a basemap: `layer` selects the type (`vec` vector / `img` imagery / `ter` terrain, plus annotation variants `cva`/`cia`/`cta`), `annotation` overlays the matching annotation layer, and `tk` falls back to the runtime config `maplibre.tk` when omitted.

> [!NOTE]
> 
> Tianditu uses the WGS84 (CGCS2000) datum — your own WGS84 data overlays directly with no conversion needed. Only Amap / Tencent (GCJ02) or Baidu (BD09) data needs 
> 
> Coordinate Conversion
> 
>  first.

## Usage

Toggle `layer` to preview vector, imagery, and terrain basemaps (all with annotation overlay):

```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>
```

## As a basemap style

`tiandituStyle(layer, { annotation, tk })` assembles a Tianditu basemap and its annotation into a complete style object, usable directly as the `options.style` of `MaplibreMap` or as an item in [MaplibreBasemapControl](https://maplibre.mhaibaraai.cn/docs/controls/basemap-control) next to vector styles. The style's `glyphs` come from the runtime config, so text layers can be overlaid.

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

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

Layer ids in the style follow `tianditu-<type>`: the basemap is `tianditu-vec` / `tianditu-img` / `tianditu-ter`, and the annotation is `tianditu-cva` / `tianditu-cia` / `tianditu-cta`. Match them by id in the `styleLayers` of [MaplibreLayerGroup](https://maplibre.mhaibaraai.cn/docs/core/layer-group) to put the annotation under group control:

```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="Labels" :style-layers="isAnnotation" :legend="[]" />
</template>
```

> [!NOTE]
> 
> Tianditu serves raster tiles: roads and similar features are drawn into the basemap tiles and cannot be controlled separately as in vector styles.

> [!TIP]
> 
> Use 
> 
> MaplibreTiandituLayer
> 
>  to overlay Tianditu on another basemap; use 
> 
> tiandituStyle
> 
>  when Tianditu should be a switchable basemap.

## 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.