vue-tianditu-component

一个基于 Vue 2 / Vue 3 的天地图（Tianditu）组件库，支持地图初始化、标注管理、地理编码搜索以及通过 ref 调用组件方法，适合以 npm 包形式集成到第三方项目中。

特性

• 同时兼容 Vue 2 与 Vue 3
• 支持天地图 API 自动加载
• 支持地图初始化、缩放、拖拽、滚轮缩放
• 支持自定义标注、文字标签、信息窗
• 支持新增标注、隐藏标注、获取全部标注
• 支持地理编码搜索
• 支持通过 ref 调用组件方法

安装

npm install vue-tianditu-component vue-demi --save

安装说明

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

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

快速开始

Vue 2 全局注册

import Vue from 'vue'
import TiandiMap from 'vue-tianditu-component'

Vue.use(TiandiMap)

Vue 2 局部注册

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

<script>
import TiandiMap from 'vue-tianditu-component'

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

Vue 3 局部注册

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

<script>
import TiandiMap from 'vue-tianditu-component'

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

通过 ref 调用方法

组件支持通过 ref 直接调用实例方法。

常用方法

• addMarkers(markers)：新增标注
• clearSearch()：清空搜索框
• geocodeSearch(keyword)：地理编码搜索
• hideMarkers(markers)：隐藏标注
• getAllMarkers()：获取全部标注
• destroyMap()：销毁地图
• resizeMap()：重新计算地图尺寸

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 'vue-tianditu-component'

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 | String | 必填 | 天地图 API Key | | version | String | 4.0 | 天地图 API 版本 | | containerStyle | Object | { width: '100%', height: '100%' } | 地图容器样式 | | centerLng | Number | 117.017362 | 地图中心点经度 | | centerLat | Number | 25.075884 | 地图中心点纬度 | | zoom | Number | 10 | 初始缩放级别 | | minZoom | Number | 1 | 最小缩放级别 | | maxZoom | Number | 18 | 最大缩放级别 | | markers | Array | [] | 初始标注数组 | | showZoom | Boolean | true | 是否显示缩放控件 | | dragEnable | Boolean | true | 是否允许拖拽 | | scrollWheelZoom | Boolean | true | 是否允许滚轮缩放 |

Events

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

标注数据格式

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

构建

npm install
npm run build

构建产物会输出到 dist 目录。

发布前检查

1. 已正确安装依赖
2. 本地执行 npm run build 成功
3. dist 目录已生成
4. package.json 中的入口字段指向正确的构建产物

常见问题

1. Vue 2 项目里能用吗？

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

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

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

3. 地图不显示怎么办？

请检查以下几点：

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

4. 标注不显示怎么办？

请确认：

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

License

MIT