tdt-map-vue

tdt-map-vue 是一个基于 Vue 2 / Vue 3 的天地图（Tianditu）地图组件库，适合快速集成到后台管理系统、地理信息展示页面、业务看板等项目中。

它对天地图常用能力做了二次封装，包括地图初始化、标注管理、文字标签、信息窗体、地理编码搜索，以及通过 ref 调用组件方法进行二次控制。

特性

• 同时兼容 Vue 2 与 Vue 3，可直接在不同版本项目中复用
• 自动加载天地图 JS API，无需在业务项目里手动引入脚本
• 支持地图初始化，并可配置中心点、缩放级别、最小/最大缩放范围
• 支持拖拽、滚轮缩放、缩放控件等常用地图交互能力
• 支持自定义标注图标、文字标签、信息窗内容
• 支持新增标注、隐藏标注、获取全部标注和销毁地图实例
• 支持地理编码搜索，可根据地址关键字快速定位
• 支持通过 ref 调用组件公开方法，便于在业务代码中做二次控制
• 提供稳定的 npm 发布结构，便于在 Vue 2 / Vue 3 项目中直接安装使用

安装

npm install tdt-map-vue  --save

如果你使用的是 Vue 3 项目，通常只需要正常安装即可；如果是 Vue 2 项目，则需要确保 vue-demi 的运行环境配置正确。组件库内部通过 vue-demi 做了兼容处理，因此同一套 API 可以在两种版本中使用。

安装说明

• Vue 2：确保项目中已正确配置 vue-demi 和 vue-template-compiler 所需环境
• Vue 3：正常安装即可

组件库通过 vue-demi 处理 Vue 2 / Vue 3 兼容场景。

构建说明

本项目发布时只生成一套稳定的构建产物：

• dist/index.cjs.js
• dist/index.es.js
• dist/index.umd.js

package.json 中已经通过 main、module 和 exports 配好了入口，Vue 2 和 Vue 3 项目都可以直接安装并使用同一个包名。

如果你是在本地调试构建结果，可以直接检查：

• CommonJS 入口：dist/index.cjs.js
• ESM 入口：dist/index.es.js
• UMD 产物：dist/index.umd.js

注意：Vue 2 项目应优先使用 require / main 对应的 CJS 入口；Vue 3 项目优先使用 import / module 对应的 ESM 入口。

快速开始

下面分别给出 Vue 2 和 Vue 3 的使用方式。无论哪种版本，都可以通过组件形式直接渲染地图，并通过 tk 传入天地图 API Key。

全局注册

import Vue from "vue";
import TiandiMap from "tdt-map-vue";

Vue.use(TiandiMap);

Vue 3 局部注册

<template>
  <TiandiMap tk="your-tianditu-api-key" :zoom="12" />
</template>

<script>
import TiandiMap from "tdt-map-vue";

export default {
  components: {
    TiandiMap,
  },
};
</script>

Vue 2 局部注册

<template>
  <TiandiMap tk="your-tianditu-api-key" :zoom="12" />
</template>

<script>
import TiandiMap from "tdt-map-vue";

export default {
  components: {
    TiandiMap,
  },
};
</script>

通过 ref 调用方法

组件支持通过 ref 直接调用实例方法，这也是它比较适合做业务封装的原因之一。比如你可以在按钮点击后新增标注、清空搜索条件、重新计算地图尺寸，或者根据外部业务状态控制地图行为，而不必把逻辑全部写死在地图组件内部。

常用方法

• addMarkers(markers)：新增标注
• clearSearch()：清空搜索框
• geocodeSearch(keyword)：地理编码搜索
• hideMarkers(markers)：隐藏标注
• getAllMarkers()：获取全部标注
• setCenterAndZoom(center, zoom)：设置地图中心点和缩放级别
• getPickupPoint()：获取当前拾取到的坐标点
• destroyMap()：销毁地图
• resizeMap()：重新计算地图尺寸

方法使用示例

下面给出几个最常用的方法调用示例，方便父组件通过 ref 直接控制地图。

1. 新增标注 addMarkers(markers)

markers 参数是一个数组，每一项的格式如下：

[
  {
    id: "marker-1",
    lng: 116.397428,
    lat: 39.90923,
    option: {
      content: "<div>北京</div>",
      iconInfo: {
        icon: "https://example.com/icon.png",
        offsetX: 32,
        offsetY: 32,
      },
      textInfo: {
        text: "北京",
        offsetX: 0,
        offsetY: -30,
      },
    },
  },
];

Vue 3 调用示例：

<template>
  <div>
    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" />
    <button @click="addMarker">新增标注</button>
  </div>
</template>

<script setup>
import { ref } from "vue";
import TiandiMap from "tdt-map-vue";

const mapRef = ref(null);

const addMarker = () => {
  mapRef.value?.addMarkers([
    {
      id: "marker-1",
      lng: 116.397428,
      lat: 39.90923,
      option: {
        content: "<div>北京</div>",
      },
    },
  ]);
};
</script>

2 设置中心点 setCenterAndZoom(center, zoom)

• center：数组，格式为 [lng, lat]
• zoom：缩放级别，类型为 number

<template>
  <div>
    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" />
    <button @click="goToCity">定位到城市</button>
  </div>
</template>

<script setup>
import { ref } from "vue";
import TiandiMap from "tdt-map-vue";

const mapRef = ref(null);

const goToCity = () => {
  mapRef.value?.setCenterAndZoom([117.017362, 25.075884], 12);
};
</script>

3 获取拾取坐标 getPickupPoint()

getPickupPoint(callback) ，传入要执行的回调时事件会传入刚刚拾取的坐标,不传入则直接返回坐标点数据

<template>
  <div>
    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" />
    <button @click="getPickedPoint">获取拾取坐标</button>
  </div>
</template>

<script setup>
import { ref } from "vue";
import TiandiMap from "tdt-map-vue";

const mapRef = ref(null);

const getPickedPoint = () => {
  mapRef.value?.getPickupPoint(getFunc); // 传入要执行的回调函数
};
// 回调函数的入参为获取到的坐标点对象
{
  lng: 117.017362,
  lat: 25.075884
}
// 
const getFunc = (point) => {
  console.log("获取到了坐标====", point);
  mapRef.value.addMarkers([
    {
      ...point,
      option: {
        content: "<div> 新增坐标点</div>",
      },
    },
  ]);
};
</script>

4 隐藏标注 hideMarkers(markers)

markers 参数是一个数组，通常只需要传入要隐藏标注的 id。

[{ id: "marker-1" }, { id: "marker-2" }];

<template>
  <div>
    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" />
    <button @click="hideMarker">隐藏标注</button>
  </div>
</template>

<script setup>
import { ref } from "vue";
import TiandiMap from "tdt-map-vue";

const mapRef = ref(null);

const hideMarker = () => {
  mapRef.value?.hideMarkers([ "marker-1" ]);
};
</script>

Vue 3 示例

<template>
  <div>
    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" :zoom="12" />
    <button @click="addMarker">添加标注</button>
  </div>
</template>

<script>
import { ref } from "vue";
import TiandiMap from "tdt-map-vue";

export default {
  components: {
    TiandiMap,
  },
  setup() {
    const mapRef = ref(null);

    const addMarker = () => {
      mapRef.value?.addMarkers([
        {
          lng: 116.397428,
          lat: 39.90923,
          option: {
            content: "<div>北京</div>",
          },
        },
      ]);
    };

    return {
      mapRef,
      addMarker,
    };
  },
};
</script>

Vue 2 示例

<template>
  <div>
    <TiandiMap ref="mapRef" tk="your-tianditu-api-key" :zoom="12" />
    <button @click="addMarker">添加标注</button>
  </div>
</template>

<script>
export default {
  methods: {
    addMarker() {
      this.$refs.mapRef.addMarkers([
        {
          lng: 116.397428,
          lat: 39.90923,
          option: {
            content: "<div>北京</div>",
          },
        },
      ]);
    },
  },
};
</script>

Props

这些属性用于控制地图的初始状态和交互行为。对于大多数业务场景，你只需要传入 tk、中心点和缩放级别即可；如果需要更强的定制能力，还可以继续配置标注、拖拽、滚轮缩放等选项。

| 参数 | 类型 | 默认值 | 说明 | | ----------------- | --------- | ----------------------------------- | ---------------- | | tk | String | 必填 | 天地图 API Key | | version | String | 4.0 | 天地图 API 版本 | | containerStyle | Object | { width: '100%', height: '100%' } | 地图容器样式 | | center | Array | [117.017362,25.075884] | 地图中心点经度 | | zoom | Number | 10 | 初始缩放级别 | | minZoom | Number | 1 | 最小缩放级别 | | maxZoom | Number | 18 | 最大缩放级别 | | markers | Array | [] | 初始标注数组 | | dragEnable | Boolean | true | 是否允许拖拽 | | scrollWheelZoom | Boolean | true | 是否允许滚轮缩放 |

Events

组件在地图初始化、标注点击、搜索结果和异常场景下都会向外抛出事件，便于业务层统一处理状态、提示信息和联动操作。

| 事件名 | 参数 | 说明 | | ---------------- | ------------------------- | -------------------------- | | ready | (map) | 地图初始化完成 | | error | (error) | 地图初始化、加载或搜索失败 | | marker-click | ({ markerData, event }) | 标注点击事件 | | addsuccess | (markers) | 新增标注成功 | | hidesuccess | () | 隐藏标注成功 | | search-success | (location) | 地理编码搜索成功 | | search-error | (error) | 地理编码搜索失败 |

天地图原生对象说明

在组件初始化完成后，你可以通过 ready 事件拿到地图实例 map，并进一步调用天地图原生 API。

常见对象包括：

• window.T.Map：地图对象
• window.T.Marker：标记对象
• window.T.InfoWindow：信息窗口对象
• window.T.LngLat：经纬度对象
• window.T.Point：点位 / 偏移对象

map 是天地图的地图实例，可以直接拿来调用原生 API。

使用建议

• 地图容器必须有明确高度，否则地图不会显示
• tk 必须替换成你自己的天地图 API Key
• 如果需要在 Vue 2 项目中使用，请确保安装了 vue-template-compiler 且版本与 vue 保持一致
• 如果你最近刚发布过新版本，但本地项目还是旧代码，请先删除缓存并重新安装依赖
• 如果你要在父组件里拿到拾取坐标，可以通过 ref 调用 getPickupPoint()
• 如果你想拿到天地图拾取回调中的原始坐标对象，可以结合 ready 事件和组件实例方法做二次封装

常见问题

下面整理了一些接入时最容易遇到的问题，建议在安装和使用前先快速浏览一遍，可以节省很多排查时间。

1. Vue 2 项目里能用吗？

可以，当前组件库就是按 Vue 2 / Vue 3 双兼容方向整理的。

2. Vue 3 能通过 ref 调用方法吗？

可以，直接通过 ref 访问组件实例并调用公开方法。

3. 地图不显示怎么办？

请检查以下几点：

• tk 是否填写正确
• 页面容器是否设置了高度
• 天地图 API 是否能正常加载
• 当前网络环境是否允许访问天地图资源

4. 标注不显示怎么办？

请确认：

• lng 和 lat 是数字
• markers 是数组
• 地图已经初始化完成

License

MIT