tianditumap-vue

天地图 JavaScript API 4.x 的 Vue 封装组件（基于 vue-demi），支持 Vue 2.6+ 与 Vue 3.2+。支持矢量/影像底图、标注与信息窗、内置地名搜索、滚轮与缩放控件等。

安装

npm install tianditumap-vue

Peer 依赖： vue@^2.6.0 || ^3.2.0。若使用 Vue 2.6，需自行安装并注册 @vue/composition-api（见下文 Vue 2 示例）。Vue 2.7+ 与 Vue 3 一般无需再装。

全局注册（推荐）

在入口文件中传入天地图 密钥 tk，以及可选的 API 脚本版本 version（对应 https://api.tianditu.gov.cn/api?v=，默认 4.0）。

注册后，各 <tianditu-map> 可省略 tk；若某个页面需单独指定密钥，仍可通过组件 tk 属性覆盖。

Vue 3（main.ts / main.js）

import { createApp } from 'vue'
import App from './App.vue'
import VueTianditu from 'tianditumap-vue'

const app = createApp(App)
app.use(VueTianditu, {
  tk: '你在天地图控制台申请的密钥',
  version: '4.0', // 可选，默认即为 4.0
})
app.mount('#app')

Vue 2.6（main.js）

必须先注册 Composition API，再注册本插件：

import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import VueTianditu from 'tianditumap-vue'
import App from './App.vue'

Vue.use(VueCompositionAPI)

Vue.use(VueTianditu, {
  tk: '你在天地图控制台申请的密钥',
  version: '4.0',
})

new Vue({
  render: (h) => h(App),
}).$mount('#app')

Vue 2.7（main.js）

内置 Composition API，可直接：

import Vue from 'vue'
import VueTianditu from 'tianditumap-vue'
import App from './App.vue'

Vue.use(VueTianditu, { tk: '你的密钥', version: '4.0' })

new Vue({
  render: (h) => h(App),
}).$mount('#app')

局部注册

未使用 Vue.use / app.use 时，可单独引入组件，并在每个实例上设置 tk（或在 use 中已配置全局 tk 则可省略）：

import { TiandituMap } from 'tianditumap-vue'

使用示例

Vue 3（<script setup>）

<template>
  <tianditu-map
    :lng="116.39"
    :lat="39.9"
    :zoom="12"
    :markers="markers"
    :map-type="mapType"
    width="100%"
    height="480px"
    :show-search-bar="true"
    :search-zoom="14"
    @ready="onReadyHandle"
    @error="onError"
  />
  <button type="button" @click="mapType = mapType === 'vector' ? 'satellite' : 'vector'">
    切换影像
  </button>
  <button type="button" @click="markers = []">清空标注</button>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { TiandituMapReadyApi, TiandituMarkerData } from 'tianditumap-vue'

const mapType = ref<'vector' | 'satellite'>('vector')

const markers = ref<TiandituMarkerData[]>([
  {
    id: 1,
    lng: 116.4,
    lat: 39.91,
    label: '文字标注',
    labelOffset: { x: 10, y: -22 },
    infoContent: '<p><b>信息框</b>（点击标记显示）</p>',
    infoOffset: { x: 0, y: -30 },
    iconUrl: 'https://api.tianditu.gov.cn/img/map/markerA.png',
    iconSize: { width: 19, height: 27 },
    iconAnchor: { x: 10, y: 25 },
  },
])

function onReadyHandle({ map }: TiandituMapReadyApi) {
  // 需要直接操作天地图 JS 实例时保存 map（Vue 2 / 3 均如此）
}

function onError(err: unknown) {
  console.error(err)
}
</script>

Vue 2（Options API）

<template>
  <div>
    <tianditu-map
      :lng="116.39"
      :lat="39.9"
      :zoom="12"
      :markers="markers"
      map-type="vector"
      width="100%"
      height="480px"
      @ready="onMapReady"
      @error="onMapError"
    />
  </div>
</template>

<script>
export default {
  data() {
    return {
      markers: [
        {
          id: 1,
          lng: 116.4,
          lat: 39.91,
          label: '示例点',
          labelOffset: { x: 10, y: -20 },
          infoContent: '<p>信息框</p>',
        },
      ],
    }
  },
  methods: {
    onMapReady(payload) {
      this.tdtMap = payload.map
    },
    onMapError(e) {
      console.error(e)
    },
  },
}
</script>

模板中建议使用 kebab-case 写法：map-type、show-search-bar、search-zoom。

批量增删标注

只需在父组件中维护 markers 数组：增删改后组件会自动同步（支持深度监听）。例如：

markers.value.push({ id: Date.now(), lng: 116.41, lat: 39.92, label: '新点' })
markers.value = markers.value.filter((m) => m.id !== 1)

组件主要属性

| 属性 | 类型 | 默认 | 说明 | |------|------|------|------| | tk | string | '' | 天地图密钥；已在 app.use / Vue.use 中配置时可省略 | | lng / lat | number | 北京附近 | 初始中心 | | zoom | number | 12 | 初始级别 | | markers | TiandituMarkerData[] | [] | 标注数据 | | mapType | 'vector' \| 'satellite' | 'vector' | 矢量 / 影像 | | width / height | string | '100%' / '400px' | 容器尺寸 | | searchZoom | number | 14 | 地名搜索成功后的缩放级别 | | showSearchBar | boolean | true | 是否显示左上角搜索框 |

标注项 TiandituMarkerData 主要字段：lng、lat、offset、iconUrl、iconSize、iconAnchor、label、labelOffset、infoContent、infoOffset、id。

事件

| 事件 | 参数 | 说明 | |------|------|------| | ready | { map } | 地图创建完成；map 为天地图实例 | | error | unknown | 初始化或图层切换等异常 |

TypeScript

库会导出类型，例如：TiandituMarkerData、TiandituMapLayerMode、TiandituMapReadyApi、TiandituMapInstance、VueTiandituPluginOptions。

注意事项

1. 地理编码 / 脚本加载依赖天地图服务与密钥配置，若遇浏览器 CORS 或配额问题，请在天地图控制台检查域名白名单，或改为服务端代理请求。
2. 同一页面建议只使用一种 version 加载脚本；切换 mapType 时组件会尽量保留当前中心与级别。
3. 发布前请在项目根目录执行 npm install 与 npm run build，确保 dist 为最新构建产物。

License

MIT