VTianditu 天地图

Tianditu 是中国国家测绘局提供的一套在线地图服务，包括矢量地图、影像地图、地形地图、地名标注等。

天地图地图服务 API

天地图的最大缩放级别？

• 矢量地图（vec_w）：最高层级为 18。
• 影像地图（img_w）：最高层级为 18。
• 地形图（ter_w）：最高层级为 14。

天地图的访问协议（WMTS URL 和 标准 URL 模板）？

特性	WMTS URL（vec_c/wmts）	标准 URL 模板（vec_w）
访问协议	WMTS（OGC 标准协议）	标准 HTTP/HTTPS 请求
适合的应用	GIS 软件（如 ArcGIS、QGIS）	Web 地图库（如 Mapbox GL JS、Leaflet）
请求参数	SERVICE, REQUEST, TILEMATRIX, TILEROW, TILECOL	x, y, z 或 {x}, {y}, {z}
子域支持	单一子域，较低并发请求能力	多子域（t0-t7），高并发请求能力
加载速度	较慢（尤其在高并发请求时）	较快，适合需要快速响应的前端应用
配置难度	较高，需要 WMTS 特定参数配置	较低，URL 模板简单适配 Web 地图库

---

推荐选择

• GIS 系统和 OGC 标准应用：选择 vec_c/wmts。
• 基于 Web 的前端地图库：选择 vec_w 标准 URL 模板，因为它更易集成，加载速度更快。

基础用法

tianditu-base.vue

<script lang="ts" setup>
import { getTdtRandomToken } from '@movk-repo/libs'
import { VMapbox, VTianditu } from '@movk-repo/mapbox'

const accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN
const token = getTdtRandomToken()
</script>

<template>
  <VMapbox :access-token="accessToken">
    <VTianditu :token="token" />
  </VMapbox>
</template>

隐藏源代码

动态切换地图类型

tianditu-dynamic.vue

<script lang="ts" setup>
import type { MapboxProps, TiandituProps } from '@movk-repo/mapbox'
import type { ProjectionSpecification } from 'mapbox-gl'
import type { PlusColumn } from 'plus-pro-components'
import { getTdtRandomToken } from '@movk-repo/libs'
import { VMapbox, VTianditu } from '@movk-repo/mapbox'

const accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN
const token = getTdtRandomToken()

const options: MapboxProps['defaultOptions'] = {
  zoom: 11.704541073088237,
  center: [117.09355096461081, 36.23562770625041],
  pitch: 59.00000000000005,
  bearing: 0,
}

const formData = ref({
  projection: 'mercator' as ProjectionSpecification['name'],
  type: 'img_w' as TiandituProps['type'],
  anno: true,
  visible: true,
  terrain: false,
})

const columns: PlusColumn[] = [
  {
    label: '地图投影',
    prop: 'projection',
    valueType: 'radio',
    options: [
      { label: '地球投影(globe)', value: 'globe' },
      { label: '墨卡托(mercator)', value: 'mercator' },
    ],
    colProps: { span: 24 },
  },
  {
    label: '底图类型',
    prop: 'type',
    valueType: 'radio',
    options: [
      { label: '矢量底图', value: 'vec_w' },
      { label: '影像底图', value: 'img_w' },
      { label: '地形底图', value: 'ter_w' },
    ],
    colProps: { span: 24 },
  },
  {
    label: '是否显示',
    prop: 'visible',
    valueType: 'switch',
  },
  {
    label: '是否显示注记',
    prop: 'anno',
    valueType: 'switch',
  },
  {
    label: '是否显示地形',
    prop: 'terrain',
    valueType: 'switch',
  },
]
</script>

<template>
  <VMapbox :default-options="options" :access-token="accessToken" :projection="formData.projection">
    <VTianditu
      :token="token" :type="formData.type" :anno="formData.anno" :visible="formData.visible" :terrain="formData.terrain"
    />
    <template #before>
      <PlusForm
        v-model="formData" :row-props="{ gutter: 20 }" :col-props="{ span: 8 }" :columns="columns"
        :has-footer="false" label-width="auto"
      />
    </template>
  </VMapbox>
</template>

隐藏源代码

Api

TiandituProps

属性名	说明	类型	默认值
token	天地图密钥	string	必填
type	天地图类型	enum	vec_w
anno	是否显示注记	boolean	true
visible	天地图可见性	boolean	true
terrain	是否显示地形	boolean	false
opacity	天地图透明度	number	1
order	天地图顺序	number	-
minzoom	最小缩放级别	number	0
maxzoom	最大缩放级别	number	18
tilesUrl	服务地址	string	https://[t0-t7].tianditu.gov.cn
subdomains	服务负载子域	array	0-7
baseSourceOptions	底图源配置	object	-
baseLayerOptions	底图图层配置	object	-
annoSourceOptions	标注源配置	object	-
annoLayerOptions	标注图层配置	object	-
terrainSourceOptions	地形源配置	object	-

说明

• visible、opacity、order、minzoom、maxzoom 等属性用于控制底图和标注的显示与行为。
• baseSourceOptions 、 baseLayerOptions 、 annoSourceOptions 、 annoLayerOptions 用于单独配置底图和标注的源选项。

TiandituEmits

事件名	说明	回调参数
load	地图加载完成后执行	Function

类型定义

源与图层的 ID

constant/index.ts

export const tianditu = {
  TIANDITU: 'tianditu',
  TIANDITU_ANNO: 'tianditu_anno',
} as const

TiandituLoadEvent

basemap/Tianditu/Tianditu.ts

export interface TiandituLoadEvent {
  map: Map
  base: RasterLayerLoadEvent
  anno?: RasterLayerLoadEvent
}